@jini-ai/cms 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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.
+- Navigation: entry targets carry optional `lastKnownHref` and `entryType` hints.
+- Taxonomy: `unassignTerms` returns the removed ids. Trash: a no-op trash/restore does not notify again.
+- Internal `@jini-ai/*` dependencies are caret ranges (`workspace:^`) instead of exact pins, so a host on a newer patch resolves a single copy without an override.
+
 ## Unreleased — Trash host adoption
 
 - Preserve `adapter-unavailable` for absent domains before checking entity policy; selected purge

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/media/blob-store.fs.d.ts

@@ -5,6 +5,7 @@ export interface LocalFsBlobStoreDeps {
 }
 export declare class LocalFsBlobStore implements BlobStorePort {
     private readonly rootDir;
+    private readonly sizesByKey;
     constructor(deps: LocalFsBlobStoreDeps);
     private resolvePath;
     put(input: PutBlobInput): Promise<{
@@ -28,6 +29,9 @@ export declare class LocalFsBlobStore implements BlobStorePort {
     get(input: {
         storageKey: string;
     }): Promise<Uint8Array>;
+    sizeOf({ storageKey }: {
+        storageKey: string;
+    }, _optional?: Record<string, never>): Promise<number | null>;
     /**
      * `ENOENT` (the path genuinely does not exist) resolves to `false`. Any other `stat()` failure
      * (`EACCES` permission denied, `ENOTDIR`, `EIO`, ...) is rethrown raw — same "catch the one

package/dist/media/blob-store.fs.js

@@ -16,6 +16,9 @@ import { dirname, join } from "node:path";
 import { computeBlobStorageKey } from "./blob-key.js";
 export class LocalFsBlobStore {
     rootDir;
+    // Storage keys include workspace + content hash: immutable bytes make successful sizes
+    // reusable for this process. Promises coalesce concurrent reads of the same hash as well.
+    sizesByKey = new Map();
     constructor(deps) {
         this.rootDir = deps.rootDir;
     }
@@ -27,6 +30,7 @@ export class LocalFsBlobStore {
         const path = this.resolvePath(storageKey);
         await mkdir(dirname(path), { recursive: true });
         await writeFile(path, input.bytes);
+        this.sizesByKey.delete(storageKey);
         return { storageKey };
     }
     /**
@@ -46,6 +50,7 @@ export class LocalFsBlobStore {
         await mkdir(dirname(path), { recursive: true });
         try {
             await writeFile(path, input.bytes, { flag: "wx" });
+            this.sizesByKey.delete(storageKey);
             return { storageKey, written: true };
         }
         catch (err) {
@@ -58,6 +63,27 @@ export class LocalFsBlobStore {
     async get(input) {
         return readFile(this.resolvePath(input.storageKey));
     }
+    sizeOf({ storageKey }, _optional = {}) {
+        const cached = this.sizesByKey.get(storageKey);
+        if (cached)
+            return cached;
+        const pending = stat(this.resolvePath(storageKey)).then((info) => info.size).catch((err) => {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        });
+        this.sizesByKey.set(storageKey, pending);
+        // Missing/restored blobs and transient failures must be retried. Identity guards prevent
+        // an older stat from clearing a newer entry after a write/remove invalidated the cache.
+        void pending.then((size) => {
+            if (size === null && this.sizesByKey.get(storageKey) === pending)
+                this.sizesByKey.delete(storageKey);
+        }, () => {
+            if (this.sizesByKey.get(storageKey) === pending)
+                this.sizesByKey.delete(storageKey);
+        });
+        return pending;
+    }
     /**
      * `ENOENT` (the path genuinely does not exist) resolves to `false`. Any other `stat()` failure
      * (`EACCES` permission denied, `ENOTDIR`, `EIO`, ...) is rethrown raw — same "catch the one
@@ -79,6 +105,7 @@ export class LocalFsBlobStore {
     }
     async remove(input) {
         await rm(this.resolvePath(input.storageKey), { force: true });
+        this.sizesByKey.delete(input.storageKey);
     }
 }
 //# sourceMappingURL=blob-store.fs.js.map

package/dist/media/blob-store.memory.d.ts

@@ -24,6 +24,9 @@ export declare class InMemoryBlobStore implements BlobStorePort {
     exists(input: {
         storageKey: string;
     }): Promise<boolean>;
+    sizeOf({ storageKey }: {
+        storageKey: string;
+    }, _optional?: Record<string, never>): Promise<number | null>;
     remove(input: {
         storageKey: string;
     }): Promise<void>;

package/dist/media/blob-store.memory.js

@@ -29,6 +29,9 @@ export class InMemoryBlobStore {
     async exists(input) {
         return this.bytesByKey.has(input.storageKey);
     }
+    async sizeOf({ storageKey }, _optional = {}) {
+        return this.bytesByKey.get(storageKey)?.byteLength ?? null;
+    }
     async remove(input) {
         this.bytesByKey.delete(input.storageKey);
     }