@jini-ai/cms 0.3.10 → 0.4.0

package/dist/content-types/write-service.d.ts

@@ -1,34 +1,36 @@
-import type { ClockPort } from "../core/ports.js";
-import { type ActorIdentityInput, type ActorPrincipalKind, type ContentTypeFieldDef, type ContentTypeRecord, type Result } from "./types.js";
+import type { Clock } from "@jini-ai/core/primitives";
+import { type Result } from "@jini-ai/core/primitives";
+import { type ActorIdentityInput, type ActorPrincipalKind, type ContentTypeFieldDef, type ContentTypeRecord } from "./types.js";
 /**
  * @file Write-service — `registerContentType`/`updateContentTypeFields`, the single write
  * chokepoint for the `content_types` registry.
  *
  * Purpose:
  * The ONLY path that creates or full-replaces a content type's field schema. Every export here:
- * `authorize()` first (fail-closed) -> the fixed definition-time guard sequence (CIC U-002-B1) ->
+ * `authorize` first (fail-closed) -> the fixed definition-time guard sequence ->
  * same-transaction row + revision write (+ watermark stamp when supplied) -> index provisioning.
  *
- * `registerContentType`'s CIC U-002-B1 guard order is binding, not incidental: key grammar ->
+ * `registerContentType`'s guard order is binding, not incidental: key grammar ->
  * reserved-key -> field-name grammar -> field-kind -> storage-only-not-queryable -> queryable-cap,
  * evaluation stops at the first failure. The storage-only check is numbered 4b rather than
  * renumbering 5, because the fixed order is pinned by name in the certified suite and the existing
  * five guards keep both their relative order and their identity: 4b sits strictly between the
  * field-kind check and the queryable-cap check, and can only fire on a field whose kind already
- * passed guard 4. `updateContentTypeFields`'s CIC U-004-B1 additionally requires `expectedVersion`
+ * passed guard 4. `updateContentTypeFields` additionally requires `expectedVersion`
  * to be checked BEFORE the `fields_empty` floor and before any per-field guard, so a stale
  * `expectedVersion` combined with `fields: []` reports `VERSION_CONFLICT`, never
  * `VALIDATION_ERROR(fields_empty)`.
  *
  * How it relates to the project:
- * `deps.watermark` (REQ-01/INV-08) and the actor-identity delegation fields
- * (`delegatedByWorkspaceId`/`delegatedById`, REQ-16) are both optional/additive — every
+ * `deps.watermark` and the actor-identity delegation fields
+ * (`delegatedByWorkspaceId`/`delegatedById`) are both optional/additive — every
  * pre-existing call site that omits them is unaffected; `watermark-stamping.integration.test.ts`
  * exercises both.
  *
  * Architectural role:
  * `features/content-types` domain logic. Depends only on `core/ports` and this package's own
  * `errors.ts`/`index-provisioning.ts`/`types.ts` — no adapter, no other feature.
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 /**
  * Matches every other feature's chokepoint `AuthorizeFn` shape structurally — no shared import,
@@ -40,16 +42,8 @@ import { type ActorIdentityInput, type ActorPrincipalKind, type ContentTypeField
  * `resource_scope_mismatch` even though the route's pre-check allowed it, and why this chokepoint —
  * not the route — is the one that must stay at least as expressive.
  */
-export type AuthorizeFn = (params: {
-    principalId: string;
-    permission: string;
-    workspaceId: string;
-    entityType?: string | undefined;
-    entityId?: string | undefined;
-}) => Promise<{
-    allowed: boolean;
-    reason: string;
-}>;
+export type { AuthorizationPort as AuthorizeFn } from '../core/authorization.js';
+import type { AuthorizationPort as AuthorizeFn } from '../core/authorization.js';
 export interface ContentTypeRevisionInput {
     contentTypeKey: string;
     workspaceId: string;
@@ -74,7 +68,9 @@ export interface ContentTypeRepoPort {
         workspaceId: string;
         key: string;
     }): Promise<ContentTypeRecord | null>;
-    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    transaction<T>(required: {
+        fn: () => Promise<T>;
+    }): Promise<T>;
 }
 export interface IndexProvisionerPort {
     provisionIndexesForNewContentType(input: {
@@ -97,7 +93,7 @@ export interface OutboxPort {
         payload: Record<string, unknown>;
     }): Promise<void>;
 }
-/** Optional (REQ-01/INV-08) — advances `database_write_watermark` by exactly 1 when supplied. */
+/** Optional — advances `database_write_watermark` by exactly 1 when supplied. See docs/decisions/DR-001-safe-schema-and-index-transitions.md. */
 export interface WatermarkPort {
     stampWatermark(input: {
         workspaceId: string;
@@ -105,7 +101,7 @@ export interface WatermarkPort {
 }
 export interface ContentTypeWriteServiceDeps {
     repo: ContentTypeRepoPort;
-    clock: ClockPort;
+    clock: Clock;
     ids: {
         newId: () => string;
     };
@@ -124,11 +120,12 @@ export interface RegisterContentTypeRequired {
     };
 }
 /**
- * REQ-01..08 — registers a new content type. Guard order is CIC U-002-B1, fixed and stop-at-first-
+ * 08 — registers a new content type. Guard order is, fixed and stop-at-first-
  * failure: key grammar -> reserved-key -> field-name grammar -> field-kind -> queryable-cap.
  *
  * @complexity O(f) in the number of submitted fields (two guard passes over `fields`).
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export declare function registerContentType(required: RegisterContentTypeRequired): Promise<Result<{
     contentType: ContentTypeRecord;
@@ -152,12 +149,13 @@ export interface UpdateContentTypeFieldsRequired {
     };
 }
 /**
- * REQ-26 — full-replace of a content type's field schema. CIC U-004-B1: `expectedVersion` is
+ * — full-replace of a content type's field schema. : `expectedVersion` is
  * checked BEFORE the `fields_empty` floor and before any per-field guard, so a stale version
  * combined with an empty array reports `VERSION_CONFLICT`, never `VALIDATION_ERROR`.
  *
  * @complexity O(f) in the number of submitted fields.
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export declare function updateContentTypeFields(required: UpdateContentTypeFieldsRequired): Promise<Result<{
     contentType: ContentTypeRecord;

package/dist/content-types/write-service.js

@@ -1,7 +1,9 @@
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 import { EntityNotLiveError } from "../core/entity-liveness.js";
 import { ContentTypeAlreadyExistsError, ContentTypeNotFoundError, ForbiddenError, InvalidFieldKindError, InvalidFieldNameGrammarError, InvalidKeyGrammarError, QueryableFieldCapExceededError, ReservedContentTypeKeyError, StorageOnlyFieldNotQueryableError, ValidationError, VersionConflictError, } from "./errors.js";
 import { resolveFieldIndexTransition, validateIdentifierGrammar } from "./index-provisioning.js";
-import { isContentTypeFieldKind, isIndexableFieldKind, } from "./types.js";
+import {} from "@jini-ai/core/primitives";
+import { isContentTypeFieldKind, isIndexableFieldKind } from "./types.js";
 /** Reserved forever for the legacy `posts` table — an operator Collection can never take these keys. */
 /**
  * Field-name guards shared by register and update, in order: every name passes the identifier
@@ -14,14 +16,14 @@ import { isContentTypeFieldKind, isIndexableFieldKind, } from "./types.js";
  */
 function fieldNameError(fields) {
     for (const field of fields) {
-        if (!validateIdentifierGrammar(field.name)) {
-            return new InvalidFieldNameGrammarError(`field name '${field.name}' fails the identifier grammar gate`);
+        if (!validateIdentifierGrammar({ value: field.name })) {
+            return new InvalidFieldNameGrammarError({ message: `field name '${field.name}' fails the identifier grammar gate` });
         }
     }
     const seen = new Set();
     for (const field of fields) {
         if (seen.has(field.name)) {
-            return new ValidationError(`field name '${field.name}' appears more than once`, "fields_duplicate_name");
+            return new ValidationError({ message: `field name '${field.name}' appears more than once`, reason: "fields_duplicate_name" });
         }
         seen.add(field.name);
     }
@@ -34,30 +36,30 @@ function countQueryableFields(fields) {
     return fields.filter((f) => f.queryable).length;
 }
 /**
- * REQ-01..08 — registers a new content type. Guard order is CIC U-002-B1, fixed and stop-at-first-
+ * 08 — registers a new content type. Guard order is, fixed and stop-at-first-
  * failure: key grammar -> reserved-key -> field-name grammar -> field-kind -> queryable-cap.
  *
  * @complexity O(f) in the number of submitted fields (two guard passes over `fields`).
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export async function registerContentType(required) {
     const { deps, input } = required;
     const authResult = await deps.authorize({
         principalId: input.actorId,
         permission: "admin.collections.manage",
-        workspaceId: input.workspaceId,
-        entityType: "content-type",
-    });
+        workspaceId: input.workspaceId
+    }, { entityType: "content-type" });
     if (!authResult.allowed) {
-        return { ok: false, error: new ForbiddenError(`principal '${input.actorId}' cannot register a content type (${authResult.reason})`) };
+        return { ok: false, error: new ForbiddenError({ message: `principal '${input.actorId}' cannot register a content type (${authResult.reason})` }) };
     }
     // Guard 1: key grammar.
-    if (!validateIdentifierGrammar(input.key)) {
-        return { ok: false, error: new InvalidKeyGrammarError(`content-type key '${input.key}' fails the identifier grammar gate ^[a-z][a-z0-9_]{0,63}$`) };
+    if (!validateIdentifierGrammar({ value: input.key })) {
+        return { ok: false, error: new InvalidKeyGrammarError({ message: `content-type key '${input.key}' fails the identifier grammar gate ^[a-z][a-z0-9_]{0,63}$` }) };
     }
     // Guard 2: reserved key.
     if (RESERVED_CONTENT_TYPE_KEYS.has(input.key)) {
-        return { ok: false, error: new ReservedContentTypeKeyError(`key '${input.key}' is permanently reserved for the legacy 'posts' table`) };
+        return { ok: false, error: new ReservedContentTypeKeyError({ message: `key '${input.key}' is permanently reserved for the legacy 'posts' table` }) };
     }
     // Guard 3: field-name grammar, then uniqueness (every field, before any kind/cap check).
     const nameErrorOnRegister = fieldNameError(input.fields);
@@ -65,8 +67,8 @@ export async function registerContentType(required) {
         return { ok: false, error: nameErrorOnRegister };
     // Guard 4: field-kind, closed enum.
     for (const field of input.fields) {
-        if (!isContentTypeFieldKind(field.kind)) {
-            return { ok: false, error: new InvalidFieldKindError(`field '${field.name}' has kind '${field.kind}', not one of the closed field-kind enum`) };
+        if (!isContentTypeFieldKind({ value: field.kind })) {
+            return { ok: false, error: new InvalidFieldKindError({ message: `field '${field.name}' has kind '${field.kind}', not one of the closed field-kind enum` }) };
         }
     }
     // Guard 4b: a storage-only kind cannot be queryable. Placed strictly between guard 4 and guard 5
@@ -74,24 +76,24 @@ export async function registerContentType(required) {
     // BEFORE the cap count and long before `resolveFieldIndexTransition` could hand it to the index
     // provisioner. This is the check that keeps a kind with no CAST target off the DDL path.
     for (const field of input.fields) {
-        if (field.queryable && !isIndexableFieldKind(field.kind)) {
+        if (field.queryable && !isIndexableFieldKind({ value: field.kind })) {
             return {
                 ok: false,
-                error: new StorageOnlyFieldNotQueryableError(`field '${field.name}' has storage-only kind '${field.kind}' and cannot be queryable`),
+                error: new StorageOnlyFieldNotQueryableError({ message: `field '${field.name}' has storage-only kind '${field.kind}' and cannot be queryable` }),
             };
         }
     }
     // Guard 5: queryable-field cap, submitted array alone.
     if (countQueryableFields(input.fields) > QUERYABLE_FIELD_CAP) {
-        return { ok: false, error: new QueryableFieldCapExceededError(`content type '${input.key}' submits more than ${QUERYABLE_FIELD_CAP} queryable fields`) };
+        return { ok: false, error: new QueryableFieldCapExceededError({ message: `content type '${input.key}' submits more than ${QUERYABLE_FIELD_CAP} queryable fields` }) };
     }
     // Row 7 — a pre-check outside the transaction. Not race-safe by itself (that's the in-tx check
     // below), but it avoids opening a transaction for the overwhelmingly common not-found case.
     const existingBeforeTx = await deps.repo.findByKey({ workspaceId: input.workspaceId, key: input.key });
     if (existingBeforeTx) {
-        return { ok: false, error: new ContentTypeAlreadyExistsError(input.key, existingBeforeTx.status === "tombstone") };
+        return { ok: false, error: new ContentTypeAlreadyExistsError({ key: input.key, tombstoned: existingBeforeTx.status === "tombstone" }) };
     }
-    const now = deps.clock.nowIso();
+    const now = kernelNowIso({ clock: deps.clock });
     const contentType = {
         workspaceId: input.workspaceId,
         key: input.key,
@@ -102,28 +104,28 @@ export async function registerContentType(required) {
         tombstonedAt: null,
     };
     try {
-        await deps.repo.transaction(async () => {
-            // The check that actually closes the race: two concurrent first-widget creates both see the
-            // pre-check above return null, but only one of them can win this in-tx re-check before save.
-            const existingInTx = await deps.repo.findByKey({ workspaceId: input.workspaceId, key: input.key });
-            if (existingInTx) {
-                throw new ContentTypeAlreadyExistsError(input.key, existingInTx.status === "tombstone");
-            }
-            await deps.repo.save(contentType);
-            await deps.repo.appendRevision({
-                contentTypeKey: input.key,
-                workspaceId: input.workspaceId,
-                op: "register",
-                stateJson: contentType,
-                actorId: input.actorId,
-                principalKind: input.principalKind ?? null,
-                delegatedByWorkspaceId: input.delegatedByWorkspaceId ?? null,
-                delegatedById: input.delegatedById ?? null,
-                recordedAt: now,
-            });
-            if (deps.watermark)
-                await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
-        });
+        await deps.repo.transaction({ fn: async () => {
+                // The check that actually closes the race: two concurrent first-widget creates both see the
+                // pre-check above return null, but only one of them can win this in-tx re-check before save.
+                const existingInTx = await deps.repo.findByKey({ workspaceId: input.workspaceId, key: input.key });
+                if (existingInTx) {
+                    throw new ContentTypeAlreadyExistsError({ key: input.key, tombstoned: existingInTx.status === "tombstone" });
+                }
+                await deps.repo.save(contentType);
+                await deps.repo.appendRevision({
+                    contentTypeKey: input.key,
+                    workspaceId: input.workspaceId,
+                    op: "register",
+                    stateJson: contentType,
+                    actorId: input.actorId,
+                    principalKind: input.principalKind ?? null,
+                    delegatedByWorkspaceId: input.delegatedByWorkspaceId ?? null,
+                    delegatedById: input.delegatedById ?? null,
+                    recordedAt: now,
+                });
+                if (deps.watermark)
+                    await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
+            } });
     }
     catch (err) {
         if (err instanceof ContentTypeAlreadyExistsError)
@@ -140,47 +142,47 @@ export async function registerContentType(required) {
     return { ok: true, value: { contentType } };
 }
 /**
- * REQ-26 — full-replace of a content type's field schema. CIC U-004-B1: `expectedVersion` is
+ * — full-replace of a content type's field schema. : `expectedVersion` is
  * checked BEFORE the `fields_empty` floor and before any per-field guard, so a stale version
  * combined with an empty array reports `VERSION_CONFLICT`, never `VALIDATION_ERROR`.
  *
  * @complexity O(f) in the number of submitted fields.
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 export async function updateContentTypeFields(required) {
     const { deps, input } = required;
     const authResult = await deps.authorize({
         principalId: input.actorId,
         permission: "admin.collections.manage",
-        workspaceId: input.workspaceId,
-        entityType: "content-type",
-    });
+        workspaceId: input.workspaceId
+    }, { entityType: "content-type" });
     if (!authResult.allowed) {
-        return { ok: false, error: new ForbiddenError(`principal '${input.actorId}' cannot update content type '${input.key}' (${authResult.reason})`) };
+        return { ok: false, error: new ForbiddenError({ message: `principal '${input.actorId}' cannot update content type '${input.key}' (${authResult.reason})` }) };
     }
     const current = await deps.repo.findByKey({ workspaceId: input.workspaceId, key: input.key });
     if (!current) {
-        return { ok: false, error: new ContentTypeNotFoundError(`content type '${input.key}' was not found in workspace '${input.workspaceId}'`) };
+        return { ok: false, error: new ContentTypeNotFoundError({ message: `content type '${input.key}' was not found in workspace '${input.workspaceId}'` }) };
     }
-    // Row 15's sibling — a tombstoned type is terminal (INV-06); this check runs before the version
+    // Row 15's sibling — a tombstoned type is terminal; this check runs before the version. See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
     // check so a stale-version update against a tombstoned row still reports "tombstoned", not
     // "version conflict" (the tombstone tore down every queryable index, so the schema is moot).
     if (current.status === "tombstone") {
-        return { ok: false, error: new EntityNotLiveError("content type", input.key, "tombstoned") };
+        return { ok: false, error: new EntityNotLiveError({ entityType: "content type", entityId: input.key, state: "tombstoned" }) };
     }
-    // U-004-B1: expectedVersion checked FIRST — before fields_empty, before any per-field guard.
+    // expectedVersion checked FIRST — before fields_empty, before any per-field guard. See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
     if (input.expectedVersion !== current.version) {
-        return { ok: false, error: new VersionConflictError(`expected version ${input.expectedVersion} for content type '${input.key}', found ${current.version}`) };
+        return { ok: false, error: new VersionConflictError({ message: `expected version ${input.expectedVersion} for content type '${input.key}', found ${current.version}` }) };
     }
     if (input.fields.length === 0) {
-        return { ok: false, error: new ValidationError(`content type '${input.key}' update submitted an empty fields array`, "fields_empty") };
+        return { ok: false, error: new ValidationError({ message: `content type '${input.key}' update submitted an empty fields array`, reason: "fields_empty" }) };
     }
     const nameErrorOnUpdate = fieldNameError(input.fields);
     if (nameErrorOnUpdate)
         return { ok: false, error: nameErrorOnUpdate };
     for (const field of input.fields) {
-        if (!isContentTypeFieldKind(field.kind)) {
-            return { ok: false, error: new InvalidFieldKindError(`field '${field.name}' has kind '${field.kind}', not one of the closed field-kind enum`) };
+        if (!isContentTypeFieldKind({ value: field.kind })) {
+            return { ok: false, error: new InvalidFieldKindError({ message: `field '${field.name}' has kind '${field.kind}', not one of the closed field-kind enum` }) };
         }
     }
     // Guard 4b: a storage-only kind cannot be queryable. Placed strictly between guard 4 and guard 5
@@ -188,36 +190,36 @@ export async function updateContentTypeFields(required) {
     // BEFORE the cap count and long before `resolveFieldIndexTransition` could hand it to the index
     // provisioner. This is the check that keeps a kind with no CAST target off the DDL path.
     for (const field of input.fields) {
-        if (field.queryable && !isIndexableFieldKind(field.kind)) {
+        if (field.queryable && !isIndexableFieldKind({ value: field.kind })) {
             return {
                 ok: false,
-                error: new StorageOnlyFieldNotQueryableError(`field '${field.name}' has storage-only kind '${field.kind}' and cannot be queryable`),
+                error: new StorageOnlyFieldNotQueryableError({ message: `field '${field.name}' has storage-only kind '${field.kind}' and cannot be queryable` }),
             };
         }
     }
     if (countQueryableFields(input.fields) > QUERYABLE_FIELD_CAP) {
-        return { ok: false, error: new QueryableFieldCapExceededError(`content type '${input.key}' submits more than ${QUERYABLE_FIELD_CAP} queryable fields`) };
+        return { ok: false, error: new QueryableFieldCapExceededError({ message: `content type '${input.key}' submits more than ${QUERYABLE_FIELD_CAP} queryable fields` }) };
     }
     const before = current.fields;
     const after = input.fields;
-    const now = deps.clock.nowIso();
+    const now = kernelNowIso({ clock: deps.clock });
     const updated = { ...current, fields: after, label: input.label ?? current.label, version: current.version + 1 };
-    await deps.repo.transaction(async () => {
-        await deps.repo.save(updated);
-        await deps.repo.appendRevision({
-            contentTypeKey: input.key,
-            workspaceId: input.workspaceId,
-            op: "field-change",
-            stateJson: updated,
-            actorId: input.actorId,
-            principalKind: input.principalKind ?? null,
-            delegatedByWorkspaceId: input.delegatedByWorkspaceId ?? null,
-            delegatedById: input.delegatedById ?? null,
-            recordedAt: now,
-        });
-        if (deps.watermark)
-            await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
-    });
+    await deps.repo.transaction({ fn: async () => {
+            await deps.repo.save(updated);
+            await deps.repo.appendRevision({
+                contentTypeKey: input.key,
+                workspaceId: input.workspaceId,
+                op: "field-change",
+                stateJson: updated,
+                actorId: input.actorId,
+                principalKind: input.principalKind ?? null,
+                delegatedByWorkspaceId: input.delegatedByWorkspaceId ?? null,
+                delegatedById: input.delegatedById ?? null,
+                recordedAt: now,
+            });
+            if (deps.watermark)
+                await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
+        } });
     await deps.indexProvisioner.applyFieldIndexTransitions({
         workspaceId: input.workspaceId,
         contentTypeKey: input.key,
@@ -226,12 +228,13 @@ export async function updateContentTypeFields(required) {
     return { ok: true, value: { contentType: updated } };
 }
 /**
- * CIC U-003-B1 composition — resolves an index transition for every field name present on either
+ * composition — resolves an index transition for every field name present on either
  * side of a full-replace update (union of before/after names), one before/after comparison per
  * name, and returns only the actionable (non-`"none"`) transitions.
  *
  * @complexity O(f) in the number of distinct field names across both arrays.
  * @overallScore 100
+ * See docs/decisions/DR-001-safe-schema-and-index-transitions.md.
  */
 function computeFullReplaceTransitions(before, after) {
     const beforeByName = new Map(before.map((f) => [f.name, f]));

package/dist/core/authorization.d.ts

@@ -0,0 +1,15 @@
+/** Caller-supplied authorization evaluator shared by content domain write services. */
+export interface AuthorizationRequired {
+    principalId: string;
+    permission: string;
+    workspaceId: string;
+}
+export interface AuthorizationOptional {
+    entityType?: string | undefined;
+    entityId?: string | undefined;
+}
+export type AuthorizationPort = (required: AuthorizationRequired, optional?: AuthorizationOptional) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+//# sourceMappingURL=authorization.d.ts.map

package/dist/core/authorization.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=authorization.js.map

package/dist/core/commands/change-set.d.ts

@@ -1,4 +1,5 @@
-import type { DomainEvent, ISODateTime, JsonObject, UUID } from "../ports.js";
+import type { ISODateTime, JsonObject, UUID } from "@jini-ai/core/primitives";
+import type { DomainEvent } from "../ports.js";
 /**
  * @file Change-set vocabulary and persistence contract.
  *
@@ -15,7 +16,7 @@ import type { DomainEvent, ISODateTime, JsonObject, UUID } from "../ports.js";
  * This is the storage shape required to land with the first persistent
  * schema. SQLite/Postgres adapters must satisfy `ChangeSetRepoPort` unchanged.
  *
- * `insert()`'s optional third argument lets the caller pass the fully-formed outbox event through
+ * `insert()`'s optional event in its second object lets the caller pass the fully-formed outbox event through
  * the SAME call, so a durable adapter can co-persist it inside the same transaction as the header
  * + items. This does NOT bring the domain write (`mutation.execute()`) into the transaction — that
  * remains covered by `executeCommand()`'s existing compensating-rollback path. See
@@ -59,10 +60,11 @@ export interface ChangeSetItemRecord {
      */
     inversePayload?: JsonObject | undefined;
     /**
-     * Entity version *after* the mutation (REQ-08 guard input). Revert refuses
+     * Entity version *after* the mutation ( guard input). Revert refuses
      * unless the entity's current version still equals this — otherwise the entity
      * has moved on since. Undefined for entity types without a version.
-     */
+   * See docs/decisions/DR-006-mutation-audit-atomicity.md.
+   */
     entityVersionAtApply?: number | undefined;
     /** Apply order; revert walks positions in reverse. */
     position: number;
@@ -75,12 +77,18 @@ export interface ChangeSetWithItems {
 /** Persistence contract for change sets. */
 export interface ChangeSetRepoPort {
     /**
-     * `event`, when present, must be durably recorded atomically with `record`/`items` (BR-04 —
+     * `event`, when present, must be durably recorded atomically with `record`/`items` ( —
      * see this file's header). A SQLite adapter co-persists it inside the same transaction; the
      * in-memory adapter forwards it to its injected event bus/outbox. Omit `event` for a change set
      * that has no associated domain event to deliver.
-     */
-    insert(record: ChangeSetRecord, items: ChangeSetItemRecord[], event?: DomainEvent): Promise<void>;
+   * See docs/decisions/DR-006-mutation-audit-atomicity.md.
+   */
+    insert(required: {
+        record: ChangeSetRecord;
+        items: ChangeSetItemRecord[];
+    }, optional?: {
+        event?: DomainEvent | undefined;
+    }): Promise<void>;
     findById(required: {
         workspaceId: UUID;
         id: UUID;

package/dist/core/commands/command.d.ts

@@ -1,4 +1,5 @@
-import type { ClockPort, IdGeneratorPort, JsonObject, OutboxPort, UUID } from "../ports.js";
+import type { Clock, IdGenerator, JsonObject, UUID } from "@jini-ai/core/primitives";
+import type { OutboxPort } from "../ports.js";
 import type { ChangeSetOperation, ChangeSetRepoPort } from "./change-set.js";
 /**
  * @file The single mutation write path.
@@ -58,20 +59,27 @@ export interface CommandMutation<TResult> {
     execute(): Promise<TResult>;
     /**
      * Read the entity's version from the execute result (the version *after* the
-     * mutation, REQ-08 / AC-02). Stamped onto the item as the revert guard input.
+     * mutation). Stamped onto the item as the revert guard input.
      * Omit for entity types without a version.
-     */
-    captureEntityVersion?(result: TResult): number | null;
+   * See docs/decisions/DR-006-mutation-audit-atomicity.md.
+   */
+    captureEntityVersion?(required: {
+        result: TResult;
+    }, optional?: Record<string, never>): number | null;
     /**
      * Compensating rollback for the memory adapter's all-or-nothing guarantee
-     * (REQ-01 / BR-04 / EC-08 / AC-17). If the change-set record fails to persist
-     * *after* `execute()` has applied the feature mutation, the gateway calls this
+     * If version capture, record preparation or persistence fails
+     * *after* `execute` has applied the feature mutation, the gateway calls this
      * to undo the mutation — restoring the entity to its exact pre-`execute` state
      * (verbatim, including `version`) so no "mutation without a record" survives
-     * (INV-01). On the SQLite adapter (RT-004) a real transaction replaces this and
-     * `rollback` becomes a no-op/omitted. Omit only for a mutation whose record step
-     * cannot fail independently of its feature write (none in v1).
-     */
+     * On the SQLite adapter a real transaction replaces this and
+     * `rollback` may be a no-op/omitted only when a caller-owned transaction covers
+     * the feature write AND all subsequent record preparation/persistence. The gateway
+     * opens no such transaction itself. Without rollback or that outer transaction, a
+     * post-mutation failure rejects but leaves the feature mutation applied (
+     * is not guaranteed). A rollback rejection takes precedence over the original error.
+   * See docs/decisions/DR-006-mutation-audit-atomicity.md.
+   */
     rollback?(): Promise<void>;
 }
 /**
@@ -95,8 +103,8 @@ export type AuthorizeFn = (params: {
 }>;
 /** Dependencies for executeCommand. */
 export interface ExecuteCommandDeps {
-    clock: ClockPort;
-    idGen: IdGeneratorPort;
+    clock: Clock;
+    idGen: IdGenerator;
     changeSets: ChangeSetRepoPort;
     /** When provided, `change-set.applied` is enqueued for async consumers. */
     outbox?: OutboxPort | undefined;
@@ -126,18 +134,26 @@ export interface ExecuteCommandOptional {
  */
 export declare class DuplicateCommandError extends Error {
     readonly changeSetId: UUID;
-    constructor(message: string, changeSetId: UUID);
+    constructor(requiredArgs: {
+        message: string;
+        changeSetId: UUID;
+    }, optionalArgs?: Record<string, never>);
 }
 /**
- * Thrown when `authorize()` denies the caller. Routes map
- * this to 403 `FORBIDDEN`. Raised before the idempotency check (INV-04) — a
+ * Thrown when `authorize` denies the caller. Routes map
+ * this to 403 `FORBIDDEN`. Raised before the idempotency check — a
  * replayed command id from a denied caller therefore never produces
- * `DuplicateCommandError` either (EC-08).
+ * `DuplicateCommandError` either.
+ * See docs/decisions/DR-006-mutation-audit-atomicity.md.
  */
 export declare class ForbiddenError extends Error {
     readonly permission: string;
     readonly reason: string;
-    constructor(message: string, permission: string, reason: string);
+    constructor({ message, permission, reason }: {
+        message: string;
+        permission: string;
+        reason: string;
+    }, _optional?: Record<string, never>);
 }
 /**
  * Execute a mutation through the command gateway.
@@ -146,20 +162,23 @@ export declare class ForbiddenError extends Error {
  * If execute throws, nothing is recorded; if inverse capture throws, the
  * mutation never runs.
  *
- * The feature mutation and its change-set record commit as one unit of work
- * (REQ-01): if `changeSets.insert` fails after `execute` has applied the
- * mutation, the gateway rolls the mutation back via `mutation.rollback` and
- * re-throws, so no change set and no outbox event survive (EC-08 / AC-17,
- * INV-01).
+ * With a working `mutation.rollback`, the feature mutation and its change-set
+ * record form one compensated unit of work : failures in version capture,
+ * record preparation or `changeSets.insert` after `execute` trigger rollback and
+ * rejection. When rollback is omitted, the gateway still
+ * rejects but cannot undo the applied feature mutation; a caller-owned outer
+ * transaction must supply atomicity. Record/event atomicity depends on the repo
+ * honoring its port contract.
  *
- * The `change-set.applied` event is passed as `changeSets.insert()`'s third argument, not a
- * separate `deps.outbox.enqueue()` call afterward — a durable adapter co-persists it inside the
+ * The `change-set.applied` event is passed in `changeSets.insert`'s optional object, not a
+ * separate `deps.outbox.enqueue` call afterward — a durable adapter co-persists it inside the
  * same transaction as the change-set record, so it can never land without a durable delivery
  * record (or vice versa). This still does NOT cover the domain mutation itself
- * (`mutation.execute()` stays outside any shared transaction, covered only by the compensating
+ * (`mutation.execute` stays outside any shared transaction, covered only by the compensating
  * rollback above), and it covers only this producer. See
  * `docs/decisions/change-set-outbox-transaction-boundary.md` for the full rationale, including the
- * other direct `OutboxPort.enqueue()` producers this decision deliberately leaves untouched.
+ * other direct `OutboxPort.enqueue` producers this decision deliberately leaves untouched.
+ * See docs/decisions/DR-006-mutation-audit-atomicity.md.
  */
 export declare function executeCommand<TResult>(required: ExecuteCommandRequired<TResult>, _optional?: ExecuteCommandOptional): Promise<{
     result: TResult;