first commit

docs/api-stack/api/api-plugin-vault/src/schema/schema.md

@@ -0,0 +1,97 @@
+# schema/schema
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Owns the SurrealQL DDL the vault plugin applies during `onInit` —
+the first leg of the 3-way plug-and-play contract. `VAULT_OWNERSHIP_SCHEMA`
+defines two tables (`vault_item` and `vault_share`) plus their indexes;
+`applyVaultSchemaViaRunner` and `applyVaultSchema` provide the two
+application paths the plugin uses (preferred runner path; direct
+`db.execute` fallback). Original — the `@suaveplan/vault`
+library encapsulates the encrypted container but exposes no opinion
+about the HTTP-layer ownership store.
+
+## Features
+
+- Two tables; `vault_item` is the active surface, `vault_share` is
+  forward-declared so the future sharing-routes follow-up plugin lands
+  without a database migration churn.
+- Three indexes covering the listing patterns the plugin actually
+  uses: per-owner-by-kind and per-owner-by-created-descending. The
+  share index is forward-declared too.
+- `DEFINE TABLE OVERWRITE` + `DEFINE FIELD OVERWRITE` everywhere — the
+  schema is idempotent. Re-applying on every cold start is safe and
+  costs only the brief metadata-replace.
+- `MigrationRunner` is the preferred application path because it
+  records the apply in `_migrations` and gives the operator a single
+  audit log of every DDL change.
+- The direct `db.execute` fallback path raises a typed
+  `VaultPluginError(VAULT_PLUGIN_SCHEMA_APPLY_FAILED)` with the original
+  error as `cause` for telemetry surfacing.
+
+## Usage: Basic
+
+```ts
+import {
+    applyVaultSchema,
+    VAULT_OWNERSHIP_SCHEMA,
+} from "@suaveplan/api-plugin-vault";
+
+await applyVaultSchema(surrealAdapter);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    applyVaultSchemaViaRunner,
+    VAULT_OWNERSHIP_SCHEMA,
+} from "@suaveplan/api-plugin-vault";
+import { createMigrationRunner } from "@suaveplan/api-migrations";
+
+const runner = createMigrationRunner({ adapter: surrealqlAdapter });
+await applyVaultSchemaViaRunner(runner);
+// _migrations now lists `0000-vault-ownership-schema`
+```
+
+## API Reference
+
+### `VAULT_OWNERSHIP_SCHEMA: string`
+
+Frozen DDL string. Contains the two `DEFINE TABLE`s and three
+`DEFINE INDEX`es plus every per-field declaration.
+
+### `SurrealLikeExecutor`
+
+Structural interface — `{ execute(query: string): Promise<unknown> }`.
+Matches `@suaveplan/surrealdb`'s `SurrealAdapter.execute`.
+
+### `applyVaultSchema(db: SurrealLikeExecutor): Promise<void>`
+
+Direct application path. Throws `VaultPluginError(VAULT_PLUGIN_SCHEMA_APPLY_FAILED)`
+on failure with the original error as `cause`.
+
+### `applyVaultSchemaViaRunner(runner: MigrationRunner): Promise<void>`
+
+Runner-mediated application path. Records the apply in the operator's
+migration log. Same error contract.
+
+## Implementation Notes
+
+- The schema does NOT define any view, function, or event — those
+  cross plugin boundaries. The vault plugin owns the bare ownership
+  store; cross-plugin views (e.g. "all items shared with me") belong
+  in the sharing follow-up.
+- `metadata` is `option<object>` so absent metadata stores as `NONE`
+  and zero-cost; clients can attach arbitrary JSON metadata without
+  schema churn.
+- Indexes are NOT marked `UNIQUE` — there is no uniqueness constraint
+  on `(ownerId, kind)`; multiple items of the same kind per owner are
+  normal.
+- The `containerKey` field is the opaque id used to look up the
+  encrypted body inside `@suaveplan/vault`'s container. Generated by
+  `vaultService` at create time; never returned to the wire.