Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

docs(storage): clarify per-crate collection ownership

Steven Enamakel31cb646e32d1
diff --git a/crates/openhuman-core/src/storage/README.md b/crates/openhuman-core/src/storage/README.md
index 6186a21b4f..db9349a9af 100644
--- a/crates/openhuman-core/src/storage/README.md
+++ b/crates/openhuman-core/src/storage/README.md
@@ -371,6 +371,6 @@ storage itself.
- `scope.rs`: the one scope grammar (`tenant_scope`, `scope_for_profile`, `scope_for_agent`, `scope_for_module`), built on tsd's `Scope::tenant/local/agent/module`.
- `schema.rs`: `collection_owners()` validates linked crates' `CollectionSpec` declarations without merging owners; `module_collections(owner)` feeds module grants.
-- `boot.rs`: `prepare_and_migrate`, called by `open`, ensures the composed collections in the host's local and cluster scopes. Tenant, agent and module scopes are prepared by their owners when opened.
+- `boot.rs`: `prepare_and_migrate`, called by `open`, ensures each linked crate's collections in the host's local and cluster scopes. Tenant, agent and module scopes are prepared by their owners when opened.
- `scope_move.rs`: the resumable copy of v1 scopes (`profile:`, `<profile>~<agent>`, raw agent ids, `module:<id>@<base>`, the `*-sha256:` fallbacks) into the v2 scopes.
- The generated reference is `docs/storage-schema.md`; `node scripts/ci/check-storage-schema.mjs` lints the current collection names, indexes, expiry fields and search fields.
diff --git a/crates/openhuman-core/src/storage/mod.rs b/crates/openhuman-core/src/storage/mod.rs
index 93dabdd7f5..543a130dc0 100644
--- a/crates/openhuman-core/src/storage/mod.rs
+++ b/crates/openhuman-core/src/storage/mod.rs
@@ -298,7 +298,7 @@ pub async fn open(url: &str) -> Result<Arc<dyn StorageBackend>, StorageError> {
// Every opened backend checks the process's lease fences on write; with
// no fence registered (every single-user host) that is a pass-through.
let backend = tinystoragedrivers::open(&parsed).await?;
- // Prepare the composed owner collections before installing lease fences.
+ // Prepare each linked crate's collection declarations before installing lease fences.
// Legacy physical-source migration is handled separately by importers.
boot::prepare_and_migrate(&backend).await?;
Ok(fenced_backend::wrap(backend))
diff --git a/docs/gitbooks/en/developing/architecture/storage.md b/docs/gitbooks/en/developing/architecture/storage.md
index c4a6f3daaf..d67cde79fa 100644
--- a/docs/gitbooks/en/developing/architecture/storage.md
+++ b/docs/gitbooks/en/developing/architecture/storage.md
@@ -171,12 +171,12 @@ CI runs these targets, with the lib tests of the domains on the ports, in the co
## Schema, boot and migration
-Storage owners expose pure v2 `CollectionSpec` values. The host composes and validates them in `storage::schema::owner_collections`, then ensures those collections in its shared scopes and when an owner opens a scope. The generated [`docs/storage-schema.md`](../../../../storage-schema.md) lists the composed collection names, indexes, expiry fields and search fields; `scripts/ci/check-storage-schema.mjs` checks their names and millisecond timestamp fields. Record shapes, legacy conversion and migration rules remain with the owning domains.
+Storage crates expose pure v2 `CollectionSpec` values. The host validates and preserves those declarations by crate in `storage::schema::collection_owners`, then calls `ensure_collection` for each declaration in its shared scopes and when an owner opens a scope. The generated [`docs/storage-schema.md`](../../../../storage-schema.md) lists each crate's collection names, indexes, expiry fields and search fields; `scripts/ci/check-storage-schema.mjs` checks their names and millisecond timestamp fields. Record shapes, legacy conversion and migration rules remain with the owning domains.
`storage::open` runs `storage::boot::prepare_and_migrate` on the raw backend before the lease fence wraps it:
-1. `owner_collections` merges compatible declarations and fails on conflicting specs before the backend is touched.
-2. The host ensures composed collections in its local and cluster scopes. Profile, agent and module scopes are prepared by their owners when opened; no driver-wide schema registry or scope enumeration is used.
+1. `collection_owners` validates each crate's declarations without combining owners.
+2. The host ensures every crate's collections in its local and cluster scopes. Profile, agent and module scopes are prepared by their owners when opened; no driver-wide schema registry or scope enumeration is used.
3. Historical workspace and per-domain files are read by the separately gated `legacy-import` path. Its source formats and typed owner conversions are kept separate from normal backend opening.
A module's storage grant is generated from its owner's declared collections (`modules::storage_grant_schemas`), so it cannot drift from what the module declares.