@jini-ai/cms 0.4.1 → 0.5.0

package/dist/media/created-by.d.ts

@@ -0,0 +1,15 @@
+import type { MediaRecord } from "./types.js";
+import type { MediaRepoPort } from "./ports.js";
+/** Bind creation writes to one authenticated caller without shared mutable actor state.
+ * Useful when adapting an older upload service that predates asset-level attribution. */
+export declare function mediaRepoWithCreator(required: {
+    mediaRepo: MediaRepoPort;
+    principalId: string;
+}, _optional?: Record<string, never>): MediaRepoPort;
+/** An update retains creation attribution, even when the original creator is unknown.
+ * Omitting an unknown field preserves compatibility with legacy serialized records. */
+export declare function preserveMediaCreator(required: {
+    record: MediaRecord;
+    original: MediaRecord;
+}, _optional?: Record<string, never>): MediaRecord;
+//# sourceMappingURL=created-by.d.ts.map

package/dist/media/created-by.js

@@ -0,0 +1,20 @@
+/** Bind creation writes to one authenticated caller without shared mutable actor state.
+ * Useful when adapting an older upload service that predates asset-level attribution. */
+export function mediaRepoWithCreator(required, _optional = {}) {
+    const { mediaRepo, principalId } = required;
+    return {
+        findById: input => mediaRepo.findById(input),
+        findBySlug: input => mediaRepo.findBySlug(input),
+        list: input => mediaRepo.list(input),
+        remove: input => mediaRepo.remove(input),
+        save: record => mediaRepo.save({ ...record, createdBy: principalId }),
+    };
+}
+/** An update retains creation attribution, even when the original creator is unknown.
+ * Omitting an unknown field preserves compatibility with legacy serialized records. */
+export function preserveMediaCreator(required, _optional = {}) {
+    const { createdBy: _ignored, ...metadata } = required.record;
+    return { ...metadata, ...(required.original.createdBy !== undefined
+            ? { createdBy: required.original.createdBy } : {}) };
+}
+//# sourceMappingURL=created-by.js.map

package/dist/media/index.d.ts

@@ -15,6 +15,7 @@ export type { MediaStatus, MediaSource, MediaRecord, AssetBlobStatus, AssetBlobR
 export { MediaNotFoundError, MediaValidationError, MediaConflictError, MediaSourceImmutableError, MediaStillReferencedError, } from "./types.js";
 export type { MediaRepoPort, AssetBlobRepoPort, AssetRenditionRepoPort, BlobStorePort, BlobGcJournalRepoPort, PutBlobInput, TransformDefinitionRepoPort, } from "./ports.js";
 export { computeBlobStorageKey } from "./blob-key.js";
+export { preserveMediaCreator, mediaRepoWithCreator } from "./created-by.js";
 export { MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES, isAllowedMediaHtmlAttributeName, parseMediaHtmlAttributes, describeMediaHtmlAttributeError, type MediaHtmlAttributeRejectionReason, type MediaHtmlAttributeError, type ParsedMediaHtmlAttributes, } from "./html-attributes.js";
 export { InMemoryMediaRepo, InMemoryAssetBlobRepo, InMemoryAssetRenditionRepo, InMemoryBlobGcJournalRepo, InMemoryTransformDefinitionRepo, } from "./repo.memory.js";
 export { withSha256Lock } from "./blob-gc-lock.js";

package/dist/media/index.js

@@ -1,5 +1,6 @@
 export { MediaNotFoundError, MediaValidationError, MediaConflictError, MediaSourceImmutableError, MediaStillReferencedError, } from "./types.js";
 export { computeBlobStorageKey } from "./blob-key.js";
+export { preserveMediaCreator, mediaRepoWithCreator } from "./created-by.js";
 export { MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES, isAllowedMediaHtmlAttributeName, parseMediaHtmlAttributes, describeMediaHtmlAttributeError, } from "./html-attributes.js";
 export { InMemoryMediaRepo, InMemoryAssetBlobRepo, InMemoryAssetRenditionRepo, InMemoryBlobGcJournalRepo, InMemoryTransformDefinitionRepo, } from "./repo.memory.js";
 export { withSha256Lock } from "./blob-gc-lock.js";

package/dist/media/media-service.d.ts

@@ -60,7 +60,7 @@ export interface UploadMediaInput {
     alt?: string | undefined;
     caption?: string | undefined;
     credit?: string | undefined;
-    /** Attributed on the `asset_blobs` row (required attribution). */
+    /** Acting principal, stamped on each media row and on a newly created asset_blobs row. */
     createdByPrincipal: string;
 }
 export interface UploadMediaDeps {

package/dist/media/media-service.js

@@ -304,6 +304,7 @@ export async function uploadMedia(required, optional = {}) {
     const media = {
         id: deps.idGen.newId(),
         workspaceId: input.workspaceId,
+        createdBy: input.createdByPrincipal,
         title,
         slug,
         alt: input.alt?.trim() ?? "",

package/dist/media/ports.d.ts

@@ -13,13 +13,15 @@
  *
  * `BlobStorePort`'s surface is deliberately narrower than the full
  * design: no `capabilities()`/`createPresignedUpload()` (the presign surface is
- * explicitly deferred by this task's scope). It has one method beyond the
- * task's stated minimal 3 (`put`/`get`/`exists`): `remove()`. That addition is
+ * explicitly deferred by this task's scope). It extends the original minimal
+ * 3 (`put`/`get`/`exists`) with `remove()`. That addition is
  * necessary to implement `purgeMedia`'s explicitly-requested "best-effort blob
  * unlink" (see `media-service.ts`) — without a way to delete bytes, purge could
  * only ever delete rows, never reclaim storage. This is disclosed here, not
  * silently smuggled in: it is still far short of the real journaled
  * GC protocol (no epochs, no `BEGIN IMMEDIATE`, no crash-safety guarantee).
+ * `putIfAbsent` adds atomic create-only writes; optional `sizeOf` reports original bytes
+ * without reading payloads (successful filesystem sizes are cached by content-addressed key).
  *
  * Interfaces only — no feature logic.
  */
@@ -162,6 +164,14 @@ export interface BlobStorePort {
     get(input: {
         storageKey: string;
     }): Promise<Uint8Array>;
+    /**
+     * Original byte count without reading the payload; null only when the key is absent.
+     * Other storage failures reject. Optional for older/custom adapters; consumers must report
+     * unknown size when unavailable, never download an entire blob just to count bytes.
+     */
+    sizeOf?(required: {
+        storageKey: string;
+    }, optional?: Record<string, never>): Promise<number | null>;
     exists(input: {
         storageKey: string;
     }): Promise<boolean>;

package/dist/media/repo.memory.js

@@ -1,3 +1,4 @@
+import { preserveMediaCreator } from "./created-by.js";
 export class InMemoryMediaRepo {
     rows;
     constructor(requiredArgs, optionalArgs = {}) {
@@ -19,7 +20,7 @@ export class InMemoryMediaRepo {
             this.rows.push(record);
             return;
         }
-        this.rows[index] = record;
+        this.rows[index] = preserveMediaCreator({ record, original: this.rows[index] });
     }
     async remove(required) {
         this.rows = this.rows.filter((row) => !(row.workspaceId === required.workspaceId && row.id === required.id));

package/dist/media/tool-registrations.js

@@ -31,6 +31,7 @@ function isMediaShapeRejection({ error }) {
 function toMediaToolView(record) {
     return {
         id: record.id,
+        createdBy: record.createdBy ?? null,
         slug: record.slug,
         title: record.title,
         alt: record.alt,

package/dist/media/types.d.ts

@@ -41,6 +41,10 @@ export interface MediaSource {
 export interface MediaRecord {
     id: UUID;
     workspaceId: UUID;
+    /** Acting principal at asset creation, independent of the producer/model and editable credit.
+     * Optional/null for records written before attribution existed. Never inferred from a shared
+     * blob's owner: identical bytes may have been uploaded by different principals. */
+    createdBy?: string | null | undefined;
     title: string;
     /**
      * Human-memorable, unique-per-workspace lookup key (owner-directed, 2026-09-07) — an ADDITIONAL

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).
@@ -241,6 +258,12 @@ function validateTarget(target) {
     if (!VALID_TARGET_KINDS.has(kind)) {
         throw new MenuValidationError({ message: `unknown target kind '${kind}'` });
     }
+    if (kind === "entryRef" && target.lastKnownHref !== undefined) {
+        const rawHref = target.lastKnownHref;
+        if (typeof rawHref !== "string" || !rawHref.trim() || !isAllowedHref({ rawHref })) {
+            throw new MenuValidationError({ message: `entryRef lastKnownHref must be ${ALLOWED_HREF_SHAPES_DESCRIPTION}.` });
+        }
+    }
     if (kind === "url") {
         const rawHref = target.href;
         if (typeof rawHref !== "string" || !rawHref.trim()) {
@@ -306,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
@@ -330,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();
@@ -351,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,
@@ -373,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;
@@ -399,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)
@@ -428,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/dist/navigation/types.d.ts

@@ -49,6 +49,11 @@ export type ReservedNavTargetKind = "dynamicQuery" | "content";
 /** A link to another content entry (page/post/media/…). Integrity-tracked. */
 export interface NavEntryTarget {
     readonly kind: "entryRef";
+    /** Optional content-type hint for editors; reference integrity and routing still use entryId. */
+    readonly entryType?: string;
+    /** Author's last known URL, retained for exports and routing misses. A known unavailable
+     * entry must remain hidden; this snapshot never overrides an availability decision. */
+    readonly lastKnownHref?: string;
     /** Target entry id. Extracted to `entry_refs` at the write chokepoint. */
     readonly entryId: UUID;
 }

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

@@ -352,12 +352,14 @@ export interface UnassignTermsRequired {
  * authorize -> validateAssignmentTarget -> write -> stamp -> outbox chokepoint as `assignTerms`,
  * and — like `assignTerms` — never produces a `taxonomy_revisions` row ( disclosed
  * narrowing applies equally to removal). Idempotent: unassigning a row that isn't there is a no-op,
- * not an error (`remove`'s 0-vs-1 return is intentionally not surfaced to the caller). Chosen over
+ * not an error. Only removed ids are returned, stamped, and emitted; an entirely absent set is a no-op. Chosen over
  * a "set terms" replace call — see the taxonomy plan's "What the docs settle" #3 for why replace
  * risks silently erasing a concurrent assignment.
  * See docs/decisions/DR-005-ordered-taxonomy-validation.md.
  */
-export declare function unassignTerms(required: UnassignTermsRequired, _optional?: Record<string, never>): Promise<void>;
+export declare function unassignTerms(required: UnassignTermsRequired, _optional?: Record<string, never>): Promise<{
+    removedTermIds: string[];
+}>;
 export interface EntryTermsCleanupPort {
     deleteByContent(params: {
         workspaceId: string;