@jini-ai/cms 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.0 — 2026-10-05
+
+### BREAKING
+
+- Entries: an entry's envelope owner comes from its content type, not the caller. `createEntry`/`updateEntry`/`importEntry` drop `input.owner` (a stray runtime value is ignored) and validate under `contentType.owner`; `ContentTypeRecord`/`OwningContentType` gain an optional `owner` (absent = `"site"`, so existing types are byte-identical) and `registerContentType` accepts one. Callers that passed `owner` register the type with its owner instead.
+- Entries, BREAKING for `EntryRepoPort` adapters: `save` takes `{ expectedVersion }` and must compare it atomically with the write inside the transaction (`VersionConflictError` thrown there becomes the Result's `{ ok: false }`). `expectedVersion: null` means "the id must be free" (live, trashed or another workspace); an import-as-create passes it, so two concurrent creates of one id no longer both land. New exports `EntrySaveOptions`, `entryVersionConflictError`; `InMemoryEntryRepo` implements both.
+- Navigation, BREAKING for `MenuRepoPort` adapters: `save` takes `{ expectedVersion }` and compares it atomically with the write; `updateMenuTree` and both `assignLocation` saves pass it. New exports `MenuSaveOptions`, `menuVersionConflictError`; `InMemoryMenuRepo` implements it (a trashed or missing row is "found none").
+
+### Changed
+
+- Content types: tombstoning tears down a type's indexes after the status save commits, not before, so a failed save no longer leaves a still-deprecated type with its indexes gone.
+- Entries: `updateEntry`, `publishEntry`/`unpublishEntry` and an import-as-update again refuse an `expectedVersion` that differs from the version they read (`VersionConflictError`), in addition to the save's compare-and-set. The compare-and-set alone let a record built from an older read overwrite a writer that landed the claimed version after that read.
+- Navigation: `updateMenuTree` restores the same read check. New `MenuVersionConflictError` (a `MenuConflictError` subclass) is what `menuVersionConflictError` and that check throw, so a host can tell a lost version check from a slug conflict.
+- Navigation, BREAKING for `MenuRepoPort` adapters: the port gains `transaction({ fn })`, and `assignLocation` runs both menu saves, the binding upsert and its outbox events inside it, so a conflict on the second save no longer leaves the displaced menu changed. `InMemoryMenuRepo.transaction` just runs `fn` (no rollback).
+- Navigation: `MenuSaveOptions.expectedVersion` accepts `null` — insert only when no row (live, trashed, any workspace) holds the id — for a host's id-preserving import-as-create; the loser gets `menu '<id>' already exists (expected no menu, found version <n>)`.
+
 ## 0.4.2 — 2026-10-04
 
 - Media: optional `BlobStorePort.sizeOf` reports original blob bytes (filesystem store memoizes `stat`); `MediaRecord.createdBy` is stamped at creation and write-once.

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

@@ -95,7 +95,7 @@ export interface TombstoneContentTypeRequired {
  * — the one-way terminal transition into `tombstone`. Must be entered from
  * `deprecated` (any other status, including an already-tombstoned row, is rejected with the same
  * "must deprecate first" guard — collapse to one check). Tears down every queryable-
- * field index the type ever provisioned BEFORE persisting the status flip, and enqueues
+ * field index the type ever provisioned AFTER persisting the status flip, and enqueues
  * `content_type.tombstoned` in the same call.
  *
  * @complexity O(1) plus one repo read, one index-teardown call, one same-tx write pair, and one

package/dist/content-types/lifecycle.js

@@ -99,7 +99,7 @@ export async function reactivateContentType(required) {
  * — the one-way terminal transition into `tombstone`. Must be entered from
  * `deprecated` (any other status, including an already-tombstoned row, is rejected with the same
  * "must deprecate first" guard — collapse to one check). Tears down every queryable-
- * field index the type ever provisioned BEFORE persisting the status flip, and enqueues
+ * field index the type ever provisioned AFTER persisting the status flip, and enqueues
  * `content_type.tombstoned` in the same call.
  *
  * @complexity O(1) plus one repo read, one index-teardown call, one same-tx write pair, and one
@@ -129,7 +129,6 @@ export async function tombstoneContentType(required) {
     }
     const now = kernelNowIso({ clock: deps.clock });
     const updated = { ...current, status: "tombstone", tombstonedAt: now, version: current.version + 1 };
-    await deps.indexProvisioner.tearDownAllIndexesForContentType({ workspaceId: input.workspaceId, contentTypeKey: input.key });
     await deps.repo.transaction({ fn: async () => {
             await deps.repo.save(updated);
             await deps.repo.appendRevision({
@@ -144,6 +143,11 @@ export async function tombstoneContentType(required) {
                 recordedAt: now,
             });
         } });
+    // AFTER the save commits, never before (wm S5): teardown is not part of the repo transaction, so
+    // tearing down first meant a save that threw left a still-'deprecated' type — whose entries stay
+    // fully readable/writable — with every queryable index already gone. In this order a failed save
+    // touches nothing, and a failed teardown leaves only unused indexes on an already-terminal type.
+    await deps.indexProvisioner.tearDownAllIndexesForContentType({ workspaceId: input.workspaceId, contentTypeKey: input.key });
     await deps.outbox.enqueue({ name: "content_type.tombstoned", payload: { workspaceId: input.workspaceId, key: input.key } });
     return { ok: true, value: { contentType: updated } };
 }

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

@@ -116,6 +116,17 @@ export interface ContentTypeRecord {
     status: ContentTypeStatus;
     version: number;
     tombstonedAt?: string | null;
+    /**
+     * The `fieldsJson.ext.<owner>` namespace every entry of this type is stored under. Absent means
+     * `"site"`, so every type registered before this property existed keeps its envelope unchanged.
+     * It belongs to the TYPE, not to whoever writes an entry: `entries/write-service.ts` reads it off
+     * the owning type, so no caller can validate a payload under the wrong namespace and mint a row
+     * the type's real reader can never parse (found 2026-09-19: the generic entries route passed no
+     * owner and wrote `ext.site` rows into a widget-owned type). Set only by code that registers its
+     * own type (`registerContentType`'s optional `owner`); the agent tool and HTTP surfaces never
+     * pass it.
+     */
+    owner?: string;
 }
 /**
  * Actor classes a chokepoint write can be attributed to. Structurally identical to

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

@@ -117,6 +117,12 @@ export interface RegisterContentTypeRequired {
         key: string;
         label: string;
         fields: ContentTypeFieldDef[];
+        /**
+         * The `fieldsJson.ext.<owner>` namespace this type's entries are stored under; omit for the
+         * default `"site"`. For code that registers its OWN type (e.g. a host's widgets feature); the
+         * agent tool and HTTP surfaces deliberately never pass it. See `ContentTypeRecord.owner`.
+         */
+        owner?: string | undefined;
     };
 }
 /**

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

@@ -57,6 +57,11 @@ export async function registerContentType(required) {
     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 1b: owner grammar, only when one is given. It becomes an object key inside every entry's
+    // `fieldsJson.ext`, so it gets the same identifier gate as the type key.
+    if (input.owner !== undefined && !validateIdentifierGrammar({ value: input.owner })) {
+        return { ok: false, error: new InvalidKeyGrammarError({ message: `content-type owner '${input.owner}' 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({ message: `key '${input.key}' is permanently reserved for the legacy 'posts' table` }) };
@@ -102,6 +107,8 @@ export async function registerContentType(required) {
         status: "active",
         version: 1,
         tombstonedAt: null,
+        // Only set when given, so a type registered without one stays byte-identical to before `owner` existed.
+        ...(input.owner !== undefined ? { owner: input.owner } : {}),
     };
     try {
         await deps.repo.transaction({ fn: async () => {

package/dist/entries/errors.d.ts

@@ -41,6 +41,13 @@ export declare class VersionConflictError extends Error {
         message: string;
     }, optionalArgs?: Record<string, never>);
 }
+/** The compare-and-set loss every `EntryRepoPort.save` adapter throws (one wording for all of them).
+ *  `expectedVersion: null` is a create that found the id taken. */
+export declare function entryVersionConflictError(required: {
+    id: string;
+    expectedVersion: number | null;
+    found: number | null;
+}): VersionConflictError;
 /** — `fieldsJson` failed `validateFieldsAgainstSchema` against the owning type's current schema. See docs/decisions/DR-002-content-lifecycle-and-cleanup.md. */
 export declare class EntryFieldValidationError extends Error {
     readonly fieldErrors: Array<{

package/dist/entries/errors.js

@@ -52,6 +52,12 @@ export class VersionConflictError extends Error {
         this.name = "VersionConflictError";
     }
 }
+/** The compare-and-set loss every `EntryRepoPort.save` adapter throws (one wording for all of them).
+ *  `expectedVersion: null` is a create that found the id taken. */
+export function entryVersionConflictError(required) {
+    const expected = required.expectedVersion === null ? "no entry" : `version ${required.expectedVersion} for entry`;
+    return new VersionConflictError({ message: `expected ${expected} '${required.id}', found ${required.found ?? "none"}` });
+}
 /** — `fieldsJson` failed `validateFieldsAgainstSchema` against the owning type's current schema. See docs/decisions/DR-002-content-lifecycle-and-cleanup.md. */
 export class EntryFieldValidationError extends Error {
     fieldErrors;

package/dist/entries/field-validation.d.ts

@@ -21,6 +21,9 @@ import type { ContentTypeFieldDef } from "../content-types/types.js";
  * documented `fields.ext.{owner}.*` promise (first surfaced by a widgets feature, which needs
  * `ext.widget`/`ext.widgets`, not `ext.site`, for data that structurally belongs to a different
  * feature).
+ * Since 2026-10-04 `write-service.ts` passes the OWNING TYPE's `owner` here, never a caller's: the
+ * caller-chosen version let the generic entries route (which passed none) validate a widget
+ * payload under `ext.site` and write a row the widgets reader can never parse.
  * `selectVisibleEntryFields` is intentionally left untouched — it has no production caller anywhere
  * in this codebase today, so widening it now would be speculative; extend it the same way once a
  * real caller needs a non-`site` read projection.

package/dist/entries/index.d.ts

@@ -25,10 +25,10 @@ export { validateFieldsAgainstSchema, selectVisibleEntryFields } from "./field-v
  * separation is inherited from the source this was ported from; a consumer catching across the
  * boundary must catch the one it actually called into.
  */
-export { ForbiddenError, EntryNotFoundError, ContentTypeNotFoundError, ContentTypeNotActiveError, EntrySlugConflictError, VersionConflictError, EntryFieldValidationError, } from "./errors.js";
+export { ForbiddenError, EntryNotFoundError, ContentTypeNotFoundError, ContentTypeNotActiveError, EntrySlugConflictError, VersionConflictError, EntryFieldValidationError, entryVersionConflictError, } from "./errors.js";
 export type { EntryLifecycleOp, EntryLifecycleHandler } from "./lifecycle-dispatch.js";
 export { ENTRY_LIFECYCLE_OP_NAMES, ENTRY_LIFECYCLE_OPS, parseEntryLifecycleOp, } from "./lifecycle-dispatch.js";
-export type { AuthorizeFn, EntryRevisionInput, EntryRepoPort, ContentTypeLookupPort, OutboxPort, WatermarkPort, CreateEntryRequired, UpdateEntryRequired, PublishUnpublishEntryRequired, ImportEntryRequired, } from "./write-service.js";
+export type { AuthorizeFn, EntryRevisionInput, EntryRepoPort, EntrySaveOptions, ContentTypeLookupPort, OutboxPort, WatermarkPort, CreateEntryRequired, UpdateEntryRequired, PublishUnpublishEntryRequired, ImportEntryRequired, } from "./write-service.js";
 export { createEntry, updateEntry, publishEntry, unpublishEntry, importEntry } from "./write-service.js";
 /**
  * The in-memory repository. Exported for the same reason `navigation` exports its own: a host's

package/dist/entries/index.js

@@ -10,7 +10,7 @@ export { validateFieldsAgainstSchema, selectVisibleEntryFields } from "./field-v
  * separation is inherited from the source this was ported from; a consumer catching across the
  * boundary must catch the one it actually called into.
  */
-export { ForbiddenError, EntryNotFoundError, ContentTypeNotFoundError, ContentTypeNotActiveError, EntrySlugConflictError, VersionConflictError, EntryFieldValidationError, } from "./errors.js";
+export { ForbiddenError, EntryNotFoundError, ContentTypeNotFoundError, ContentTypeNotActiveError, EntrySlugConflictError, VersionConflictError, EntryFieldValidationError, entryVersionConflictError, } from "./errors.js";
 export { ENTRY_LIFECYCLE_OP_NAMES, ENTRY_LIFECYCLE_OPS, parseEntryLifecycleOp, } from "./lifecycle-dispatch.js";
 export { createEntry, updateEntry, publishEntry, unpublishEntry, importEntry } from "./write-service.js";
 /**

package/dist/entries/repo.memory.d.ts

@@ -1,5 +1,5 @@
 import type { Clock } from "@jini-ai/core/primitives";
-import type { EntryRepoPort, EntryRevisionInput, OutboxPort } from "./write-service.js";
+import type { EntryRepoPort, EntryRevisionInput, EntrySaveOptions, OutboxPort } from "./write-service.js";
 import type { EntryListPort } from "./list.js";
 import type { EntryRecord, EntryStatus } from "./types.js";
 /**
@@ -20,7 +20,7 @@ export declare class InMemoryEntryRepo implements EntryRepoPort, EntryListPort {
         workspaceId: string;
         id: string;
     }): Promise<EntryRecord | null>;
-    save(row: EntryRecord): Promise<void>;
+    save(row: EntryRecord, options?: EntrySaveOptions): Promise<void>;
     appendRevision(revision: EntryRevisionInput): Promise<void>;
     transaction<T>({ fn }: {
         fn: () => Promise<T>;

package/dist/entries/repo.memory.js

@@ -1,4 +1,5 @@
 import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
+import { entryVersionConflictError } from "./errors.js";
 /**
  * @file In-memory `EntryRepoPort` + `EntryListPort` double (same disclosed rule-of-two-until-a-
  * real-adapter-exists precedent as `features/content-types/repo.memory.ts` — see that file's
@@ -22,7 +23,15 @@ export class InMemoryEntryRepo {
         const row = this.byId.get(params.id);
         return row && row.workspaceId === params.workspaceId ? { ...row } : null;
     }
-    async save(row) {
+    async save(row, options = {}) {
+        if (options.expectedVersion !== undefined) {
+            const stored = this.byId.get(row.id);
+            // A create (`null`) needs the id free in every workspace: the id is the key here, as the
+            // primary key is in a SQL adapter, so a foreign row with it would be overwritten.
+            const found = stored && (options.expectedVersion === null || stored.workspaceId === row.workspaceId) ? stored.version : null;
+            if (found !== options.expectedVersion)
+                throw entryVersionConflictError({ id: row.id, expectedVersion: options.expectedVersion, found });
+        }
         this.byId.set(row.id, { ...row });
     }
     async appendRevision(revision) {

package/dist/entries/types.d.ts

@@ -38,6 +38,8 @@ export interface OwningContentType {
     key: string;
     status: ContentTypeStatus;
     fields: ContentTypeFieldDef[];
+    /** The `fieldsJson.ext.<owner>` namespace this type's entries live under; absent = `"site"`. See `content-types/types.ts`'s `ContentTypeRecord.owner`. */
+    owner?: string | undefined;
 }
 export interface ActorIdentityInput {
     actorId: string;

package/dist/entries/write-service.d.ts

@@ -51,6 +51,12 @@ export interface EntryRevisionInput {
     delegatedById: string | null;
     recordedAt: string;
 }
+/** Options for {@link EntryRepoPort.save}. */
+export interface EntrySaveOptions {
+    /** The version the caller read; the save throws `VersionConflictError` unless the stored live row still holds it.
+     *  `null` is a create: the save throws unless no row (live, trashed, or in another workspace) holds the id. */
+    expectedVersion?: number | null | undefined;
+}
 export interface EntryRepoPort {
     findBySlug(params: {
         workspaceId: string;
@@ -61,7 +67,16 @@ export interface EntryRepoPort {
         workspaceId: string;
         id: string;
     }): Promise<EntryRecord | null>;
-    save(row: EntryRecord): Promise<void>;
+    /**
+     * Writes `row` by id. With `expectedVersion`, the write is a compare-and-set: it lands only when the
+     * stored live (not trashed) row still holds that version, checked atomically with the write (one
+     * conditional UPDATE in a SQL adapter), so two writers that read the same version cannot both land.
+     * With `expectedVersion: null` it is insert-if-absent (an import-as-create; `INSERT ... ON CONFLICT DO
+     * NOTHING` in a SQL adapter), so two creates of one id cannot both land either.
+     * Without it, the write is unconditional (`createEntry`'s freshly minted id, trash seams).
+     * @throws VersionConflictError ``expected version <n> for entry '<id>', found <stored|none>`` ({@link entryVersionConflictError}).
+     */
+    save(row: EntryRecord, options?: EntrySaveOptions): Promise<void>;
     appendRevision(revision: EntryRevisionInput): Promise<void>;
     transaction<T>(required: {
         fn: () => Promise<T>;
@@ -111,8 +126,6 @@ export interface CreateEntryRequired {
         title: string;
         fieldsJson: unknown;
         bodyJson?: unknown;
-        /** The `ext` sub-key `fieldsJson` is namespaced under. Defaults to `"site"` — see `field-validation.ts`'s `validateFieldsAgainstSchema`. */
-        owner?: string | undefined;
     };
 }
 /**
@@ -164,8 +177,6 @@ export interface UpdateEntryRequired {
          */
         bodyJson?: unknown;
         expectedVersion: number;
-        /** The `ext` sub-key `fieldsJson` is namespaced under. Defaults to `"site"` — see `field-validation.ts`'s `validateFieldsAgainstSchema`. */
-        owner?: string | undefined;
     };
 }
 /**
@@ -211,11 +222,11 @@ export interface ImportEntryRequired {
          * The publish factory's three-way CAS contract: `undefined` means "no row with this id may
          * already exist" (an import-as-create); a number means "a row with this id must exist and be
          * at exactly this version" (an import-as-update). Both cases end in `VersionConflictError` on
-         * mismatch, never a silent create-over-existing or a silent no-op.
+         * mismatch, never a silent create-over-existing or a silent no-op. Both are also enforced by the
+         * save itself (`undefined` becomes the save's `expectedVersion: null`), because the `findById`
+         * check below let two concurrent creates of one id both pass and the second overwrite the first.
          */
         expectedVersion: number | undefined;
-        /** The `ext` sub-key `fieldsJson` is namespaced under. Defaults to `"site"` — see `field-validation.ts`'s `validateFieldsAgainstSchema`. */
-        owner?: string | undefined;
     };
 }
 /**

package/dist/entries/write-service.js

@@ -1,5 +1,5 @@
 import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
-import { ContentTypeNotActiveError, ContentTypeNotFoundError, EntryFieldValidationError, EntryNotFoundError, EntrySlugConflictError, ForbiddenError, VersionConflictError, } from "./errors.js";
+import { ContentTypeNotActiveError, ContentTypeNotFoundError, EntryFieldValidationError, EntryNotFoundError, EntrySlugConflictError, entryVersionConflictError, ForbiddenError, VersionConflictError, } from "./errors.js";
 import { validateFieldsAgainstSchema } from "./field-validation.js";
 function delegationFields(input) {
     return {
@@ -33,7 +33,11 @@ export async function createEntry(required) {
         // See docs/decisions/DR-002-content-lifecycle-and-cleanup.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
         return { ok: false, error: new ContentTypeNotActiveError({ message: `content type '${input.type}' is not active; new entries cannot be created` }) };
     }
-    const validation = validateFieldsAgainstSchema({ schema: contentType.fields, fieldsJson: input.fieldsJson }, { owner: input.owner });
+    // The envelope namespace comes from the owning TYPE, never the caller (2026-10-04). It used to be
+    // `input.owner` defaulting to "site": the generic entries route passed none, so a widget-owned
+    // type's payload validated under `ext.site` and wrote a row the widgets reader could never parse.
+    // The same rule holds in `updateEntry` and `importEntry` below.
+    const validation = validateFieldsAgainstSchema({ schema: contentType.fields, fieldsJson: input.fieldsJson }, { owner: contentType.owner });
     if (!validation.valid) {
         return { ok: false, error: new EntryFieldValidationError({ fieldErrors: validation.fieldErrors }) };
     }
@@ -78,8 +82,12 @@ export async function createEntry(required) {
 /**
  * shared resolve step for `updateEntry`/`publishEntry`/`unpublishEntry`: authorize ->
  * find the entry -> find its owning type -> reject ONLY if that type is `tombstone`
- * (`deprecated` blocks nothing here, unlike `createEntry`'s rule) -> `expectedVersion`
- * check.
+ * (`deprecated` blocks nothing here, unlike `createEntry`'s rule) -> `expectedVersion` must equal the
+ * version read. That check alone is not enough: the save's compare-and-set inside the write's
+ * transaction ({@link runVersionedWrite}) also checks it, because a check on this read let two writers
+ * that read the same version both land (wm S3). Nor is the compare-and-set alone: the caller's record
+ * is built from THIS read, so a basis that differs from it could match a version another writer lands
+ * after the read and overwrite that writer with a record built from the older row.
  *
  * @complexity O(1) plus one entry read and one content-type read.
  * @overallScore 100
@@ -100,10 +108,27 @@ async function resolveExistingEntryForTransition(deps, input) {
         return { ok: false, error: new ContentTypeNotActiveError({ message: `content type '${entry.type}' is tombstoned; existing entries cannot be updated/published/unpublished` }) };
     }
     if (input.expectedVersion !== entry.version) {
-        return { ok: false, error: new VersionConflictError({ message: `expected version ${input.expectedVersion} for entry '${input.id}', found ${entry.version}` }) };
+        return { ok: false, error: entryVersionConflictError({ id: input.id, expectedVersion: input.expectedVersion, found: entry.version }) };
     }
     return { ok: true, value: { entry, contentType } };
 }
+/**
+ * Runs a versioned write's transaction; a compare-and-set loss thrown by `save` inside it becomes
+ * the returned error (the callers return it as `{ ok: false }`, so HTTP routes keep their Result
+ * path). The transaction rolls the whole write back, so a loss leaves no revision or watermark.
+ * @throws whatever else the transaction throws.
+ */
+async function runVersionedWrite(entryRepo, fn) {
+    try {
+        await entryRepo.transaction({ fn });
+        return null;
+    }
+    catch (error) {
+        if (error instanceof VersionConflictError)
+            return error;
+        throw error;
+    }
+}
 /**
  * — updates an existing entry's `title`/`fieldsJson`/`bodyJson` (only the fields supplied
  * are changed). Rejected `ContentTypeNotActiveError` only if the owning type is `tombstone`
@@ -122,7 +147,7 @@ export async function updateEntry(required) {
     const { entry: current, contentType } = resolved.value;
     let fieldsJson = current.fieldsJson;
     if (input.fieldsJson !== undefined) {
-        const validation = validateFieldsAgainstSchema({ schema: contentType?.fields ?? [], fieldsJson: input.fieldsJson }, { owner: input.owner });
+        const validation = validateFieldsAgainstSchema({ schema: contentType?.fields ?? [], fieldsJson: input.fieldsJson }, { owner: contentType?.owner });
         if (!validation.valid) {
             return { ok: false, error: new EntryFieldValidationError({ fieldErrors: validation.fieldErrors }) };
         }
@@ -137,22 +162,24 @@ export async function updateEntry(required) {
         updatedAt: now,
         version: current.version + 1,
     };
-    await deps.entryRepo.transaction({ fn: async () => {
-            await deps.entryRepo.save(updated);
-            await deps.entryRepo.appendRevision({
-                entryId: current.id,
-                workspaceId: input.workspaceId,
-                op: "update",
-                stateJson: updated,
-                actorId: input.actorId,
-                ...delegationFields(input),
-                recordedAt: now,
-            });
-            if (deps.watermark)
-                await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
-            if (deps.onWritten)
-                await deps.onWritten(updated);
-        } });
+    const conflict = await runVersionedWrite(deps.entryRepo, async () => {
+        await deps.entryRepo.save(updated, { expectedVersion: input.expectedVersion });
+        await deps.entryRepo.appendRevision({
+            entryId: current.id,
+            workspaceId: input.workspaceId,
+            op: "update",
+            stateJson: updated,
+            actorId: input.actorId,
+            ...delegationFields(input),
+            recordedAt: now,
+        });
+        if (deps.watermark)
+            await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
+        if (deps.onWritten)
+            await deps.onWritten(updated);
+    });
+    if (conflict)
+        return { ok: false, error: conflict };
     await deps.outbox.enqueue({ name: "entry.updated", payload: { workspaceId: input.workspaceId, entryId: current.id } });
     return { ok: true, value: { entry: updated } };
 }
@@ -187,12 +214,13 @@ export async function importEntry(required) {
     if (contentType.status === "tombstone") {
         return { ok: false, error: new ContentTypeNotActiveError({ message: `content type '${input.type}' is tombstoned; entries cannot be imported into it` }) };
     }
-    const validation = validateFieldsAgainstSchema({ schema: contentType.fields, fieldsJson: input.fieldsJson }, { owner: input.owner });
+    const validation = validateFieldsAgainstSchema({ schema: contentType.fields, fieldsJson: input.fieldsJson }, { owner: contentType.owner });
     if (!validation.valid) {
         return { ok: false, error: new EntryFieldValidationError({ fieldErrors: validation.fieldErrors }) };
     }
     const existing = await deps.entryRepo.findById({ workspaceId: input.workspaceId, id: input.id });
     if (input.expectedVersion === undefined) {
+        // A create that lands between this read and the save is the save's insert-if-absent below.
         if (existing) {
             return { ok: false, error: new VersionConflictError({ message: `entry '${input.id}' already exists in workspace '${input.workspaceId}', but no expectedVersion was supplied for import` }) };
         }
@@ -201,8 +229,10 @@ export async function importEntry(required) {
         if (!existing) {
             return { ok: false, error: new VersionConflictError({ message: `expected version ${input.expectedVersion} for entry '${input.id}', but no such entry exists` }) };
         }
+        // Checked on this read AND by the save's compare-and-set below (wm S3): the record is built from
+        // this read, so a basis that differs from it must not reach a save that could match it.
         if (existing.version !== input.expectedVersion) {
-            return { ok: false, error: new VersionConflictError({ message: `expected version ${input.expectedVersion} for entry '${input.id}', found ${existing.version}` }) };
+            return { ok: false, error: entryVersionConflictError({ id: input.id, expectedVersion: input.expectedVersion, found: existing.version }) };
         }
         // Same id, different type means this is not the row the caller's plan was made against; a
         // silent type move would also dodge the tombstone check on the entry's REAL type. See docs/decisions/DR-002-content-lifecycle-and-cleanup.md.
@@ -225,22 +255,24 @@ export async function importEntry(required) {
         updatedAt: now,
         version: existing ? existing.version + 1 : 1,
     };
-    await deps.entryRepo.transaction({ fn: async () => {
-            await deps.entryRepo.save(entry);
-            await deps.entryRepo.appendRevision({
-                entryId: entry.id,
-                workspaceId: input.workspaceId,
-                op: existing ? "update" : "create",
-                stateJson: entry,
-                actorId: input.actorId,
-                ...delegationFields(input),
-                recordedAt: now,
-            });
-            if (deps.watermark)
-                await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
-            if (deps.onWritten)
-                await deps.onWritten(entry);
-        } });
+    const conflict = await runVersionedWrite(deps.entryRepo, async () => {
+        await deps.entryRepo.save(entry, { expectedVersion: input.expectedVersion ?? null });
+        await deps.entryRepo.appendRevision({
+            entryId: entry.id,
+            workspaceId: input.workspaceId,
+            op: existing ? "update" : "create",
+            stateJson: entry,
+            actorId: input.actorId,
+            ...delegationFields(input),
+            recordedAt: now,
+        });
+        if (deps.watermark)
+            await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
+        if (deps.onWritten)
+            await deps.onWritten(entry);
+    });
+    if (conflict)
+        return { ok: false, error: conflict };
     await deps.outbox.enqueue({ name: "entry.imported", payload: { workspaceId: input.workspaceId, entryId: entry.id, type: input.type, slug: input.slug } });
     return { ok: true, value: { entry } };
 }
@@ -258,20 +290,22 @@ async function transitionEntryStatus(required, target) {
         updatedAt: now,
         version: current.version + 1,
     };
-    await deps.entryRepo.transaction({ fn: async () => {
-            await deps.entryRepo.save(updated);
-            await deps.entryRepo.appendRevision({
-                entryId: current.id,
-                workspaceId: input.workspaceId,
-                op: target.op,
-                stateJson: updated,
-                actorId: input.actorId,
-                ...delegationFields(input),
-                recordedAt: now,
-            });
-            if (deps.watermark)
-                await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
-        } });
+    const conflict = await runVersionedWrite(deps.entryRepo, async () => {
+        await deps.entryRepo.save(updated, { expectedVersion: input.expectedVersion });
+        await deps.entryRepo.appendRevision({
+            entryId: current.id,
+            workspaceId: input.workspaceId,
+            op: target.op,
+            stateJson: updated,
+            actorId: input.actorId,
+            ...delegationFields(input),
+            recordedAt: now,
+        });
+        if (deps.watermark)
+            await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
+    });
+    if (conflict)
+        return { ok: false, error: conflict };
     await deps.outbox.enqueue({ name: target.eventName, payload: { workspaceId: input.workspaceId, entryId: current.id } });
     return { ok: true, value: { entry: updated } };
 }

package/dist/navigation/index.d.ts

@@ -15,7 +15,7 @@ export { createNavMenuReadModel, type NavMenuReadModelDeps, type NavMenuReadMode
  * `repo.memory.ts`'s file header for why) but is a real public contract: a host's own SQLite
  * adapter implements it directly, the same way it implements `NavLocationBindingRepoPort`.
  */
-export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, type MenuRepoPort, } from "./repo.memory.js";
+export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, menuVersionConflictError, type MenuRepoPort, type MenuSaveOptions, } from "./repo.memory.js";
 /**
  * `isAllowedHref`/`ALLOWED_HREF_SHAPES_DESCRIPTION` (2026-09-03): the canonical author-link
  * allowlist, promoted here specifically so a HOST can import it rather than hand-copy it — the
@@ -25,7 +25,7 @@ export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, type MenuRepoPort, }
  * `menu-service.ts`'s own doc comment on `isAllowedHref` for the retirement plan and why nothing in
  * `check:boundaries` blocks either host-side call site from doing so.
  */
-export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, isAllowedHref, ALLOWED_HREF_SHAPES_DESCRIPTION, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, type TreeValidationLimits, type CreateMenuDeps, type CreateMenuServiceInput, type CreateMenuRequired, type CreateMenuOptional, type UpdateMenuTreeDeps, type UpdateMenuTreeServiceInput, type UpdateMenuTreeRequired, type UpdateMenuTreeOptional, type AssignLocationDeps, type AssignLocationServiceInput, type AssignLocationRequired, type AssignLocationOptional, type DeleteMenuDeps, type DeleteMenuServiceInput, type DeleteMenuRequired, type DeleteMenuOptional, } from "./menu-service.js";
+export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, isAllowedHref, ALLOWED_HREF_SHAPES_DESCRIPTION, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuVersionConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, type TreeValidationLimits, type CreateMenuDeps, type CreateMenuServiceInput, type CreateMenuRequired, type CreateMenuOptional, type UpdateMenuTreeDeps, type UpdateMenuTreeServiceInput, type UpdateMenuTreeRequired, type UpdateMenuTreeOptional, type AssignLocationDeps, type AssignLocationServiceInput, type AssignLocationRequired, type AssignLocationOptional, type DeleteMenuDeps, type DeleteMenuServiceInput, type DeleteMenuRequired, type DeleteMenuOptional, } from "./menu-service.js";
 export { resolveForLocation, resolveMenuDoc, type ResolveTargetHrefFn, type ResolvedTargetHref, type ResolveForLocationDeps, type ResolveForLocationServiceInput, type ResolveForLocationRequired, type ResolveForLocationOptional, } from "./resolver.js";
 export { rebuildNavLocationBindings, type RebuildNavLocationBindingsDeps, type RebuildNavLocationBindingsResult, } from "./reconcile.js";
 /** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */

package/dist/navigation/index.js

@@ -6,7 +6,7 @@ export { createNavMenuReadModel } from "./read-model.js";
  * `repo.memory.ts`'s file header for why) but is a real public contract: a host's own SQLite
  * adapter implements it directly, the same way it implements `NavLocationBindingRepoPort`.
  */
-export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, } from "./repo.memory.js";
+export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, menuVersionConflictError, } from "./repo.memory.js";
 /**
  * `isAllowedHref`/`ALLOWED_HREF_SHAPES_DESCRIPTION` (2026-09-03): the canonical author-link
  * allowlist, promoted here specifically so a HOST can import it rather than hand-copy it — the
@@ -16,7 +16,7 @@ export { InMemoryMenuRepo, InMemoryNavLocationBindingRepo, } from "./repo.memory
  * `menu-service.ts`'s own doc comment on `isAllowedHref` for the retirement plan and why nothing in
  * `check:boundaries` blocks either host-side call site from doing so.
  */
-export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, isAllowedHref, ALLOWED_HREF_SHAPES_DESCRIPTION, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, } from "./menu-service.js";
+export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndCloneTree, isAllowedHref, ALLOWED_HREF_SHAPES_DESCRIPTION, MenuNotFoundError, MenuValidationError, MenuConflictError, MenuVersionConflictError, MenuLocationBoundError, DEFAULT_MAX_TREE_DEPTH, DEFAULT_MAX_ITEM_COUNT, } from "./menu-service.js";
 export { resolveForLocation, resolveMenuDoc, } from "./resolver.js";
 export { rebuildNavLocationBindings, } from "./reconcile.js";
 /** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */

package/dist/navigation/menu-service.d.ts

@@ -18,6 +18,22 @@ export declare class MenuConflictError extends Error {
         message: string;
     }, optionalArgs?: ErrorOptions);
 }
+/**
+ * A menu write lost its version check: the basis the caller read is no longer the stored live row's
+ * version (or a create found the id taken). A subclass, so every `instanceof MenuConflictError` check
+ * keeps matching, while a host can tell "someone else changed this, reload" apart from the other
+ * conflicts (slug already taken, slug held by a trashed menu), which want the message itself.
+ * Every `MenuRepoPort` adapter throws it, built by {@link menuVersionConflictError}.
+ */
+export declare class MenuVersionConflictError extends MenuConflictError {
+}
+/** The version-check loss every `MenuRepoPort` adapter (and `updateMenuTree`'s read check) throws, one
+ *  wording for all of them. `expectedVersion: null` is a create (`MenuSaveOptions`) that found the id taken. */
+export declare function menuVersionConflictError(required: {
+    id: UUID;
+    expectedVersion: number | null;
+    found: number | null;
+}): MenuVersionConflictError;
 /**
  * The 409-style purge rejection: hard delete is blocked while the menu is
  * still bound to at least one theme location (deletion ladder).
@@ -184,7 +200,9 @@ export interface UpdateMenuTreeOptional {
 }
 /**
  * Replaces a menu's whole item tree, guarded by optimistic concurrency on the
- * entry `version` (matches the host's `updatePost` pattern).
+ * entry `version` (matches the host's `updatePost` pattern): `expectedVersion` must equal the version
+ * read, and the repo's `save` compares it again atomically with the write; either miss throws
+ * `MenuVersionConflictError`.
  *
  * Id-stability note ("an update may not renumber surviving items"):
  * this build enforces only that ids are present and unique within the
@@ -236,24 +254,18 @@ export interface AssignLocationOptional {
  * default) and its `locations` field is updated to drop the key — recorded as
  * its own revision-worthy write.
  *
- * Atomicity note: these writes are
- * logically ONE transaction — the binding-index write is a second in-tx
- * participant alongside a slug-change-capture slot in the host's routing
- * layer. Neither real cross-write transactions nor that routing layer exist
- * as running code yet anywhere this library has shipped, so this function
- * performs the writes sequentially with no rollback if a later step throws.
- * This is an accepted, documented gap pending the command gateway's
- * transaction machinery — do not copy this sequencing pattern into code that
- * has real transactions available.
+ * Atomicity: these writes are ONE transaction (`repo.transaction`) — the displaced
+ * menu's save, this menu's save, the binding upsert and the outbox events commit
+ * together or not at all. Both menu saves are compare-and-set, so the second can
+ * lose to another editor AFTER the first landed: without the transaction, that
+ * left the displaced menu's `locations` without the key while the binding still
+ * pointed at it, and a binding rebuild then dropped the assignment. A
+ * `MenuVersionConflictError` (or any other throw) rolls the whole unit back in a
+ * store that can roll back; `InMemoryMenuRepo` cannot (see its `transaction`).
  *
  * @complexity O repo calls (bounded: at most two menu reads/writes plus one
  * binding upsert), independent of workspace size.
- * @overallScore 90
- * @findings Medium: no rollback across the two writes (menu save, then
- * binding upsert) if the second fails, leaving the derived index stale until
- * a rebuild. Acceptable because the index is declared rebuildable-by-definition;
- * flagged as tech debt for when transactions
- * exist.
+ * @overallScore 100
  */
 export declare function assignLocation(required: AssignLocationRequired, _optional?: AssignLocationOptional): Promise<{
     menu: NavMenuEntry;

package/dist/navigation/menu-service.js

@@ -67,6 +67,23 @@ export class MenuConflictError extends Error {
         super(message, optionalArgs);
     }
 }
+/**
+ * A menu write lost its version check: the basis the caller read is no longer the stored live row's
+ * version (or a create found the id taken). A subclass, so every `instanceof MenuConflictError` check
+ * keeps matching, while a host can tell "someone else changed this, reload" apart from the other
+ * conflicts (slug already taken, slug held by a trashed menu), which want the message itself.
+ * Every `MenuRepoPort` adapter throws it, built by {@link menuVersionConflictError}.
+ */
+export class MenuVersionConflictError extends MenuConflictError {
+}
+/** The version-check loss every `MenuRepoPort` adapter (and `updateMenuTree`'s read check) throws, one
+ *  wording for all of them. `expectedVersion: null` is a create (`MenuSaveOptions`) that found the id taken. */
+export function menuVersionConflictError(required) {
+    if (required.expectedVersion === null) {
+        return new MenuVersionConflictError({ message: `menu '${required.id}' already exists (expected no menu, found version ${required.found ?? "none"})` });
+    }
+    return new MenuVersionConflictError({ message: `menu '${required.id}' was modified concurrently (expected version ${required.expectedVersion}, found ${required.found ?? "none"})` });
+}
 /**
  * The 409-style purge rejection: hard delete is blocked while the menu is
  * still bound to at least one theme location (deletion ladder).
@@ -312,7 +329,9 @@ export async function createMenu(required, optional = {}) {
 }
 /**
  * Replaces a menu's whole item tree, guarded by optimistic concurrency on the
- * entry `version` (matches the host's `updatePost` pattern).
+ * entry `version` (matches the host's `updatePost` pattern): `expectedVersion` must equal the version
+ * read, and the repo's `save` compares it again atomically with the write; either miss throws
+ * `MenuVersionConflictError`.
  *
  * Id-stability note ("an update may not renumber surviving items"):
  * this build enforces only that ids are present and unique within the
@@ -336,8 +355,10 @@ export async function updateMenuTree(required, optional = {}) {
     if (!existing)
         throw new MenuNotFoundError({ message: `menu '${input.id}' was not found` });
     assertEntityLive({ entityType: "menu", entityId: input.id, state: existing.status === "trash" ? "trashed" : "live" });
+    // The new record is built from this read, so a basis that differs from it must not reach the save:
+    // it could match a version another writer lands after this read and overwrite that writer.
     if (existing.version !== input.expectedVersion) {
-        throw new MenuConflictError({ message: `menu '${input.id}' was modified concurrently (expected version ${input.expectedVersion}, found ${existing.version})` });
+        throw menuVersionConflictError({ id: input.id, expectedVersion: input.expectedVersion, found: existing.version });
     }
     const title = (input.title ?? existing.title).trim();
     const slug = (input.slug ?? existing.slug).trim().toLowerCase();
@@ -357,7 +378,9 @@ export async function updateMenuTree(required, optional = {}) {
         updatedAt: kernelNowIso({ clock: deps.clock }),
         version: existing.version + 1,
     };
-    await deps.repo.save(menu);
+    // The version check is ALSO the save's compare-and-set, not only the read above: a check before
+    // the write alone let two editors that read the same version both land (wm S4).
+    await deps.repo.save(menu, { expectedVersion: input.expectedVersion });
     await deps.outbox.enqueue(buildEvent({
         idGen: deps.idGen,
         clock: deps.clock,
@@ -379,24 +402,18 @@ export async function updateMenuTree(required, optional = {}) {
  * default) and its `locations` field is updated to drop the key — recorded as
  * its own revision-worthy write.
  *
- * Atomicity note: these writes are
- * logically ONE transaction — the binding-index write is a second in-tx
- * participant alongside a slug-change-capture slot in the host's routing
- * layer. Neither real cross-write transactions nor that routing layer exist
- * as running code yet anywhere this library has shipped, so this function
- * performs the writes sequentially with no rollback if a later step throws.
- * This is an accepted, documented gap pending the command gateway's
- * transaction machinery — do not copy this sequencing pattern into code that
- * has real transactions available.
+ * Atomicity: these writes are ONE transaction (`repo.transaction`) — the displaced
+ * menu's save, this menu's save, the binding upsert and the outbox events commit
+ * together or not at all. Both menu saves are compare-and-set, so the second can
+ * lose to another editor AFTER the first landed: without the transaction, that
+ * left the displaced menu's `locations` without the key while the binding still
+ * pointed at it, and a binding rebuild then dropped the assignment. A
+ * `MenuVersionConflictError` (or any other throw) rolls the whole unit back in a
+ * store that can roll back; `InMemoryMenuRepo` cannot (see its `transaction`).
  *
  * @complexity O repo calls (bounded: at most two menu reads/writes plus one
  * binding upsert), independent of workspace size.
- * @overallScore 90
- * @findings Medium: no rollback across the two writes (menu save, then
- * binding upsert) if the second fails, leaving the derived index stale until
- * a rebuild. Acceptable because the index is declared rebuildable-by-definition;
- * flagged as tech debt for when transactions
- * exist.
+ * @overallScore 100
  */
 export async function assignLocation(required, _optional = {}) {
     const { deps, input } = required;
@@ -405,27 +422,6 @@ export async function assignLocation(required, _optional = {}) {
         throw new MenuNotFoundError({ message: `menu '${input.menuId}' was not found` });
     assertEntityLive({ entityType: "menu", entityId: input.menuId, state: menu.status === "trash" ? "trashed" : "live" });
     const now = kernelNowIso({ clock: deps.clock });
-    const existingBinding = await deps.bindingRepo.findByLocation({
-        workspaceId: input.workspaceId,
-        locationKey: input.locationKey,
-    });
-    let displacedMenu = null;
-    if (existingBinding && existingBinding.menuId !== input.menuId) {
-        const displaced = await deps.repo.findById({
-            workspaceId: input.workspaceId,
-            id: existingBinding.menuId,
-        });
-        if (displaced) {
-            const updatedDisplaced = {
-                ...displaced,
-                locations: displaced.locations.filter((key) => key !== input.locationKey),
-                updatedAt: now,
-                version: displaced.version + 1,
-            };
-            await deps.repo.save(updatedDisplaced);
-            displacedMenu = updatedDisplaced;
-        }
-    }
     const updatedMenu = {
         ...menu,
         locations: menu.locations.includes(input.locationKey)
@@ -434,32 +430,55 @@ export async function assignLocation(required, _optional = {}) {
         updatedAt: now,
         version: menu.version + 1,
     };
-    await deps.repo.save(updatedMenu);
-    const binding = await deps.bindingRepo.upsert({
-        workspaceId: input.workspaceId,
-        locationKey: input.locationKey,
-        menuId: input.menuId,
-        boundAt: now,
-    });
-    if (displacedMenu) {
-        await deps.outbox.enqueue(buildEvent({
-            idGen: deps.idGen,
-            clock: deps.clock,
-            name: "navigation.location.unassigned",
-            workspaceId: input.workspaceId,
-            aggregateId: displacedMenu.id,
-            payload: { locationKey: input.locationKey, menuId: displacedMenu.id },
-        }));
-    }
-    await deps.outbox.enqueue(buildEvent({
-        idGen: deps.idGen,
-        clock: deps.clock,
-        name: "navigation.location.assigned",
-        workspaceId: input.workspaceId,
-        aggregateId: input.menuId,
-        payload: { locationKey: input.locationKey, menuId: input.menuId },
-    }));
-    return { menu: updatedMenu, binding, displacedMenu };
+    return deps.repo.transaction({ fn: async () => {
+            const existingBinding = await deps.bindingRepo.findByLocation({
+                workspaceId: input.workspaceId,
+                locationKey: input.locationKey,
+            });
+            let displacedMenu = null;
+            if (existingBinding && existingBinding.menuId !== input.menuId) {
+                const displaced = await deps.repo.findById({
+                    workspaceId: input.workspaceId,
+                    id: existingBinding.menuId,
+                });
+                if (displaced) {
+                    const updatedDisplaced = {
+                        ...displaced,
+                        locations: displaced.locations.filter((key) => key !== input.locationKey),
+                        updatedAt: now,
+                        version: displaced.version + 1,
+                    };
+                    await deps.repo.save(updatedDisplaced, { expectedVersion: displaced.version });
+                    displacedMenu = updatedDisplaced;
+                }
+            }
+            await deps.repo.save(updatedMenu, { expectedVersion: menu.version });
+            const binding = await deps.bindingRepo.upsert({
+                workspaceId: input.workspaceId,
+                locationKey: input.locationKey,
+                menuId: input.menuId,
+                boundAt: now,
+            });
+            if (displacedMenu) {
+                await deps.outbox.enqueue(buildEvent({
+                    idGen: deps.idGen,
+                    clock: deps.clock,
+                    name: "navigation.location.unassigned",
+                    workspaceId: input.workspaceId,
+                    aggregateId: displacedMenu.id,
+                    payload: { locationKey: input.locationKey, menuId: displacedMenu.id },
+                }));
+            }
+            await deps.outbox.enqueue(buildEvent({
+                idGen: deps.idGen,
+                clock: deps.clock,
+                name: "navigation.location.assigned",
+                workspaceId: input.workspaceId,
+                aggregateId: input.menuId,
+                payload: { locationKey: input.locationKey, menuId: input.menuId },
+            }));
+            return { menu: updatedMenu, binding, displacedMenu };
+        } });
 }
 /**
  * Deletion ladder (mirrors the media library's):

package/dist/navigation/repo.memory.d.ts

@@ -32,6 +32,7 @@
  * collections.
  */
 import type { UUID } from "@jini-ai/core/primitives";
+import { menuVersionConflictError } from "./menu-service.js";
 import type { NavLocationBindingRepoPort } from "./ports.js";
 import type { NavLocationBindingRow, NavLocationKey, NavMenuEntry } from "./types.js";
 /**
@@ -53,13 +54,46 @@ export interface MenuRepoPort {
     list(required: {
         workspaceId: UUID;
     }): Promise<NavMenuEntry[]>;
-    save(record: NavMenuEntry): Promise<void>;
+    /**
+     * Writes `record` by id. With `expectedVersion`, the write is a compare-and-set: it lands only when
+     * the stored row is live (not `status: "trash"`) and still holds that version, checked atomically
+     * with the write (one conditional UPDATE in a SQL adapter), so two writers that read the same
+     * version cannot both land. With `expectedVersion: null` it is insert-if-absent (a create that
+     * keeps a caller-given id, e.g. a host's id-preserving import; `INSERT ... ON CONFLICT DO NOTHING`
+     * in a SQL adapter), so two creates of one id cannot both land either. Without it, the write is
+     * unconditional (`createMenu`'s freshly minted id, trash seams).
+     * @throws MenuVersionConflictError ``menu '<id>' was modified concurrently (expected version <n>, found <stored|none>)``,
+     *         or ``menu '<id>' already exists (expected no menu, found version <n>)`` for a create
+     *         ({@link menuVersionConflictError}).
+     */
+    save(record: NavMenuEntry, options?: MenuSaveOptions): Promise<void>;
     /** Hard-remove a menu row. Only called after the trash step. */
     remove(required: {
         workspaceId: UUID;
         id: UUID;
     }): Promise<void>;
+    /**
+     * Runs `fn` as ONE unit of work: every menu save, binding write and outbox enqueue inside it commits
+     * together or not at all, and a nested call joins the outer one. `assignLocation` needs it because it
+     * writes two menus, then the binding: a conflict on the second menu must not leave the first one's
+     * `locations` changed while the binding still points at it. A SQL adapter runs its connection's
+     * transaction, and the binding repo and outbox must write through that same connection (a wiring
+     * obligation of the host). A store with nothing to roll back may just call `fn` (see
+     * `InMemoryMenuRepo.transaction`).
+     */
+    transaction<T>(required: {
+        fn: () => Promise<T>;
+    }): Promise<T>;
 }
+/** Options for {@link MenuRepoPort.save}. */
+export interface MenuSaveOptions {
+    /** The version the caller read; the save throws `MenuVersionConflictError` unless the stored live row still holds it.
+     *  `null` is a create: the save throws unless no row (live, trashed, or in another workspace) holds the id. */
+    expectedVersion?: number | null | undefined;
+}
+/** Re-exported from here, where it has always been exported from; it lives in `menu-service.ts` so that
+ *  module's own read check can throw it without a value import cycle. */
+export { menuVersionConflictError };
 /**
  * In-memory `MenuRepoPort` adapter for dev/tests. See file header for why a
  * self-contained repo exists instead of an entries-backed one.
@@ -86,7 +120,17 @@ export declare class InMemoryMenuRepo implements MenuRepoPort {
     list(required: {
         workspaceId: UUID;
     }): Promise<NavMenuEntry[]>;
-    save(record: NavMenuEntry): Promise<void>;
+    save(record: NavMenuEntry, options?: MenuSaveOptions): Promise<void>;
+    /**
+     * Just runs `fn`: nothing here rolls back, the same disclosed choice as `InMemoryEntryRepo`'s. A
+     * partial write can only be left by a version conflict on a later save of the same unit, which in
+     * this single-process store needs another writer to land between that unit's awaits; dev and test
+     * hosts accept that, and every durable host adapter must roll back.
+     * @complexity O(1) beyond `fn`.
+     */
+    transaction<T>(required: {
+        fn: () => Promise<T>;
+    }): Promise<T>;
     remove(required: {
         workspaceId: UUID;
         id: UUID;

package/dist/navigation/repo.memory.js

@@ -1,3 +1,7 @@
+import { menuVersionConflictError } from "./menu-service.js";
+/** Re-exported from here, where it has always been exported from; it lives in `menu-service.ts` so that
+ *  module's own read check can throw it without a value import cycle. */
+export { menuVersionConflictError };
 /**
  * In-memory `MenuRepoPort` adapter for dev/tests. See file header for why a
  * self-contained repo exists instead of an entries-backed one.
@@ -23,14 +27,37 @@ export class InMemoryMenuRepo {
     async list(required) {
         return this.rows.filter((row) => row.workspaceId === required.workspaceId);
     }
-    async save(record) {
+    async save(record, options = {}) {
         const index = this.rows.findIndex((row) => row.workspaceId === record.workspaceId && row.id === record.id);
+        if (options.expectedVersion === null) {
+            // A create needs the id free in every workspace and status, as a SQL primary key on `id` does.
+            const holder = this.rows.find((row) => row.id === record.id);
+            if (holder)
+                throw menuVersionConflictError({ id: record.id, expectedVersion: null, found: holder.version });
+        }
+        else if (options.expectedVersion !== undefined) {
+            const stored = this.rows[index];
+            const found = stored && stored.status !== "trash" ? stored.version : null;
+            if (found !== options.expectedVersion) {
+                throw menuVersionConflictError({ id: record.id, expectedVersion: options.expectedVersion, found });
+            }
+        }
         if (index === -1) {
             this.rows.push(record);
             return;
         }
         this.rows[index] = record;
     }
+    /**
+     * Just runs `fn`: nothing here rolls back, the same disclosed choice as `InMemoryEntryRepo`'s. A
+     * partial write can only be left by a version conflict on a later save of the same unit, which in
+     * this single-process store needs another writer to land between that unit's awaits; dev and test
+     * hosts accept that, and every durable host adapter must roll back.
+     * @complexity O(1) beyond `fn`.
+     */
+    async transaction(required) {
+        return required.fn();
+    }
     async remove(required) {
         this.rows = this.rows.filter((row) => !(row.workspaceId === required.workspaceId && row.id === required.id));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/cms",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Content-model capability for Jini-hosted products: framework-free contracts, ports, and domain services in `/core` and per-domain subpaths; Node-bound adapters in domain-specific subpaths.",
   "license": "Apache-2.0",
   "repository": {
@@ -132,7 +132,7 @@
     "@jini-ai/http-kit": "0.4.0"
   },
   "dependencies": {
-    "@jini-ai/core": "^0.4.0"
+    "@jini-ai/core": "^0.4.1"
   },
   "peerDependencies": {
     "sharp": "^0.35.3",