@@ -4,118 +4,23 @@ This file is the single source of truth for how humans and coding agents work
44in this repository. ` CLAUDE.md ` is a symlink to this file, so every agent reads
55the same instructions.
66
7- When you generate a new project from this template, keep this file and adapt
8- the project-specific parts (crate name, module map, feature flags, commands).
9- Delete guidance that no longer applies rather than leaving it to rot.
10-
11- ## Template Checklist
12-
13- Do this once, in a single commit, before writing feature code:
14-
15- - [ ] Rename ` crates/template ` and ` crates/template-bus ` to the project's crate
16- names, and update ` name ` in each manifest plus the ` template-bus ` entry in
17- the root ` [workspace.dependencies] ` .
18- - [ ] Set ` description ` , ` keywords ` , and ` categories ` in each manifest, and
19- ` repository ` in the root ` [workspace.package] ` .
20- - [ ] Rename the crate references in ` README.md ` , both ` src/lib.rs ` files,
21- ` crates/template/examples/ ` , and ` crates/template/tests/ ` (search for
22- ` template ` and ` template_bus ` ).
23- - [ ] Replace the placeholder ` greeting ` module in both crates with the first
24- real feature area — payload types in the contract crate, behavior in the
25- module crate — keeping the ` mod.rs ` / ` types.rs ` / ` test.rs ` layout.
26- - [ ] Confirm ` license ` and ` LICENSE ` match the project's intended license.
27- - [ ] Update the security contact in ` SECURITY.md ` .
28- - [ ] Rename the TinyBus interface, object path, and member constants in
29- ` crates/template-bus/src/names/ ` , and the matching ` provides ` / ` methods `
30- declarations in ` crates/template/src/tinybus_module/ ` , while keeping
31- ` vendor/tinybus ` pinned.
32- - [ ] Reset ` CONTRACT_VERSION ` in ` crates/template-bus/src/version/ ` for the new
33- contract.
34- - [ ] Replace ` ROADMAP.md ` with the real plan, or delete it.
35- - [ ] Rewrite the "Project Structure" section below to describe this workspace.
36-
377## Project Structure
388
39- This is a Rust 2024 cargo workspace rooted at a virtual ` Cargo.toml ` . Every
40- crate lives under ` crates/ ` , one directory per package, each directory named for
41- the package it holds. There is no root package: the crate that ships as the
42- loadable module is ` crates/template ` , the same as any other member.
43-
44- ``` text
45- Cargo.toml # virtual workspace: members, [workspace.package],
46- # [workspace.dependencies], [workspace.lints]
47- crates/
48- ├── template-bus/ # the wire contract: what crosses the bus, nothing else
49- │ ├── README.md # why the contract is its own crate
50- │ └── src/
51- │ ├── lib.rs # crate docs + the entire public re-export surface
52- │ ├── names/ # interface, object path, one constant per member
53- │ ├── version/ # contract version and the host bind rule
54- │ └── <family>/ # one directory per payload family
55- └── template/ # the module: behavior, adapter, and the cdylib
56- ├── src/
57- │ ├── lib.rs # crate docs + public surface, re-exporting the contract
58- │ ├── error/mod.rs # crate-wide `Error` and `Result<T>`
59- │ ├── tinybus_module/ # TinyBus interface, ABI exports, integration tests
60- │ └── <feature>/ # one directory per feature area
61- │ ├── mod.rs # module docs, wiring, smallest useful public API
62- │ ├── types.rs # substantial type definitions
63- │ └── test.rs # module-local unit tests
64- ├── tests/ # integration tests against the public API only
65- └── examples/ # runnable, compiled-in-CI usage examples
66- vendor/tinybus/ # pinned TinyBus host types and module SDK
67- docs/
68- ├── specs/ # behavior and architecture specifications
69- ├── plans/ # test-first implementation plans
70- └── adr/ # immutable architecture decision records
71- ```
72-
73- ### The two-crate split
74-
75- ` crates/template-bus ` holds every type that crosses the bus and the names of the
76- members that carry them. It has no transport, no runtime, and no behavior, and
77- CI asserts it stays that way. A host that only makes calls depends on it alone.
78-
79- ` crates/template ` depends on it and re-exports all of it, so
80- ` template::GreetRequest ` and ` template_bus::GreetRequest ` are the * same* type
81- rather than structural twins. That direction is load-bearing: a parallel set of
82- payload types for hosts would mean a conversion at every call site that nothing
83- checks.
84-
85- The rule for deciding where something goes: a payload type describes what a
86- frame carries and belongs in the contract; anything that answers a frame, holds
87- a connection, or touches an engine belongs in the module crate.
88-
89- Add a crate by creating ` crates/<name>/ ` — ` members = ["crates/*"] ` picks it up
90- by existing. Inherit ` version ` , ` edition ` , ` rust-version ` , ` license ` , and
91- ` repository ` from ` [workspace.package] ` , take shared dependencies from
92- ` [workspace.dependencies] ` , and opt into the shared lint set with:
93-
94- ``` toml
95- [lints ]
96- workspace = true
97- ```
98-
99- Each feature area belongs in a focused module directory under a crate's ` src/ ` .
100- A module root explains the module, wires its pieces together, and exposes the
101- smallest useful API. Move substantial type definitions into ` types.rs ` and put
102- module-local unit tests in a dedicated ` test.rs ` , wired from the bottom of the
103- module root with:
104-
105- ``` rust
106- #[cfg(test)]
107- mod test ;
108- ```
9+ This Rust 2024 workspace ships a native TinyBus security module.
10910
110- Do not accumulate inline ` mod tests ` blocks in implementation files, and do not
111- let a general-purpose ` utils.rs ` or ` helpers.rs ` grow — those are a symptom of a
112- missing module. Prefer many small modules that each do one thing well over few
113- broad ones.
11+ - ` crates/tinysecurity-bus ` : versioned transport-free contract, normal dependencies serde and thiserror only.
12+ - ` crates/tinysecurity-policy ` : conservative native policy engine.
13+ - ` crates/tinysecurity ` : internal engine re-export, never host-linked.
14+ - ` crates/tinysecurity-module ` : configured TinyBus SDK adapter and cdylib.
15+ - ` vendor/tinybus ` : pinned module SDK and loader, maintained upstream.
16+ - ` docs/specs ` , ` docs/plans ` , ` docs/adr ` : accepted design, ordered implementation and decisions.
11417
115- Keep public exports centralized in each crate's ` src/lib.rs ` so downstream users
116- have one predictable surface. Put shared error variants in
117- ` crates/template/src/error/mod.rs ` and return the crate-wide ` Result<T> ` from
118- fallible public APIs.
18+ Only implemented engines may advertise methods. Unknown effects deny. Module
19+ configuration uses SDK init/reinit, not lifecycle RPCs. Hosts link only the
20+ contract, and production migration requires released artifacts/checksums.
21+ Tests live in sibling ` *_tests.rs ` files or crate ` tests/ ` integration suites;
22+ never use inline modules or ` test.rs ` filenames. Public types have rustdoc.
23+ Do not create empty engine crates or claim full tracker completion at bootstrap.
11924
12025## Build And Test
12126
@@ -133,8 +38,8 @@ Supporting commands:
13338
13439- ` cargo fmt --all ` — format before committing.
13540- ` cargo test <filter> ` — run a focused subset while iterating.
136- - ` cargo test -p template -bus ` — run one crate's suite.
137- - ` cargo run -p template --example basic ` — run the bundled example.
41+ - ` cargo test -p tinysecurity -bus ` — run one crate's suite.
42+ - ` cargo run -p tinysecurity-module --example verify_module -- <native-library> ` — run the bundled example.
13843- ` cargo doc --no-deps --all-features ` — build the rustdoc CI also builds with
13944 ` RUSTDOCFLAGS="-D warnings" ` .
14045- ` cargo test --doc ` — run doctests alone when editing documentation examples.
@@ -185,7 +90,7 @@ add one:
18590- gate anything optional behind a Cargo feature, documented in ` Cargo.toml ` ;
18691- declare it once in the root ` [workspace.dependencies] ` when more than one
18792 crate needs it, and take it with ` { workspace = true } ` ;
188- - never add one to ` crates/template -bus ` that pulls in a transport, an async
93+ - never add one to ` crates/tinysecurity -bus ` that pulls in a transport, an async
18994 runtime, an HTTP client, or a native library — CI fails the build if you do;
19095- leave a comment above the entry explaining * why* the crate is needed and what
19196 uses it — see the existing entries for the expected tone;
@@ -211,15 +116,20 @@ new module capability requires more.
211116
212117## Testing
213118
214- - Module-local unit tests live in ` crates/<crate>/src/<feature>/test.rs ` and may
215- touch private items.
119+ - Module-local unit tests live in sibling ` *_tests.rs ` files and may touch
120+ private items: use ` src/<feature>/mod_tests.rs ` beside ` mod.rs ` , or
121+ ` src/<module>_tests.rs ` beside ` <module>.rs ` . Declare them at the bottom of
122+ the source module with ` #[cfg(test)] ` , ` #[path = "<module>_tests.rs"] `
123+ (or ` "mod_tests.rs" ` ), and ` mod tests; ` . The test file starts with
124+ ` use super::*; ` and carries no ` #[cfg(test)] ` of its own. Never use inline
125+ test modules or files named ` test.rs ` , ` tests.rs ` , or ` <module>_test.rs ` .
216126- Integration tests live in ` crates/<crate>/tests/ ` and exercise only the public
217127 API — they are the regression suite for the crate's contract.
218128- Payload types pin their serde representation in a unit test. That
219129 representation is the wire form: a host and a module that disagree about a
220130 field name fail at runtime with a decode error.
221131- Use descriptive, behavioral test names: ` rejects_an_empty_name ` , not
222- ` test_greet_2 ` .
132+ ` test_policy_2 ` .
223133- Cover the failure paths, not just the happy path. Every new error variant
224134 needs a test that produces it.
225135- For async behavior, standardize on one runtime (` tokio ` as a dev-dependency
@@ -240,8 +150,8 @@ Write documentation for the reader who has never seen the code.
240150
241151- Every public item gets a rustdoc comment. ` missing_docs ` is a warning that CI
242152 treats as an error.
243- - Start every ` mod.rs ` and ` test.rs ` with a concise module-level ` //! `
244- description .
153+ - Start every ` mod.rs ` with a concise module-level ` //! ` description.
154+ Sibling ` *_tests.rs ` files start with ` use super::*; ` as specified above .
245155- Each crate's ` src/lib.rs ` carries its crate-level overview: what the crate
246156 does, the primary entry points, and a short runnable example. It should also
247157 say what the crate deliberately does * not* hold, and why.
@@ -295,7 +205,7 @@ Releases run from `.github/workflows/release.yml` via a manual
295205an interrupted release after its version commit and tag exist. The workflow
296206re-runs the full validation suite, computes the next version, updates
297207the root ` [workspace.package] ` version and ` Cargo.lock ` , commits and tags
298- ` vX.Y.Z ` , builds ` crates/template ` as a TinyBus module for every supported
208+ ` vX.Y.Z ` , builds ` crates/tinysecurity-module ` as a TinyBus module for every supported
299209platform, pushes, and creates an immutable GitHub release with installable
300210native packages.
301211
0 commit comments