@jini-ai/cms 0.3.10 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## Unreleased — Trash host adoption
+
+- Preserve `adapter-unavailable` for absent domains before checking entity policy; selected purge
+  still checks resolved-row authorization first. Added regression coverage for both manual and
+  retention purge outcomes.
+- Restore shared rationale for atomic marker/index changes, keyset pagination, retention promises,
+  restore races, leases and follow-up no-ops. Move the cursor wire/Unicode/malformed-input suite
+  into `src/trash/__tests__/cursor.test.ts`. Move the nine in-memory repository contract cases
+  and nine pure sweep decision cases alongside their shared implementations; native timer and
+  SQL/dialect integration coverage remains with the host adapters.
+
+## 0.4.0 — 2026-10-02
+
+### BREAKING
+
+- Remove the unused `@jini-ai/cms/server` placeholder subpath and its `CMS_SERVER_LAYER` marker; concrete Node adapters remain in domain-specific entries and identity wiring belongs to `@jini-ai/user-management/server`.
+- Identity tools moved to user-management/server; analytics moved to the analytics package and trash to cms/trash. Settings use a principal lookup port, generic tool/HTTP/clock types come from core, and the nonexistent ./widgets entry was removed.
+- Distribution includes runtime output, release documentation and required assets only. Process records and per-job neutrality checks are no longer part of the package surface.
+
+## Unreleased
+
+### Compile repairs
+
+- Align settings HTTP adapters and value-write tool errors with current named kernel/domain arguments; import the canonical taxonomy ID generator type.
+- Correct feed callback/mock typing, authorization fixtures, taxonomy delete arguments, workspace update dependencies, and awaited index-identity assertions without removing tests.
+
+### Breaking architecture boundaries
+
+- Move identity registrations to `@jini-ai/user-management/server`; remove the user-management dependency.
+- Move generic registration helpers and tool catalog types to `@jini-ai/core`; remove domain type aliases and local primitive/Result/HTTP declarations. Use core primitives and named helper calls.
+- Replace the settings identity repository dependency with a host-owned findActiveById lookup that a raw identity repository cannot satisfy structurally.
+- Require explicitly bound transactions for term rename and workspace deletion.
+- Add `./trash`, moved with its tests from platform. Retention is an option defaulting to 60 days; eager RangeError validation and sweeper bounds are retained. ID allocation uses the kernel `IdGenerator.newId()` port.
+- Remove the unimplemented `./widgets` export and its metadata entry.
+
+
+- Add `@jini-ai/cms/http/settings`: move the eight settings routes, contracts, CMS
+  adapters and resumable change feed with their behavior suites from HTTP kit.
+  `express` and `@jini-ai/http-kit` are optional peers used only by HTTP entries.
+- Restore `401 UNAUTHENTICATED` when readiness or principal resolution fails.
+- Isolate throwing diagnostics and individual cleanup failures so subscriptions retry
+  safely and cancellation/end still run. Regression tests written, not run.
+
+- Remove specification identifiers from runtime refusal messages while preserving the guard, error class and explanatory text; retain rationale references in comments.
+
+- Add forms validation, audited definition writes, bounded submissions and notification services in the separate nested `@jini-ai/cms-forms` workspace package.
+- Add `./media/import` URL and binary validation with required MIME/size policy and injected HTTP, sniffer and outbound guard ports.
+
+### CMS integration
+
+- The universal `./core/tools` entry now owns CMS permission helpers. Named input, catalog, schema-rejection and registration helpers are exported directly by the kernel.
+- Complete the `./media/import` barrel and runtime metadata, with caller-supplied HTTP, binary validation, MIME/size policy and outbound safety ports.
+- Identity services and hashing now live in `@jini-ai/user-management` and `@jini-ai/user-management/server`; Identity tool registration composition is exported by the user-management server entry. Remove the former identity workspace dependency from CMS and exclude retired identity build output from packaging.
+- BREAKING: CMS domain functions, constructors, lifecycle handlers and scalar/callback repository, event-bus, outbox and change-set methods use `(requiredArgs, optionalArgs)` object arguments. Optional configuration and seeds move to the second object. Entry/content-type transactions use `transaction({ fn })`; their authorization ports use required principal/permission/workspace fields plus optional entity scope in the second object. Error details, validation and ordering are preserved. Hosts must rewire their adapters and calls.
+- BREAKING: Retire `./identity` and `./identity/hasher` CMS export targets after their source migration. Import services from the identity package; import the registration builder from `@jini-ai/user-management/server`.
+- Settings and navigation conversions still owned by their active jobs are pending. Legacy core helpers and authorization callbacks remain compatible until those callers migrate.
+- Correct `./media` runtime metadata to Node because its existing barrel exposes filesystem, crypto and native-transform adapters; `./media/import` remains universal.

package/README.md

@@ -2,27 +2,39 @@
 
 Content-model capability for Jini-hosted products.
 
-> **Status: implemented, port in progress.** Created 2026-08-02 as an empty shell; the port has
-> been landing since. Measured 2026-09-05 at `v0.3.4`: 131 non-test source files / 21,718 lines
-> under `src/` (34,938 including tests), 11 domain trees, and 14 public subpath exports wired in
-> `package.json`. Some domain modules named under [Port inventory](#port-inventory) have not moved
-> yet — check `src/` and the `exports` map for what is actually reachable today rather than
-> trusting this paragraph's counts.
+The source tree includes content domains and Node adapters. CMS depends on shared kernel
+contracts and has no user-management dependency. Generic tool wiring is exported by
+`@jini-ai/core`; hosts provide CMS authorization and active-principal lookup ports.
+See [API integration](API-INTEGRATION.md) for current signatures and migration examples, and
+[integration-report.md](integration-report.md) for pending protected work and deferred verification.
 
 ## Layers
 
 | subpath | runtime | contents |
 |---|---|---|
 | `.` / `./core` | universal | Content contracts and types, ports, pure domain services, kernel registries. No Express, no `node:*`, no DOM. |
-| `./server` | node | Concrete adapters for the ports in `/core`: SQLite/Postgres repositories, filesystem blob stores, image transformers. |
+| `./media` | node | Media services, filesystem blob stores and image transformers. |
+| `./http/settings` | node | Settings HTTP routes, host policy contracts, CMS adapters and resumable change feed. |
 
-`/server` depends on `/core`. The reverse is a boundary violation — if a core module wants
-something from `/server`, the dependency is backwards and the fix is a port (interface) in core,
+Node-bound domain adapters depend on `/core`. The reverse is a boundary violation — if a core module wants
+something from a Node adapter, the dependency is backwards and the fix is a port (interface) in core,
 not a widened export.
 
-`./server` means *the Node-bound layer*, not *the HTTP server* — same convention as
-`@jini-ai/admin`. HTTP transport is out of scope; Jini has `@jini-ai/http-kit` and
-`@jini-ai/server`.
+Domain HTTP adapters live under `./http/*`, using the generic transport and host
+composition supplied by `@jini-ai/http-kit` and `@jini-ai/server`.
+Identity tool registration composition belongs to `@jini-ai/user-management/server`.
+
+`@jini-ai/cms/http/settings` exports `registerSettingsRoutes`, the settings HTTP
+contracts and the CMS service/change-feed factories. Hosts provide route paths,
+permissions, workspace, readiness, principal resolution, authorization, scheduler,
+service and feed ports. Registration returns a disposer that closes active feeds.
+CMS adapters pass named request objects to settings dispatch and change-feed services;
+queryable index-name helpers return promises that callers must await.
+Install the optional peers `express` and `@jini-ai/http-kit` when using HTTP subpaths;
+the framework-free root and domain entries do not import them.
+Readiness or principal-resolution failures return `401 UNAUTHENTICATED`.
+Stream diagnostics are best-effort: a throwing reporter cannot prevent retries,
+cancellation of other schedules or ending the response.
 
 ## Why the split exists before there is any code to split
 
@@ -57,11 +69,12 @@ history shows they essentially never co-change with each other, so each ports in
 coordination.
 
 **Landed** (directories under `src/`, each with its own subpath export):
-`core`, `content-types`, `entries`, `identity`, `media`, `navigation`, `presentation`, `settings`,
-`taxonomy`, `workspace`, and the `server` adapter layer.
+`core`, `content-types`, `entries`, `media`, `navigation`, `presentation`, `settings`,
+`taxonomy`, `workspace`, and `trash`. `./core/tools` exports CMS permission helpers; `./media/import` exports bounded image fetching with injected policies and ports.
 
-**Still to move:** `post`, `seo`, `comments`, `forms`, `redirects`, `widgets`, `newsletter`,
-`members`. (`widgets` has an `exports` entry but no `src/widgets/` tree yet.)
+**Still to move:** `post`, `seo`, `comments`, `redirects`, `widgets`, `newsletter`,
+`members`. The unimplemented `./widgets` export has been removed.
+The nested forms package is maintained by its separate owner and is excluded from this parent package.
 
 **Explicitly not ported:**
 
@@ -84,6 +97,21 @@ pnpm --filter @jini-ai/cms test
 - **Add coverage thresholds.** `vitest.config.ts` still has none. That was a deliberate omission
   while the package was a placeholder; it no longer is, so the reason has expired. Set them against
   what the ported modules actually measure — siblings run 98–100%.
-- **Delete `CMS_SERVER_LAYER`** (`src/server/index.ts`). It existed only to give the `/server`
-  entry point something real to resolve, and real exports have since landed. Its `/core`
-  counterpart `CMS_CORE_LAYER` is already gone.
+
+## Design decisions
+
+- [Schema indexes use closed fragments and unambiguous identities](docs/decisions/DR-001-safe-schema-and-index-transitions.md).
+- [Content lifecycle separates new authoring from existing-entry writes](docs/decisions/DR-002-content-lifecycle-and-cleanup.md).
+- [Settings preserve total defaults, scope fences and revision evidence](docs/decisions/DR-003-settings-ledger-invariants.md).
+- [Blob collection rechecks references before journaled unlink](docs/decisions/DR-004-journaled-blob-gc.md).
+- [Taxonomy validation preserves first-failure order and full cycle checks](docs/decisions/DR-005-ordered-taxonomy-validation.md).
+- [Mutation, audit record and outbox intent share a commit boundary](docs/decisions/DR-006-mutation-audit-atomicity.md).
+- [Workspace administration preserves tenancy and ownership floors](docs/decisions/DR-007-workspace-and-owner-floors.md).
+- [Navigation mutations enqueue one event only on success](docs/decisions/DR-008-navigation-event-intent.md).
+
+The `./trash` surface owns snapshot-only listing, keyset cursors, atomic marker/index writes,
+transactional follow-ups and the retention sweeper. Hosts inject their table adapters, reentrant
+transaction runner, `IdGenerator`, entity policy, `Clock` and scheduler. Native timer `unref` and
+error logging belong to the host. Actor/prior-marker/list filters are passed in the optional second
+object. Purge callers own human confirmation and must authorize each resolved index row; unavailable
+domains remain `adapter-unavailable` after authorization even when their entity policy denies them.

package/dist/content-types/agent-tools.d.ts

@@ -1,65 +1,12 @@
+import type { AgentToolDefinition } from "@jini-ai/core";
 /**
- * @file REQ-22/REQ-23 — the Collections content-types agent-tool catalog, instantiating
- * a REQ-22 naming/callability convention (mirrors `features/database/agent-tools.ts`'s
- * shape for this domain).
- *
- * Purpose:
- * A static, in-process catalog describing every agent-callable tool this domain exposes and the
- * permission/actor-class rule each one carries. `collections_content_type_list` (admin-UI-backend-
- * gap closure, mirroring `routes/admin/content-types/list.ts`) and `collections_plan_cleanup` are
- * both free reads (`admin.collections.read`, `sideEffects:'none'`) — the former lists the registry,
- * the latter only recomputes and returns an eligibility plan. `collections_execute_cleanup` is the
- * one destructive tool, gated to
- * `admin.collections.manage` and restricted to `confirmer-must-equal-own-delegatedBy`. There is
- * deliberately no `collections_confirm_cleanup` tool and no tool description implying an agent can
- * perform the confirm() step — confirmation of a destructive cleanup is human-UI-only (mirrors
- * the Database library's "Restore is a Recovery tool, not a Database tool" discipline: a lever an agent must
- * never be handed directly).
- *
- * How it relates to the project:
- * The server-side tool filter consumes this catalog to decide which tool names an agent
- * session may even see; `authorize()` and the confirmation-token gateway (`core/gated-mutations`)
- * enforce the actual permission/actor-class checks at call time — this module only declares the
- * catalog shape, it performs no I/O and no enforcement itself.
- *
- * Architectural role:
- * `features/content-types` domain logic. Performs no I/O and no enforcement. Depends only on this
- * package's own `types.ts` (the field-kind enum) and `index-provisioning.ts` (the identifier
- * grammar pattern) — imported so the published JSON Schemas cannot drift from the single sources
- * of those two values, rather than restating either.
- */
-export type AgentToolSideEffect = "none" | "mutates-durable-state" | "mints-token";
-export type AgentToolActorClassRule = "confirmer-must-equal-own-delegatedBy" | "user-only" | "none";
-export interface AgentToolDefinition {
-    name: string;
-    description: string;
-    sideEffects: AgentToolSideEffect;
-    authorization: {
-        permission: string;
-    };
-    actorClassRule?: AgentToolActorClassRule;
-    /**
-     * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
-     * (`assistant/tool-registrations.ts`). Optional because the two cleanup entries are not wired to
-     * handlers yet and their input shape is not designed; `tool-registrations.ts` asserts that every
-     * tool it DOES wire has one.
-     *
-     * These schemas are hand-authored, and enforcement lives elsewhere — `field-defs.ts` for
-     * structure and `write-service.ts`'s CIC U-002-B1 chain for the domain rules. That is a
-     * deliberate two-artifact design, so the pair is pinned against drift by a fixture corpus in
-     * `__tests__/unit/agent-tools.schema-agreement.unit.test.ts`. The two values a schema would
-     * otherwise duplicate — the field-kind enum and the identifier grammar — are imported from their
-     * single sources rather than restated.
-     */
-    inputSchema?: Readonly<Record<string, unknown>>;
-}
-/**
- * REQ-22/REQ-23 — the Collections content-types domain's fixed agent-tool catalog.
+ * — the Collections content-types domain's fixed agent-tool catalog.
  *
  * `collections_content_type_list` is ordered first, mirroring `identity/agent-tools.ts`'s
  * "read-tools-first" convention: a model cannot call `update_fields`/`deprecate`/`reactivate`/
  * `tombstone` without a `key` and current `expectedVersion`, and this is the only way to learn
  * either for a content type it did not itself just create.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export declare const contentTypesAgentToolCatalog: AgentToolDefinition[];
 //# sourceMappingURL=agent-tools.d.ts.map

package/dist/content-types/agent-tools.js

@@ -1,6 +1,6 @@
 /**
- * @file REQ-22/REQ-23 — the Collections content-types agent-tool catalog, instantiating
- * a REQ-22 naming/callability convention (mirrors `features/database/agent-tools.ts`'s
+ * @file the Collections content-types agent-tool catalog, instantiating
+ * a naming/callability convention (mirrors `features/database/agent-tools.ts`'s
  * shape for this domain).
  *
  * Purpose:
@@ -12,13 +12,13 @@
  * one destructive tool, gated to
  * `admin.collections.manage` and restricted to `confirmer-must-equal-own-delegatedBy`. There is
  * deliberately no `collections_confirm_cleanup` tool and no tool description implying an agent can
- * perform the confirm() step — confirmation of a destructive cleanup is human-UI-only (mirrors
+ * perform the confirm step — confirmation of a destructive cleanup is human-UI-only (mirrors
  * the Database library's "Restore is a Recovery tool, not a Database tool" discipline: a lever an agent must
  * never be handed directly).
  *
  * How it relates to the project:
  * The server-side tool filter consumes this catalog to decide which tool names an agent
- * session may even see; `authorize()` and the confirmation-token gateway (`core/gated-mutations`)
+ * session may even see; `authorize` and the confirmation-token gateway (`core/gated-mutations`)
  * enforce the actual permission/actor-class checks at call time — this module only declares the
  * catalog shape, it performs no I/O and no enforcement itself.
  *
@@ -27,10 +27,25 @@
  * package's own `types.ts` (the field-kind enum) and `index-provisioning.ts` (the identifier
  * grammar pattern) — imported so the published JSON Schemas cannot drift from the single sources
  * of those two values, rather than restating either.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 import { IDENTIFIER_GRAMMAR_PATTERN } from "./index-provisioning.js";
 import { CONTENT_TYPE_FIELD_KINDS } from "./types.js";
-/** One entry of a `fields` array, as published to the model. Mirrors what `field-defs.ts` enforces. */
+/**
+   * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
+   * (`assistant/tool-registrations.ts`). Optional because the two cleanup entries are not wired to
+   * handlers yet and their input shape is not designed; `tool-registrations.ts` asserts that every
+   * tool it DOES wire has one.
+   *
+   * These schemas are hand-authored, and enforcement lives elsewhere — `field-defs.ts` for
+   * structure and `write-service.ts`'s chain for the domain rules. That is a
+   * deliberate two-artifact design, so the pair is pinned against drift by a fixture corpus in
+   * `__tests__/unit/agent-tools.schema-agreement.unit.test.ts`. The two values a schema would
+   * otherwise duplicate — the field-kind enum and the identifier grammar — are imported from their
+   * single sources rather than restated.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
+ *
+ * One entry of a `fields` array, as published to the model. Mirrors what `field-defs.ts` enforces. */
 const FIELD_DEF_SCHEMA = {
     type: "object",
     additionalProperties: false,
@@ -83,12 +98,13 @@ const LIFECYCLE_INPUT_SCHEMA = {
     },
 };
 /**
- * REQ-22/REQ-23 — the Collections content-types domain's fixed agent-tool catalog.
+ * — the Collections content-types domain's fixed agent-tool catalog.
  *
  * `collections_content_type_list` is ordered first, mirroring `identity/agent-tools.ts`'s
  * "read-tools-first" convention: a model cannot call `update_fields`/`deprecate`/`reactivate`/
  * `tombstone` without a `key` and current `expectedVersion`, and this is the only way to learn
  * either for a content type it did not itself just create.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export const contentTypesAgentToolCatalog = [
     {

package/dist/content-types/cleanup.d.ts

@@ -1,22 +1,22 @@
-import type { ClockPort } from "../core/ports.js";
+import type { Clock } from "@jini-ai/core/primitives";
 import { CleanupNotEligibleError } from "./errors.js";
 import type { AuthorizeFn } from "./write-service.js";
-import type { Result } from "./types.js";
+import type { Result } from "@jini-ai/core/primitives";
 /**
- * @file REQ-20/REQ-21 — the destructive cleanup ceremony, instantiating the
+ * @file the destructive cleanup ceremony, instantiating the
  * gated-mutation gateway (`domain="collections"`, `action="cleanup"`) around a tombstoned content
  * type's final, irreversible removal (the disable -> tombstone -> cleanup
  * lifecycle).
  *
  * Purpose:
- * `planCleanup` is the eligibility gate (C-405): a content type must be `status='tombstone'`, its
+ * `planCleanup` is the eligibility gate : a content type must be `status='tombstone'`, its
  * retention window (30 days since `tombstonedAt`, inclusive) must have elapsed, and an
  * `exportReference` must be present — checked in that fixed order, stopping at the first failure
- * (behavior.spec.md §2.3), before the actual gated-mutation `plan()` is ever reached. `executeCleanup`
- * forwards straight to the gated-mutation gateway's own `execute()` (token redemption, actor-class
+ * (behavior.spec.md §2.3), before the actual gated-mutation `plan` is ever reached. `executeCleanup`
+ * forwards straight to the gated-mutation gateway's own `execute` (token redemption, actor-class
  * check, plan-staleness re-check all live there — this module does not re-implement them) and
  * only performs the actual multi-table removal after the gateway confirms the token; a rejected
- * gateway call never triggers any local removal (EC-10, INV-07).
+ * gateway call never triggers any local removal.
  *
  * How it relates to the project:
  * `deps.gateway` in `planCleanup`/`executeCleanup` is intentionally two different narrow port
@@ -26,6 +26,7 @@ import type { Result } from "./types.js";
  *
  * Architectural role:
  * `features/content-types` domain logic, composing `write-service.ts`'s `AuthorizeFn` shape.
+ * See docs/decisions/DR-002-content-lifecycle-and-cleanup.md.
  */
 export interface CleanupEligibilityCheckRepoPort {
     findByKey(params: {
@@ -52,7 +53,7 @@ export interface PlanCleanupRequired {
     deps: {
         repo: CleanupEligibilityCheckRepoPort;
         gateway: PlanCleanupGatewayPort;
-        clock: ClockPort;
+        clock: Clock;
         authorize: AuthorizeFn;
     };
     input: {
@@ -63,12 +64,13 @@ export interface PlanCleanupRequired {
     };
 }
 /**
- * REQ-20 — the fixed-order eligibility gate: `status==='tombstone'` -> retention window elapsed
+ * — the fixed-order eligibility gate: `status==='tombstone'` -> retention window elapsed
  * (>=30 days since `tombstonedAt`, inclusive lower bound) -> `exportReference` present. Only once
- * all three pass does this call reach the real `gateway.plan()`.
+ * all three pass does this call reach the real `gateway.plan`.
  *
  * @complexity O(1) — one repo read, one date diff, one delegated gateway call at most.
  * @overallScore 100
+ * See docs/decisions/DR-002-content-lifecycle-and-cleanup.md.
  */
 export declare function planCleanup(required: PlanCleanupRequired): Promise<Result<{
     planId: string;
@@ -88,7 +90,9 @@ export interface CleanupRemovalRepoPort {
     }): Promise<{
         removedEntryCount: number;
     }>;
-    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    transaction<T>(required: {
+        fn: () => Promise<T>;
+    }): Promise<T>;
 }
 export interface ExecuteCleanupRequired {
     deps: {
@@ -103,14 +107,15 @@ export interface ExecuteCleanupRequired {
     };
 }
 /**
- * REQ-21/INV-07 — forwards straight to the gated-mutation gateway's own `execute()`; only once
+ * — forwards straight to the gated-mutation gateway's own `execute`; only once
  * that confirms (token redeemed, actor-class checked, plan still fresh) does this function perform
  * the actual atomic multi-table removal. A gateway rejection (expired/already-redeemed token,
- * stale plan) is forwarded verbatim and no local removal is ever attempted (EC-10).
+ * stale plan) is forwarded verbatim and no local removal is ever attempted.
  *
  * @complexity O(1) plus one delegated gateway call and, on success, one same-tx multi-table
  * removal.
  * @overallScore 100
+ * See docs/decisions/DR-002-content-lifecycle-and-cleanup.md.
  */
 export declare function executeCleanup(required: ExecuteCleanupRequired): Promise<Result<{
     removedEntryCount: number;

package/dist/content-types/cleanup.js

@@ -1,30 +1,32 @@
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 import { CleanupNotEligibleError } from "./errors.js";
 const RETENTION_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
 /**
- * REQ-20 — the fixed-order eligibility gate: `status==='tombstone'` -> retention window elapsed
+ * — the fixed-order eligibility gate: `status==='tombstone'` -> retention window elapsed
  * (>=30 days since `tombstonedAt`, inclusive lower bound) -> `exportReference` present. Only once
- * all three pass does this call reach the real `gateway.plan()`.
+ * all three pass does this call reach the real `gateway.plan`.
  *
  * @complexity O(1) — one repo read, one date diff, one delegated gateway call at most.
  * @overallScore 100
+ * See docs/decisions/DR-002-content-lifecycle-and-cleanup.md.
  */
 export async function planCleanup(required) {
     const { deps, input } = required;
     const authResult = await deps.authorize({ principalId: input.actorId, permission: "admin.collections.read", workspaceId: input.workspaceId });
     if (!authResult.allowed) {
-        return { ok: false, error: new CleanupNotEligibleError("forbidden", `principal '${input.actorId}' is not authorized to plan a cleanup (${authResult.reason})`) };
+        return { ok: false, error: new CleanupNotEligibleError({ reason: "forbidden" }, { message: `principal '${input.actorId}' is not authorized to plan a cleanup (${authResult.reason})` }) };
     }
     const contentType = await deps.repo.findByKey({ workspaceId: input.workspaceId, key: input.contentTypeKey });
     if (!contentType || contentType.status !== "tombstone") {
-        return { ok: false, error: new CleanupNotEligibleError("not_tombstoned") };
+        return { ok: false, error: new CleanupNotEligibleError({ reason: "not_tombstoned" }) };
     }
-    const now = deps.clock.nowIso();
+    const now = kernelNowIso({ clock: deps.clock });
     const elapsedMs = new Date(now).getTime() - new Date(contentType.tombstonedAt ?? now).getTime();
     if (elapsedMs < RETENTION_WINDOW_MS) {
-        return { ok: false, error: new CleanupNotEligibleError("retention_window_not_elapsed") };
+        return { ok: false, error: new CleanupNotEligibleError({ reason: "retention_window_not_elapsed" }) };
     }
     if (!input.exportReference) {
-        return { ok: false, error: new CleanupNotEligibleError("export_reference_missing") };
+        return { ok: false, error: new CleanupNotEligibleError({ reason: "export_reference_missing" }) };
     }
     const planResult = await deps.gateway.plan({
         principalId: input.actorId,
@@ -34,19 +36,20 @@ export async function planCleanup(required) {
         action: "cleanup",
     });
     if (!planResult.ok) {
-        return { ok: false, error: new CleanupNotEligibleError("gateway_rejected", String(planResult.error)) };
+        return { ok: false, error: new CleanupNotEligibleError({ reason: "gateway_rejected" }, { message: String(planResult.error) }) };
     }
     return { ok: true, value: planResult.value };
 }
 /**
- * REQ-21/INV-07 — forwards straight to the gated-mutation gateway's own `execute()`; only once
+ * — forwards straight to the gated-mutation gateway's own `execute`; only once
  * that confirms (token redeemed, actor-class checked, plan still fresh) does this function perform
  * the actual atomic multi-table removal. A gateway rejection (expired/already-redeemed token,
- * stale plan) is forwarded verbatim and no local removal is ever attempted (EC-10).
+ * stale plan) is forwarded verbatim and no local removal is ever attempted.
  *
  * @complexity O(1) plus one delegated gateway call and, on success, one same-tx multi-table
  * removal.
  * @overallScore 100
+ * See docs/decisions/DR-002-content-lifecycle-and-cleanup.md.
  */
 export async function executeCleanup(required) {
     const { deps, input } = required;
@@ -59,7 +62,9 @@ export async function executeCleanup(required) {
     if (!gatewayResult.ok) {
         return gatewayResult;
     }
-    const removal = await deps.repo.transaction(async () => deps.repo.removeContentTypeAndAllScopedRows({ contentTypeKey: input.contentTypeKey }));
+    const removal = await deps.repo.transaction({
+        fn: async () => deps.repo.removeContentTypeAndAllScopedRows({ contentTypeKey: input.contentTypeKey }),
+    });
     return { ok: true, value: removal };
 }
 //# sourceMappingURL=cleanup.js.map

package/dist/content-types/errors.d.ts

@@ -30,26 +30,36 @@ import { ToolInputError } from "@jini-ai/core";
  * marker above.
  */
 export declare class ForbiddenError extends ToolInputError {
-    constructor(message: string);
+    constructor({ message }: {
+        message: string;
+    }, _optional?: Record<string, never>);
 }
-/** CIC U-002-B1 guard 1 — `key`/field-name grammar gate `^[a-z][a-z0-9_]{0,63}$` (U-001-B2). */
+/** guard 1 — `key`/field-name grammar gate `^[a-z][a-z0-9_]{0,63}$`. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export declare class InvalidKeyGrammarError extends ToolInputError {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
-/** CIC U-002-B1 guard 2 — `key` is one of the permanently reserved legacy `posts` keys. */
+/** guard 2 — `key` is one of the permanently reserved legacy `posts` keys. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export declare class ReservedContentTypeKeyError extends ToolInputError {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
-/** CIC U-002-B1 guard 3 — a field name fails the identifier grammar gate. */
+/** guard 3 — a field name fails the identifier grammar gate. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export declare class InvalidFieldNameGrammarError extends ToolInputError {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
-/** CIC U-001-B1 / U-002-B1 guard 4 — a field `kind` is not one of the closed field-kind enum. */
+/** guard 4 — a field `kind` is not one of the closed field-kind enum. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export declare class InvalidFieldKindError extends ToolInputError {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
 /**
- * CIC U-002-B1 guard 4b — a field declares a STORAGE-ONLY `kind` (`json`) together with
+ * guard 4b — a field declares a STORAGE-ONLY `kind` (`json`) together with
  * `queryable: true`. The kind itself is legal and the field may be declared and written; what is
  * rejected is the pairing, because a storage-only kind has no `CAST` target and therefore no index
  * to provision.
@@ -62,16 +72,19 @@ export declare class InvalidFieldKindError extends ToolInputError {
  * `400 VALIDATION_ERROR` with no coordinated change, and the relationship is honest — this IS a
  * rejection of the field's kind, in the context the kind was used. `.name` still distinguishes it
  * for any caller that wants the finer signal.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export declare class StorageOnlyFieldNotQueryableError extends InvalidFieldKindError {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
 /**
  * A `fields` payload whose STRUCTURE is wrong — not a value that failed a domain rule, but a
  * shape the `ContentTypeFieldDef[]` contract does not describe at all (a non-array, a non-object
  * element, a missing/mistyped `name`/`required`/`queryable`, or an unrecognized key).
  *
- * Distinct from the five CIC U-002-B1 guard errors on purpose: those judge a well-formed field
+ * Distinct from the five guard errors on purpose: those judge a well-formed field
  * definition against a domain rule, and they remain the sole owners of the grammar, kind-enum and
  * queryable-cap decisions. This one fires strictly earlier, at the untrusted-input boundary
  * (`field-defs.ts`), for payloads the guards could not have judged without either crashing or
@@ -79,6 +92,7 @@ export declare class StorageOnlyFieldNotQueryableError extends InvalidFieldKindE
  *
  * `violation.received` names the offending value's TYPE, never the value — a field payload can
  * carry operator content, and this message reaches both an HTTP client and a model.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export declare class InvalidFieldShapeError extends ToolInputError {
     readonly code: "VALIDATION_ERROR";
@@ -93,29 +107,39 @@ export declare class InvalidFieldShapeError extends ToolInputError {
         received: string;
     });
 }
-/** CIC U-002-B1 guard 5 — more than the per-type cap of `queryable` fields were submitted. */
+/** guard 5 — more than the per-type cap of `queryable` fields were submitted. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export declare class QueryableFieldCapExceededError extends ToolInputError {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
-/** CIC U-004-B1 — `expectedVersion` did not match the current row's version (OCC conflict). */
+/** — `expectedVersion` did not match the current row's version (OCC conflict). See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export declare class VersionConflictError extends ToolInputError {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
 export declare class ContentTypeNotFoundError extends ToolInputError {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
 /**
  * Row 7 (web-high fix plan, 2026-09-24) — `registerContentType` loaded no existing row before
  * saving, so two concurrent first-widget creates (or a caller retrying an existing key) could
  * silently overwrite the current fields, and registering a tombstoned key could resurrect it
- * (INV-06 forbids any transition out of tombstone, including via a fresh register). Thrown when
+ * ( forbids any transition out of tombstone, including via a fresh register). Thrown when
  * `deps.repo.findByKey` already returns a row for the key, whether that row is active/deprecated
  * or tombstoned — `tombstoned` distinguishes the two so a caller/HTTP route can give the right
  * guidance (retry with update-fields, vs. the key is permanently gone).
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export declare class ContentTypeAlreadyExistsError extends ToolInputError {
     readonly tombstoned: boolean;
-    constructor(key: string, tombstoned: boolean);
+    constructor(requiredArgs: {
+        key: string;
+        tombstoned: boolean;
+    }, optionalArgs?: Record<string, never>);
 }
 /** A generic validation rejection carrying a stable machine-readable `details.reason`. */
 export declare class ValidationError extends ToolInputError {
@@ -123,15 +147,24 @@ export declare class ValidationError extends ToolInputError {
     readonly details: {
         reason: string;
     };
-    constructor(message: string, reason: string);
+    constructor(requiredArgs: {
+        message: string;
+        reason: string;
+    }, optionalArgs?: Record<string, never>);
 }
-/** REQ-09..12 lifecycle state-machine guard rejection (INV-06 terminal-tombstone, EC-09 deprecate-first). */
+/**..12 lifecycle state-machine guard rejection ( terminal-tombstone, deprecate-first). See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export declare class ContentTypeLifecycleError extends ToolInputError {
-    constructor(message: string);
+    constructor(requiredArgs: {
+        message: string;
+    }, optionalArgs?: Record<string, never>);
 }
-/** REQ-20 `planCleanup` eligibility-gate rejection; `reason` is one of a closed, ordered set. */
+/** `planCleanup` eligibility-gate rejection; `reason` is one of a closed, ordered set. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export declare class CleanupNotEligibleError extends Error {
     readonly reason: string;
-    constructor(reason: string, message?: string);
+    constructor(requiredArgs: {
+        reason: string;
+    }, optionalArgs?: {
+        message?: string;
+    });
 }
 //# sourceMappingURL=errors.d.ts.map