Merge pull request #73 from tinyhumansai/crates-layout

Move every crate under crates/ and reach them all by feature

Author: senamakel

.github/workflows/ci.yml

@@ -58,7 +58,7 @@ jobs:
       #
       # This is also the configuration that keeps the promise the feature
       # exists for: no `git2` / `libgit2-sys` in the graph.
-      # `api/Cargo.toml` spells out this exact command in a comment and asks
+      # `crates/tinymemory-api/Cargo.toml` spells out this command in a comment and asks
       # that the contract crate never link a storage engine, a native library,
       # an HTTP client, or an async runtime. It was left as a comment, so
       # nothing checked it — and a forbidden dependency arrives transitively,
@@ -84,7 +84,7 @@ jobs:
         run: ./scripts/ci/dependency-budget.sh
 
       - name: Run the bundled example
-        run: cargo run --example basic
+        run: cargo run -p tinymemory --example basic
 
       - name: Assert engine containment (#18 §C1)
         run: ./scripts/ci/engine-containment.sh

.github/workflows/release.yml

@@ -83,9 +83,17 @@ jobs:
         run: |
           set -euo pipefail
 
+          # The root manifest is a virtual workspace — every crate lives under
+          # `crates/`, and there is no root package. So name the facade rather
+          # than taking `.packages[0]`, which is whichever member cargo happened
+          # to list first and would silently start releasing a different crate's
+          # version the day that order changes.
           metadata="$(cargo metadata --format-version 1 --no-deps)"
-          crate_name="$(jq -r '.packages[0].name' <<< "$metadata")"
-          current_version="$(jq -r '.packages[0].version' <<< "$metadata")"
+          crate_name="tinymemory"
+          current_version="$(
+            jq -r --arg name "$crate_name" \
+              '.packages[] | select(.name == $name) | .version' <<< "$metadata"
+          )"
           if [[ -z "$current_version" || "$current_version" == "null" ]]; then
             echo "Could not resolve the current crate version" >&2
             exit 1
@@ -127,7 +135,7 @@ jobs:
             echo "tag=${tag}"
           } >> "$GITHUB_OUTPUT"
 
-      # Bumps the root `[package]` version only. That is sufficient *because* no
+      # Bumps the facade's `[package]` version only. That is sufficient *because* no
       # intra-workspace path dependency carries a `version = "…"` requirement —
       # a `minor` bump to 0.2.0 against a sibling asking for `^0.1.0` fails
       # resolution here with "failed to select a version", which is exactly how
@@ -152,19 +160,20 @@ jobs:
             echo "An intra-workspace path dependency carries a version requirement:" >&2
             echo "$offenders" >&2
             echo >&2
-            echo "Bumping the root package will fail to resolve against it. Nothing here" >&2
+            echo "Bumping the facade will fail to resolve against it. Nothing here" >&2
             echo "is published to crates.io, so drop the 'version' key and keep 'path'." >&2
             exit 1
           fi
 
-          perl -0pi -e 's/(\[package\][\s\S]*?\nversion = ")[^"]+(")/$1$ENV{NEXT_VERSION}$2/' Cargo.toml
+          perl -0pi -e 's/(\[package\][\s\S]*?\nversion = ")[^"]+(")/$1$ENV{NEXT_VERSION}$2/' \
+            crates/tinymemory/Cargo.toml
           cargo update -p "$CRATE_NAME" --precise "$NEXT_VERSION"
 
           # There are TWO Cargo worlds here, and the module's is the one the
           # release actually builds. `crates/tinymemory-module` is its own
           # workspace root with its own `Cargo.lock` (see the root Cargo.toml
-          # comment for why), and it depends on the root crate by path — so
-          # bumping the root version leaves that lockfile recording the old one.
+          # comment for why), and it depends on the facade by path — so bumping
+          # the facade's version leaves that lockfile recording the old one.
           #
           # `native-bundles` then builds with `--locked` and every one of the
           # eleven jobs fails with "cannot update the lock file … because
@@ -188,7 +197,8 @@ jobs:
           # Both lockfiles: the module's own workspace lock is what the bundle
           # jobs build against with `--locked`, so a tag that omits it cannot be
           # built at all.
-          git add Cargo.toml Cargo.lock crates/tinymemory-module/Cargo.lock
+          git add crates/tinymemory/Cargo.toml Cargo.lock \
+            crates/tinymemory-module/Cargo.lock
           git commit -m "Release ${RELEASE_TAG}"
           git tag -a "${RELEASE_TAG}" -m "Release ${RELEASE_TAG}"
 

AGENTS.md

@@ -9,37 +9,48 @@ no longer applies rather than leaving it to rot.
 
 ## Project Structure
 
-This is a Cargo **workspace**: the `tinymemory` facade at the root, the
-`tinymemory-api` contract in `api/`, and one engine adapter per directory under
-`adapters/`. Engines themselves are submodules under `vendor/`, excluded from
-the workspace.
-
-See [`README.md`](README.md) for the layout and the rules that govern it — in
-particular, why policy stays in the host and why adapters name their engines by
-version requirement rather than by path.
+This is a Cargo **workspace** with a virtual root: there is no root package,
+and every crate lives in its own directory under `crates/`, named for the
+package it holds. `members` is the glob `crates/*`, so a new crate joins the
+workspace by existing. `crates/tinymemory` is the facade a host depends on;
+`crates/tinymemory-api` is the contract; the rest are the subsystems and the
+engine adapters, each reachable from the facade by a feature named after it.
+Engines themselves are submodules under `vendor/`, excluded from the workspace.
+
+See [`README.md`](README.md) for the full layout, the feature table, and the
+rules that govern them — in particular, why policy stays in the host and why
+adapters name their engines by version requirement rather than by path.
 
 ```text
-src/
-├── lib.rs              # crate docs + the entire public re-export surface
-├── error/mod.rs        # crate-wide `Error` and `Result<T>`
-└── <feature>/          # one directory per feature area
-    ├── mod.rs          # module docs, wiring, smallest useful public API
-    ├── types.rs        # substantial type definitions
-    └── test.rs         # module-local unit tests
-tests/                  # integration tests against the public API only
-examples/               # runnable, compiled-in-CI usage examples
+crates/<package>/
+├── Cargo.toml          # one package; `[lints]` opted into per crate
+├── README.md           # required of complex crates: design, surface, caveats
+└── src/
+    ├── lib.rs          # crate docs + the entire public re-export surface
+    ├── error/mod.rs    # crate-wide `Error` and `Result<T>`
+    └── <feature>/      # one directory per feature area
+        ├── mod.rs      # module docs, wiring, smallest useful public API
+        ├── types.rs    # substantial type definitions
+        └── test.rs     # module-local unit tests
+crates/<package>/tests/     # integration tests against the public API only
+crates/<package>/examples/  # runnable, compiled-in-CI usage examples
 vendor/tinybus/         # pinned TinyBus source; optional until wired by a project
 docs/
 ├── specs/              # behavior and architecture specifications
 ├── plans/              # test-first implementation plans
 └── adr/                # immutable architecture decision records
 ```
 
-Each feature area belongs in a focused module directory under `src/`. A module
-root explains the module, wires its pieces together, and exposes the smallest
-useful API. Move substantial type definitions into `types.rs` and put
-module-local unit tests in a dedicated `test.rs`, wired from the bottom of the
-module root with:
+A new crate goes in `crates/<package>/`, and a package that is not an adapter
+or a subsystem of the memory layer probably does not belong here at all. Reach
+it from the facade by adding an optional dependency and a feature of the same
+name, so a host keeps taking one dependency and stating what it wants.
+
+Each feature area belongs in a focused module directory under the crate's
+`src/`. A module root explains the module, wires its pieces together, and
+exposes the smallest useful API. Move substantial type definitions into
+`types.rs` and put module-local unit tests in a dedicated `test.rs`, wired from
+the bottom of the module root with:
 
 ```rust
 #[cfg(test)]
@@ -51,9 +62,10 @@ let a general-purpose `utils.rs` or `helpers.rs` grow — those are a symptom of
 missing module. Prefer many small modules that each do one thing well over few
 broad ones.
 
-Keep public exports centralized in `src/lib.rs` so downstream users have one
-predictable surface. Put shared error variants in `src/error/mod.rs` and return
-the crate-wide `Result<T>` from fallible public APIs.
+Keep public exports centralized in each crate's `src/lib.rs` so downstream
+users have one predictable surface. Put shared error variants in
+`src/error/mod.rs` and return the crate-wide `Result<T>` from fallible public
+APIs.
 
 ## Build And Test
 
@@ -71,7 +83,9 @@ Supporting commands:
 
 - `cargo fmt --all` — format before committing.
 - `cargo test <filter>` — run a focused subset while iterating.
-- `cargo run --example basic` — run the bundled example.
+- `cargo run -p tinymemory --example basic` — run the bundled example. The
+  `-p` is required: the workspace root is virtual, so cargo cannot infer which
+  package an example belongs to.
 - `cargo doc --no-deps --all-features` — build the rustdoc CI also builds with
   `RUSTDOCFLAGS="-D warnings"`.
 - `cargo test --doc` — run doctests alone when editing documentation examples.
@@ -92,14 +106,16 @@ Use standard `rustfmt` output and Rust 2024 idioms. Do not hand-format around
 - Prefer small, typed APIs over stringly-typed ones. Accept `&str` and generic
   `impl Into<String>` at boundaries; return owned, concrete types.
 - Keep the public surface minimal: default to private, and export deliberately
-  from `src/lib.rs`.
-- `unsafe` is forbidden crate-wide by the lint configuration in `Cargo.toml`.
-  If a project genuinely needs it, relax the lint in its own commit and document
-  every invariant with a `// SAFETY:` comment.
+  from the crate's `src/lib.rs`.
+- `unsafe` is forbidden crate-wide by the `[lints]` table in each crate's own
+  `Cargo.toml` — the root is virtual and carries no lint configuration. If a
+  crate genuinely needs it, relax the lint in its own commit and document every
+  invariant with a `// SAFETY:` comment.
 
 ### Errors
 
-- One crate-wide `Error` enum in `src/error/mod.rs`, built with `thiserror`.
+- One crate-wide `Error` enum in the crate's `src/error/mod.rs`, built with
+  `thiserror`.
 - Fallible public functions return `Result<T>`, the crate alias.
 - Add a specific variant instead of stuffing context into a string; error
   messages are lowercase, without trailing punctuation.
@@ -143,10 +159,10 @@ on every generated crate.
 
 ## Testing
 
-- Module-local unit tests live in `src/<feature>/test.rs` and may touch private
-  items.
-- Integration tests live in `tests/` and exercise only the public API — they are
-  the regression suite for the crate's contract.
+- Module-local unit tests live in `crates/<package>/src/<feature>/test.rs` and
+  may touch private items.
+- Integration tests live in `crates/<package>/tests/` and exercise only the
+  public API — they are the regression suite for the crate's contract.
 - Use descriptive, behavioral test names: `rejects_an_empty_name`, not
   `test_greet_2`.
 - Cover the failure paths, not just the happy path. Every new error variant
@@ -171,8 +187,8 @@ Write documentation for the reader who has never seen the code.
   treats as an error.
 - Start every `mod.rs` and `test.rs` with a concise module-level `//!`
   description.
-- `src/lib.rs` carries the crate-level overview: what the crate does, the
-  primary entry points, and a short runnable example.
+- Each crate's `src/lib.rs` carries its crate-level overview: what the crate
+  does, its primary entry points, and a short runnable example.
 - Prefer concrete examples over vague description. Doc examples are compiled and
   run by `cargo test`, so they cannot drift.
 - Complex modules must include a module-level `README.md` covering their design,
@@ -221,13 +237,14 @@ explicitly declined with a reason.
 Releases run from `.github/workflows/release.yml` via a manual
 `workflow_dispatch` with a `patch` / `minor` / `major` bump. The workflow
 re-runs the full validation suite, computes the next version, updates
-`Cargo.toml` and `Cargo.lock`, commits and tags `vX.Y.Z`, packages, pushes, and
-publishes to crates.io using the `CARGO_REGISTRY_TOKEN` secret.
+`crates/tinymemory/Cargo.toml` and `Cargo.lock`, commits and tags `vX.Y.Z`,
+packages, pushes, and publishes to crates.io using the `CARGO_REGISTRY_TOKEN`
+secret.
 
 Consequently:
 
-- Do not hand-edit the `version` field in `Cargo.toml`; the release workflow
-  owns it.
+- Do not hand-edit the `version` field in `crates/tinymemory/Cargo.toml`; the
+  release workflow owns it.
 - Follow semantic versioning. Any change to the public surface that is not
   purely additive is a breaking change and needs a major bump (pre-1.0: a minor
   bump).