@jini-ai/cms 0.3.7 → 0.3.9

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

@@ -1,3 +1,4 @@
+import { ToolInputError } from "@jini-ai/core";
 /**
  * @file Typed error surface for the `content-types` package.
  *
@@ -10,26 +11,41 @@
  * the constructor sets `this.name` explicitly (confirmed empirically in Session 2 of this
  * workstream) — every class below sets it.
  *
+ * Every class the five wired agent tools (`define`/`update_fields`/`deprecate`/`reactivate`/
+ * `tombstone`) can actually throw extends `ToolInputError` (`@jini-ai/core`), not plain `Error` —
+ * mirroring `core/entity-liveness.ts`'s `EntityNotLiveError` (see its file header for the full
+ * rationale). Without that, `write-service.ts`/`lifecycle.ts` return these via a `Result` that
+ * `tool-registrations.ts`'s `fromResult` re-throws unwrapped, `@jini-ai/daemon`'s `ToolExecutor`
+ * sees a plain `Error` it cannot distinguish from a genuine internal fault, and every HTTP-facing
+ * mapping of that failure (`@jini-ai/http-kit`'s `delegated-tools.ts`) redacts it to a 500
+ * `INTERNAL_ERROR` — so a model calling `collections_content_type_define` on a key that already
+ * exists never sees "use collections_content_type_update_fields", only an opaque failure it cannot
+ * act on. `CleanupNotEligibleError` is the one exception: `collections_plan_cleanup`/
+ * `collections_execute_cleanup` are declared but not yet wired to any handler
+ * (`tool-registrations.ts`'s `UNWIRED_CONTENT_TYPES_TOOL_IDS`), so nothing reaches a model through
+ * it today — left as plain `Error` until that wiring exists and it can be verified the same way.
+ *
  * Architectural role:
- * `features/content-types` domain logic. No dependencies.
+ * `features/content-types` domain logic. Depends on `@jini-ai/core` only for the `ToolInputError`
+ * marker above.
  */
-export declare class ForbiddenError extends Error {
+export declare class ForbiddenError extends ToolInputError {
     constructor(message: string);
 }
 /** CIC U-002-B1 guard 1 — `key`/field-name grammar gate `^[a-z][a-z0-9_]{0,63}$` (U-001-B2). */
-export declare class InvalidKeyGrammarError extends Error {
+export declare class InvalidKeyGrammarError extends ToolInputError {
     constructor(message: string);
 }
 /** CIC U-002-B1 guard 2 — `key` is one of the permanently reserved legacy `posts` keys. */
-export declare class ReservedContentTypeKeyError extends Error {
+export declare class ReservedContentTypeKeyError extends ToolInputError {
     constructor(message: string);
 }
 /** CIC U-002-B1 guard 3 — a field name fails the identifier grammar gate. */
-export declare class InvalidFieldNameGrammarError extends Error {
+export declare class InvalidFieldNameGrammarError extends ToolInputError {
     constructor(message: string);
 }
 /** CIC U-001-B1 / U-002-B1 guard 4 — a field `kind` is not one of the closed field-kind enum. */
-export declare class InvalidFieldKindError extends Error {
+export declare class InvalidFieldKindError extends ToolInputError {
     constructor(message: string);
 }
 /**
@@ -64,7 +80,7 @@ export declare class StorageOnlyFieldNotQueryableError extends InvalidFieldKindE
  * `violation.received` names the offending value's TYPE, never the value — a field payload can
  * carry operator content, and this message reaches both an HTTP client and a model.
  */
-export declare class InvalidFieldShapeError extends Error {
+export declare class InvalidFieldShapeError extends ToolInputError {
     readonly code: "VALIDATION_ERROR";
     readonly violation: {
         path: string;
@@ -78,18 +94,31 @@ export declare class InvalidFieldShapeError extends Error {
     });
 }
 /** CIC U-002-B1 guard 5 — more than the per-type cap of `queryable` fields were submitted. */
-export declare class QueryableFieldCapExceededError extends Error {
+export declare class QueryableFieldCapExceededError extends ToolInputError {
     constructor(message: string);
 }
 /** CIC U-004-B1 — `expectedVersion` did not match the current row's version (OCC conflict). */
-export declare class VersionConflictError extends Error {
+export declare class VersionConflictError extends ToolInputError {
     constructor(message: string);
 }
-export declare class ContentTypeNotFoundError extends Error {
+export declare class ContentTypeNotFoundError extends ToolInputError {
     constructor(message: string);
 }
+/**
+ * Row 7 (web-high fix plan, 2026-09-24) — `registerContentType` loaded no existing row before
+ * saving, so two concurrent first-widget creates (or a caller retrying an existing key) could
+ * silently overwrite the current fields, and registering a tombstoned key could resurrect it
+ * (INV-06 forbids any transition out of tombstone, including via a fresh register). Thrown when
+ * `deps.repo.findByKey` already returns a row for the key, whether that row is active/deprecated
+ * or tombstoned — `tombstoned` distinguishes the two so a caller/HTTP route can give the right
+ * guidance (retry with update-fields, vs. the key is permanently gone).
+ */
+export declare class ContentTypeAlreadyExistsError extends ToolInputError {
+    readonly tombstoned: boolean;
+    constructor(key: string, tombstoned: boolean);
+}
 /** A generic validation rejection carrying a stable machine-readable `details.reason`. */
-export declare class ValidationError extends Error {
+export declare class ValidationError extends ToolInputError {
     readonly code: "VALIDATION_ERROR";
     readonly details: {
         reason: string;
@@ -97,7 +126,7 @@ export declare class ValidationError extends Error {
     constructor(message: string, reason: string);
 }
 /** REQ-09..12 lifecycle state-machine guard rejection (INV-06 terminal-tombstone, EC-09 deprecate-first). */
-export declare class ContentTypeLifecycleError extends Error {
+export declare class ContentTypeLifecycleError extends ToolInputError {
     constructor(message: string);
 }
 /** REQ-20 `planCleanup` eligibility-gate rejection; `reason` is one of a closed, ordered set. */

package/dist/content-types/errors.js

@@ -1,3 +1,4 @@
+import { ToolInputError } from "@jini-ai/core";
 /**
  * @file Typed error surface for the `content-types` package.
  *
@@ -10,38 +11,53 @@
  * the constructor sets `this.name` explicitly (confirmed empirically in Session 2 of this
  * workstream) — every class below sets it.
  *
+ * Every class the five wired agent tools (`define`/`update_fields`/`deprecate`/`reactivate`/
+ * `tombstone`) can actually throw extends `ToolInputError` (`@jini-ai/core`), not plain `Error` —
+ * mirroring `core/entity-liveness.ts`'s `EntityNotLiveError` (see its file header for the full
+ * rationale). Without that, `write-service.ts`/`lifecycle.ts` return these via a `Result` that
+ * `tool-registrations.ts`'s `fromResult` re-throws unwrapped, `@jini-ai/daemon`'s `ToolExecutor`
+ * sees a plain `Error` it cannot distinguish from a genuine internal fault, and every HTTP-facing
+ * mapping of that failure (`@jini-ai/http-kit`'s `delegated-tools.ts`) redacts it to a 500
+ * `INTERNAL_ERROR` — so a model calling `collections_content_type_define` on a key that already
+ * exists never sees "use collections_content_type_update_fields", only an opaque failure it cannot
+ * act on. `CleanupNotEligibleError` is the one exception: `collections_plan_cleanup`/
+ * `collections_execute_cleanup` are declared but not yet wired to any handler
+ * (`tool-registrations.ts`'s `UNWIRED_CONTENT_TYPES_TOOL_IDS`), so nothing reaches a model through
+ * it today — left as plain `Error` until that wiring exists and it can be verified the same way.
+ *
  * Architectural role:
- * `features/content-types` domain logic. No dependencies.
+ * `features/content-types` domain logic. Depends on `@jini-ai/core` only for the `ToolInputError`
+ * marker above.
  */
-export class ForbiddenError extends Error {
+export class ForbiddenError extends ToolInputError {
     constructor(message) {
         super(message);
         this.name = "ForbiddenError";
     }
 }
 /** CIC U-002-B1 guard 1 — `key`/field-name grammar gate `^[a-z][a-z0-9_]{0,63}$` (U-001-B2). */
-export class InvalidKeyGrammarError extends Error {
+export class InvalidKeyGrammarError extends ToolInputError {
     constructor(message) {
         super(message);
         this.name = "InvalidKeyGrammarError";
     }
 }
 /** CIC U-002-B1 guard 2 — `key` is one of the permanently reserved legacy `posts` keys. */
-export class ReservedContentTypeKeyError extends Error {
+export class ReservedContentTypeKeyError extends ToolInputError {
     constructor(message) {
         super(message);
         this.name = "ReservedContentTypeKeyError";
     }
 }
 /** CIC U-002-B1 guard 3 — a field name fails the identifier grammar gate. */
-export class InvalidFieldNameGrammarError extends Error {
+export class InvalidFieldNameGrammarError extends ToolInputError {
     constructor(message) {
         super(message);
         this.name = "InvalidFieldNameGrammarError";
     }
 }
 /** CIC U-001-B1 / U-002-B1 guard 4 — a field `kind` is not one of the closed field-kind enum. */
-export class InvalidFieldKindError extends Error {
+export class InvalidFieldKindError extends ToolInputError {
     constructor(message) {
         super(message);
         this.name = "InvalidFieldKindError";
@@ -82,7 +98,7 @@ export class StorageOnlyFieldNotQueryableError extends InvalidFieldKindError {
  * `violation.received` names the offending value's TYPE, never the value — a field payload can
  * carry operator content, and this message reaches both an HTTP client and a model.
  */
-export class InvalidFieldShapeError extends Error {
+export class InvalidFieldShapeError extends ToolInputError {
     code = "VALIDATION_ERROR";
     violation;
     constructor(violation) {
@@ -92,27 +108,46 @@ export class InvalidFieldShapeError extends Error {
     }
 }
 /** CIC U-002-B1 guard 5 — more than the per-type cap of `queryable` fields were submitted. */
-export class QueryableFieldCapExceededError extends Error {
+export class QueryableFieldCapExceededError extends ToolInputError {
     constructor(message) {
         super(message);
         this.name = "QueryableFieldCapExceededError";
     }
 }
 /** CIC U-004-B1 — `expectedVersion` did not match the current row's version (OCC conflict). */
-export class VersionConflictError extends Error {
+export class VersionConflictError extends ToolInputError {
     constructor(message) {
         super(message);
         this.name = "VersionConflictError";
     }
 }
-export class ContentTypeNotFoundError extends Error {
+export class ContentTypeNotFoundError extends ToolInputError {
     constructor(message) {
         super(message);
         this.name = "CONTENT_TYPE_NOT_FOUND";
     }
 }
+/**
+ * Row 7 (web-high fix plan, 2026-09-24) — `registerContentType` loaded no existing row before
+ * saving, so two concurrent first-widget creates (or a caller retrying an existing key) could
+ * silently overwrite the current fields, and registering a tombstoned key could resurrect it
+ * (INV-06 forbids any transition out of tombstone, including via a fresh register). Thrown when
+ * `deps.repo.findByKey` already returns a row for the key, whether that row is active/deprecated
+ * or tombstoned — `tombstoned` distinguishes the two so a caller/HTTP route can give the right
+ * guidance (retry with update-fields, vs. the key is permanently gone).
+ */
+export class ContentTypeAlreadyExistsError extends ToolInputError {
+    tombstoned;
+    constructor(key, tombstoned) {
+        super(tombstoned
+            ? `content type '${key}' was permanently deleted; its key can't be reused (INV-06)`
+            : `content type '${key}' already exists; use collections_content_type_update_fields to change its fields`);
+        this.name = "ContentTypeAlreadyExistsError";
+        this.tombstoned = tombstoned;
+    }
+}
 /** A generic validation rejection carrying a stable machine-readable `details.reason`. */
-export class ValidationError extends Error {
+export class ValidationError extends ToolInputError {
     code = "VALIDATION_ERROR";
     details;
     constructor(message, reason) {
@@ -122,7 +157,7 @@ export class ValidationError extends Error {
     }
 }
 /** REQ-09..12 lifecycle state-machine guard rejection (INV-06 terminal-tombstone, EC-09 deprecate-first). */
-export class ContentTypeLifecycleError extends Error {
+export class ContentTypeLifecycleError extends ToolInputError {
     constructor(message) {
         super(message);
         this.name = "ContentTypeLifecycleError";

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

@@ -30,7 +30,7 @@ export { ForbiddenError, InvalidKeyGrammarError, ReservedContentTypeKeyError, In
  * carries the parent maps this to the same `400 VALIDATION_ERROR` with no change. Catch it by
  * name only if the finer distinction matters.
  */
-StorageOnlyFieldNotQueryableError, InvalidFieldShapeError, QueryableFieldCapExceededError, VersionConflictError, ContentTypeNotFoundError, ValidationError, ContentTypeLifecycleError, CleanupNotEligibleError, } from "./errors.js";
+StorageOnlyFieldNotQueryableError, InvalidFieldShapeError, QueryableFieldCapExceededError, VersionConflictError, ContentTypeNotFoundError, ContentTypeAlreadyExistsError, ValidationError, ContentTypeLifecycleError, CleanupNotEligibleError, } from "./errors.js";
 /**
  * The queryable-field index machinery. `IDENTIFIER_GRAMMAR_PATTERN` is exported because it is the
  * single definition of the identifier grammar — the published agent-tool schemas reference it

package/dist/content-types/index.js

@@ -20,7 +20,7 @@ export { ForbiddenError, InvalidKeyGrammarError, ReservedContentTypeKeyError, In
  * carries the parent maps this to the same `400 VALIDATION_ERROR` with no change. Catch it by
  * name only if the finer distinction matters.
  */
-StorageOnlyFieldNotQueryableError, InvalidFieldShapeError, QueryableFieldCapExceededError, VersionConflictError, ContentTypeNotFoundError, ValidationError, ContentTypeLifecycleError, CleanupNotEligibleError, } from "./errors.js";
+StorageOnlyFieldNotQueryableError, InvalidFieldShapeError, QueryableFieldCapExceededError, VersionConflictError, ContentTypeNotFoundError, ContentTypeAlreadyExistsError, ValidationError, ContentTypeLifecycleError, CleanupNotEligibleError, } from "./errors.js";
 export { IDENTIFIER_GRAMMAR_PATTERN, validateIdentifierGrammar, mapFieldKindToCast, buildQueryableFieldIndexName, resolveFieldIndexTransition, } from "./index-provisioning.js";
 export { registerContentType, updateContentTypeFields } from "./write-service.js";
 export { deprecateContentType, reactivateContentType, tombstoneContentType, } from "./lifecycle.js";

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

@@ -1,7 +1,32 @@
-import { ContentTypeNotFoundError, ForbiddenError, InvalidFieldKindError, InvalidFieldNameGrammarError, InvalidKeyGrammarError, QueryableFieldCapExceededError, ReservedContentTypeKeyError, StorageOnlyFieldNotQueryableError, ValidationError, VersionConflictError, } from "./errors.js";
+import { EntityNotLiveError } from "../core/entity-liveness.js";
+import { ContentTypeAlreadyExistsError, ContentTypeNotFoundError, ForbiddenError, InvalidFieldKindError, InvalidFieldNameGrammarError, InvalidKeyGrammarError, QueryableFieldCapExceededError, ReservedContentTypeKeyError, StorageOnlyFieldNotQueryableError, ValidationError, VersionConflictError, } from "./errors.js";
 import { resolveFieldIndexTransition, validateIdentifierGrammar } from "./index-provisioning.js";
 import { isContentTypeFieldKind, isIndexableFieldKind, } from "./types.js";
 /** Reserved forever for the legacy `posts` table — an operator Collection can never take these keys. */
+/**
+ * Field-name guards shared by register and update, in order: every name passes the identifier
+ * grammar (`InvalidFieldNameGrammarError`), THEN no name appears twice
+ * (`VALIDATION_ERROR(fields_duplicate_name)`). Duplicates are refused because entry values are
+ * stored keyed by field name and the index-transition diff builds a name-keyed map, so two defs
+ * sharing a name leave one of them unaddressable (last one wins). Returns `null` when both pass.
+ *
+ * @complexity O(f) in the number of submitted fields.
+ */
+function fieldNameError(fields) {
+    for (const field of fields) {
+        if (!validateIdentifierGrammar(field.name)) {
+            return new InvalidFieldNameGrammarError(`field name '${field.name}' fails the identifier grammar gate`);
+        }
+    }
+    const seen = new Set();
+    for (const field of fields) {
+        if (seen.has(field.name)) {
+            return new ValidationError(`field name '${field.name}' appears more than once`, "fields_duplicate_name");
+        }
+        seen.add(field.name);
+    }
+    return null;
+}
 const RESERVED_CONTENT_TYPE_KEYS = new Set(["post", "page"]);
 /** Per-type cap on `queryable` fields (queryable-index sprawl mitigation). */
 const QUERYABLE_FIELD_CAP = 20;
@@ -34,12 +59,10 @@ export async function registerContentType(required) {
     if (RESERVED_CONTENT_TYPE_KEYS.has(input.key)) {
         return { ok: false, error: new ReservedContentTypeKeyError(`key '${input.key}' is permanently reserved for the legacy 'posts' table`) };
     }
-    // Guard 3: field-name grammar (every field, before any kind/cap check).
-    for (const field of input.fields) {
-        if (!validateIdentifierGrammar(field.name)) {
-            return { ok: false, error: new InvalidFieldNameGrammarError(`field name '${field.name}' fails the identifier grammar gate`) };
-        }
-    }
+    // Guard 3: field-name grammar, then uniqueness (every field, before any kind/cap check).
+    const nameErrorOnRegister = fieldNameError(input.fields);
+    if (nameErrorOnRegister)
+        return { ok: false, error: nameErrorOnRegister };
     // Guard 4: field-kind, closed enum.
     for (const field of input.fields) {
         if (!isContentTypeFieldKind(field.kind)) {
@@ -62,6 +85,12 @@ export async function registerContentType(required) {
     if (countQueryableFields(input.fields) > QUERYABLE_FIELD_CAP) {
         return { ok: false, error: new QueryableFieldCapExceededError(`content type '${input.key}' submits more than ${QUERYABLE_FIELD_CAP} queryable fields`) };
     }
+    // Row 7 — a pre-check outside the transaction. Not race-safe by itself (that's the in-tx check
+    // below), but it avoids opening a transaction for the overwhelmingly common not-found case.
+    const existingBeforeTx = await deps.repo.findByKey({ workspaceId: input.workspaceId, key: input.key });
+    if (existingBeforeTx) {
+        return { ok: false, error: new ContentTypeAlreadyExistsError(input.key, existingBeforeTx.status === "tombstone") };
+    }
     const now = deps.clock.nowIso();
     const contentType = {
         workspaceId: input.workspaceId,
@@ -72,22 +101,37 @@ export async function registerContentType(required) {
         version: 1,
         tombstonedAt: null,
     };
-    await deps.repo.transaction(async () => {
-        await deps.repo.save(contentType);
-        await deps.repo.appendRevision({
-            contentTypeKey: input.key,
-            workspaceId: input.workspaceId,
-            op: "register",
-            stateJson: contentType,
-            actorId: input.actorId,
-            principalKind: input.principalKind ?? null,
-            delegatedByWorkspaceId: input.delegatedByWorkspaceId ?? null,
-            delegatedById: input.delegatedById ?? null,
-            recordedAt: now,
+    try {
+        await deps.repo.transaction(async () => {
+            // The check that actually closes the race: two concurrent first-widget creates both see the
+            // pre-check above return null, but only one of them can win this in-tx re-check before save.
+            const existingInTx = await deps.repo.findByKey({ workspaceId: input.workspaceId, key: input.key });
+            if (existingInTx) {
+                throw new ContentTypeAlreadyExistsError(input.key, existingInTx.status === "tombstone");
+            }
+            await deps.repo.save(contentType);
+            await deps.repo.appendRevision({
+                contentTypeKey: input.key,
+                workspaceId: input.workspaceId,
+                op: "register",
+                stateJson: contentType,
+                actorId: input.actorId,
+                principalKind: input.principalKind ?? null,
+                delegatedByWorkspaceId: input.delegatedByWorkspaceId ?? null,
+                delegatedById: input.delegatedById ?? null,
+                recordedAt: now,
+            });
+            if (deps.watermark)
+                await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
         });
-        if (deps.watermark)
-            await deps.watermark.stampWatermark({ workspaceId: input.workspaceId });
-    });
+    }
+    catch (err) {
+        if (err instanceof ContentTypeAlreadyExistsError)
+            return { ok: false, error: err };
+        throw err;
+    }
+    // Index provisioning runs only once the transaction has committed a new row — never on the
+    // already-exists path above.
     await deps.indexProvisioner.provisionIndexesForNewContentType({
         workspaceId: input.workspaceId,
         contentTypeKey: input.key,
@@ -118,6 +162,12 @@ export async function updateContentTypeFields(required) {
     if (!current) {
         return { ok: false, error: new ContentTypeNotFoundError(`content type '${input.key}' was not found in workspace '${input.workspaceId}'`) };
     }
+    // Row 15's sibling — a tombstoned type is terminal (INV-06); this check runs before the version
+    // check so a stale-version update against a tombstoned row still reports "tombstoned", not
+    // "version conflict" (the tombstone tore down every queryable index, so the schema is moot).
+    if (current.status === "tombstone") {
+        return { ok: false, error: new EntityNotLiveError("content type", input.key, "tombstoned") };
+    }
     // U-004-B1: expectedVersion checked FIRST — before fields_empty, before any per-field guard.
     if (input.expectedVersion !== current.version) {
         return { ok: false, error: new VersionConflictError(`expected version ${input.expectedVersion} for content type '${input.key}', found ${current.version}`) };
@@ -125,11 +175,9 @@ export async function updateContentTypeFields(required) {
     if (input.fields.length === 0) {
         return { ok: false, error: new ValidationError(`content type '${input.key}' update submitted an empty fields array`, "fields_empty") };
     }
-    for (const field of input.fields) {
-        if (!validateIdentifierGrammar(field.name)) {
-            return { ok: false, error: new InvalidFieldNameGrammarError(`field name '${field.name}' fails the identifier grammar gate`) };
-        }
-    }
+    const nameErrorOnUpdate = fieldNameError(input.fields);
+    if (nameErrorOnUpdate)
+        return { ok: false, error: nameErrorOnUpdate };
     for (const field of input.fields) {
         if (!isContentTypeFieldKind(field.kind)) {
             return { ok: false, error: new InvalidFieldKindError(`field '${field.name}' has kind '${field.kind}', not one of the closed field-kind enum`) };

package/dist/core/entity-liveness.d.ts

@@ -0,0 +1,55 @@
+import { ToolInputError } from "@jini-ai/core";
+/**
+ * @file The write-side counterpart to `not-trashed.ts`'s read-side `notTrashed()` filter (Tovu
+ * `features/trash/not-trashed.ts`).
+ *
+ * Purpose:
+ * A recurring defect across this codebase's writers: a mutation loads its row with a `findById`
+ * (or equivalent) that returns trashed and tombstoned rows just as readily as live ones, and never
+ * asks whether the row it found is actually live before saving over it. Fixed per writer, that is
+ * an unbounded number of near-identical patches, each one easy to forget on the next new writer.
+ * This module is the one shared check every writer calls right after its own load, so the check
+ * exists exactly once.
+ *
+ * Why it lives in `@jini-ai/cms/core` rather than in a Tovu module or a Jini domain package:
+ * Tovu's writers (pages, SEO, redirects) and Jini's own domain writers (media, content-types,
+ * taxonomy) both need it, Jini cannot import anything Tovu owns, and duplicating the check per side
+ * reintroduces the drift this module exists to remove. `core` is the one place both reach.
+ *
+ * Why `EntityNotLiveError` extends `ToolInputError` rather than a plain `Error`: the daemon's tool
+ * executor already treats `ToolInputError` as caller-facing (see `registration-kit.ts`'s doc
+ * comment), so every domain's agent tool surfaces this error's message to the caller with no
+ * per-domain allowlist entry, and every HTTP route that already maps `ToolInputError`-family errors
+ * picks it up for free. A per-domain rule added to `contracts/core/model-facing-tool-errors.ts`
+ * instead would be exactly the "correct primitive, unwired call site" defect this codebase keeps
+ * hitting — the check would exist but a caller could still fail to wire it in.
+ *
+ * The message is built only from a fixed string, the entity kind and the caller's own id (never
+ * from row content), so it satisfies `contracts/core/model-facing-tool-errors.ts`'s safety rule for
+ * a caller-facing message with no redaction step.
+ */
+/** A record's liveness as far as this guard is concerned. `"live"` never throws. */
+export type EntityLiveness = "live" | "trashed" | "tombstoned";
+/**
+ * Thrown by {@link assertEntityLive} for a non-live entity. `code` is the stable machine-readable
+ * discriminant; `entityType`/`entityId`/`state` are the values the message was built from, kept on
+ * the instance so a caller that wants to branch on them (rather than parse the message) can.
+ */
+export declare class EntityNotLiveError extends ToolInputError {
+    readonly entityType: string;
+    readonly entityId: string;
+    readonly state: "trashed" | "tombstoned";
+    readonly code: "ENTITY_IN_TRASH" | "ENTITY_TOMBSTONED";
+    constructor(entityType: string, entityId: string, state: "trashed" | "tombstoned");
+}
+/**
+ * Throws {@link EntityNotLiveError} unless `required.state` is `"live"`. Call this immediately
+ * after a writer's own load, before any mutation of the loaded row.
+ * @complexity O(1).
+ */
+export declare function assertEntityLive(required: {
+    entityType: string;
+    entityId: string;
+    state: EntityLiveness;
+}): void;
+//# sourceMappingURL=entity-liveness.d.ts.map

package/dist/core/entity-liveness.js

@@ -0,0 +1,38 @@
+import { ToolInputError } from "@jini-ai/core";
+/**
+ * Thrown by {@link assertEntityLive} for a non-live entity. `code` is the stable machine-readable
+ * discriminant; `entityType`/`entityId`/`state` are the values the message was built from, kept on
+ * the instance so a caller that wants to branch on them (rather than parse the message) can.
+ */
+export class EntityNotLiveError extends ToolInputError {
+    entityType;
+    entityId;
+    state;
+    code;
+    constructor(entityType, entityId, state) {
+        super(buildEntityNotLiveMessage(entityType, entityId, state));
+        this.entityType = entityType;
+        this.entityId = entityId;
+        this.state = state;
+        this.name = "EntityNotLiveError";
+        this.code = state === "trashed" ? "ENTITY_IN_TRASH" : "ENTITY_TOMBSTONED";
+    }
+}
+/** @complexity O(1). Pure string formatting; the two messages are tested byte-for-byte. */
+function buildEntityNotLiveMessage(entityType, entityId, state) {
+    if (state === "trashed") {
+        return `ENTITY_IN_TRASH: ${entityType} '${entityId}' is in the Trash. Restore it from the Trash before changing it.`;
+    }
+    return `ENTITY_TOMBSTONED: ${entityType} '${entityId}' was permanently deleted and can't be changed.`;
+}
+/**
+ * Throws {@link EntityNotLiveError} unless `required.state` is `"live"`. Call this immediately
+ * after a writer's own load, before any mutation of the loaded row.
+ * @complexity O(1).
+ */
+export function assertEntityLive(required) {
+    if (required.state === "live")
+        return;
+    throw new EntityNotLiveError(required.entityType, required.entityId, required.state);
+}
+//# sourceMappingURL=entity-liveness.js.map

package/dist/core/index.d.ts

@@ -41,5 +41,6 @@
 export type { UUID, ISODateTime, JsonPrimitive, JsonValue, JsonObject, JsonArray, DomainEvent, EventBusPort, OutboxRecord, OutboxPort, ClockPort, IdGeneratorPort, } from './ports.js';
 export type { ChangeSetStatus, ChangeSetOperation, ChangeSetRecord, ChangeSetItemRecord, ChangeSetWithItems, ChangeSetRepoPort, } from './commands/change-set.js';
 export * from './commands/command.js';
+export * from './entity-liveness.js';
 export * from './tools/registration-kit.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -39,5 +39,6 @@
  * behind a registration call the host makes, not behind a kernel barrel.
  */
 export * from './commands/command.js';
+export * from './entity-liveness.js';
 export * from './tools/registration-kit.js';
 //# sourceMappingURL=index.js.map

package/dist/core/tools/registration-kit.d.ts

@@ -91,22 +91,56 @@ export type DerivedRiskByToolId = ReadonlyMap<string, AgentToolSideEffect>;
  */
 export declare const AGENT_TOOL_PRINCIPAL_KIND: "agent";
 /**
- * Actor-class rules that cannot be honored while no confirmation transport is wired.
+ * Actor-class rules that need a human confirmer.
  *
  * `confirmer-must-equal-own-delegatedBy` means "a human must confirm this, and the confirmer must
- * be the principal who delegated". A host can only deliver that by building `ToolExecutor` with an
- * `ExecutionDelegate`. Without one, `descriptor.requiresConfirmation` would park the execution on a
- * promise only `resumeConfirmation` can settle — and nothing would call it. The park is also unbounded, because `descriptor.timeoutMs`'s timer is armed only AFTER the
- * confirmation await.
+ * be the principal who delegated". The kit never delivers that through `descriptor.requiresConfirmation`:
+ * without a host `ExecutionDelegate`, that flag parks the execution on a promise only
+ * `resumeConfirmation` can settle, and nothing would call it (unbounded, too, because
+ * `descriptor.timeoutMs`'s timer is armed only AFTER the confirmation await).
  *
- * So a tool carrying this rule must not be wired at all. Today none is — `collections_execute_cleanup`,
- * `database_execute_migrate_forward`, and `backup_execute_restore` all carry it and all three are
- * declared unwired — which makes this guard a statement of the invariant rather than a fix: a
- * future edit wiring any of them fails the build instead of silently shipping a tool whose stated
- * human-confirmation requirement is unenforceable. When a confirmation transport does land, this
- * constant is the deliberate place to relax.
+ * So a tool carrying this rule is wirable only when its handler was built with
+ * {@link humanConfirmedHandler}, which asks the human through the host's own confirmation transport
+ * and runs the action only on an explicit yes. Any other handler fails the build.
  */
 export declare const ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT: Set<string>;
+/**
+ * The human who confirmed, as {@link humanConfirmedHandler} hands it to `run`: always the run's own
+ * delegating principal (`ctx.principal.id`, see {@link AGENT_TOOL_PRINCIPAL_KIND}), always
+ * `kind: "user"`. The only thing a `run` step may pass to a confirm step as its confirmer.
+ */
+export interface HumanConfirmer {
+    readonly id: string;
+    readonly kind: "user";
+}
+/** What the host's transport reports back. Only exactly `confirmed: true` counts as a yes. */
+export type HumanConfirmationAnswer = {
+    confirmed: true;
+} | {
+    confirmed: false;
+    result: unknown;
+};
+/**
+ * Builds the one kind of handler a `confirmer-must-equal-own-delegatedBy` tool may be wired with
+ * (see {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}).
+ *
+ * The order is fixed here, not left to each domain: `prepare` (validate, pre-authorize, derive what
+ * the human will see) → `askHuman` (the host's transport, e.g. an MCP-UI dialog) → `run`, only when
+ * the answer is exactly `{ confirmed: true }`. The decision never comes from `ctx.input`, so nothing
+ * the model sends can stand in for the human. `run` gets the confirmer as the delegating human.
+ *
+ * @param steps.prepare - Reads input and derives what the human is asked about. May throw.
+ * @param steps.askHuman - Asks the human through the host's transport. Throws when no human can be
+ *   asked; a no-answer returns `{ confirmed: false, result }` and `result` is the tool's result.
+ * @param steps.run - Performs the action on a yes.
+ * @returns A handler {@link assertToolIsWirable} accepts for a tool carrying the rule.
+ * @complexity O(1) plus the three steps.
+ */
+export declare function humanConfirmedHandler<TPrepared>(steps: {
+    prepare: (ctx: Parameters<ToolHandler>[0]) => Promise<TPrepared>;
+    askHuman: (ctx: Parameters<ToolHandler>[0], prepared: TPrepared) => Promise<HumanConfirmationAnswer>;
+    run: (ctx: Parameters<ToolHandler>[0], prepared: TPrepared, confirmer: HumanConfirmer) => Promise<unknown>;
+}): ToolHandler;
 /**
  * Indexes a domain catalog by tool id — the single lookup used for descriptors, risk metadata, and
  * schema-bearing error messages.
@@ -220,8 +254,8 @@ export declare function decorateWithSchema(params: {
 /**
  * Build-time gate on a single tool's risk metadata: refuses to wire a tool whose declared
  * `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
- * whose id that layer has not classified at all, or whose `actorClassRule` needs a confirmation
- * transport that does not exist.
+ * whose id that layer has not classified at all, or whose `actorClassRule` needs a human confirmer
+ * its handler does not ask for.
  *
  * Throws rather than warning, and at registration time rather than call time: a metadata
  * inconsistency is a developer error that should stop the daemon booting, not a runtime condition
@@ -230,7 +264,10 @@ export declare function decorateWithSchema(params: {
  * @param params.toolId - The wired tool id.
  * @param params.catalogEntry - Its `agent-tools.ts` entry, the declared side of the comparison.
  * @param params.derivedRisk - The wiring layer's independent classification, the derived side.
- * @throws {Error} If the tool is unclassified, misclassified, or needs missing confirmation support.
+ * @param params.handler - The handler being wired; checked only for a tool carrying a rule in
+ *   {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}.
+ * @throws {Error} If the tool is unclassified, misclassified, or needs a human confirmer its handler
+ *   does not ask for.
  * @complexity O(1) — two map/set lookups.
  * @overallScore 100
  */
@@ -238,6 +275,7 @@ export declare function assertToolIsWirable(params: {
     toolId: string;
     catalogEntry: WirableToolDefinition;
     derivedRisk: DerivedRiskByToolId;
+    handler?: ToolHandler;
 }): void;
 /**
  * Turns one domain's handler map into `ToolRegistration`s, applying every build-time gate the
@@ -258,9 +296,9 @@ export declare function assertToolIsWirable(params: {
  * the same rule, and a `ToolPolicy`-only check would be bypassable by any future non-tool caller of
  * the same domain function, which is precisely why the chokepoint owns the gate.
  *
- * `descriptor.requiresConfirmation` is deliberately never set — see
- * {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT} for why that omission is safe rather
- * than a hole.
+ * `descriptor.requiresConfirmation` is deliberately never set — a tool that needs a human confirm
+ * asks inside its own {@link humanConfirmedHandler}; see
+ * {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}.
  *
  * @param spec.domain - Human-readable domain name, used only in failure messages.
  * @param spec.catalogModule - Path of the catalog file, named in the drift message so the failure

package/dist/core/tools/registration-kit.js

@@ -48,22 +48,47 @@ import { ForbiddenError } from "../commands/command.js";
 // and Forms' `CommandActor.kind` param without a cast at either call site.
 export const AGENT_TOOL_PRINCIPAL_KIND = "agent";
 /**
- * Actor-class rules that cannot be honored while no confirmation transport is wired.
+ * Actor-class rules that need a human confirmer.
  *
  * `confirmer-must-equal-own-delegatedBy` means "a human must confirm this, and the confirmer must
- * be the principal who delegated". A host can only deliver that by building `ToolExecutor` with an
- * `ExecutionDelegate`. Without one, `descriptor.requiresConfirmation` would park the execution on a
- * promise only `resumeConfirmation` can settle — and nothing would call it. The park is also unbounded, because `descriptor.timeoutMs`'s timer is armed only AFTER the
- * confirmation await.
+ * be the principal who delegated". The kit never delivers that through `descriptor.requiresConfirmation`:
+ * without a host `ExecutionDelegate`, that flag parks the execution on a promise only
+ * `resumeConfirmation` can settle, and nothing would call it (unbounded, too, because
+ * `descriptor.timeoutMs`'s timer is armed only AFTER the confirmation await).
  *
- * So a tool carrying this rule must not be wired at all. Today none is — `collections_execute_cleanup`,
- * `database_execute_migrate_forward`, and `backup_execute_restore` all carry it and all three are
- * declared unwired — which makes this guard a statement of the invariant rather than a fix: a
- * future edit wiring any of them fails the build instead of silently shipping a tool whose stated
- * human-confirmation requirement is unenforceable. When a confirmation transport does land, this
- * constant is the deliberate place to relax.
+ * So a tool carrying this rule is wirable only when its handler was built with
+ * {@link humanConfirmedHandler}, which asks the human through the host's own confirmation transport
+ * and runs the action only on an explicit yes. Any other handler fails the build.
  */
 export const ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT = new Set(["confirmer-must-equal-own-delegatedBy"]);
+const HUMAN_CONFIRMED_HANDLERS = new WeakSet();
+/**
+ * Builds the one kind of handler a `confirmer-must-equal-own-delegatedBy` tool may be wired with
+ * (see {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}).
+ *
+ * The order is fixed here, not left to each domain: `prepare` (validate, pre-authorize, derive what
+ * the human will see) → `askHuman` (the host's transport, e.g. an MCP-UI dialog) → `run`, only when
+ * the answer is exactly `{ confirmed: true }`. The decision never comes from `ctx.input`, so nothing
+ * the model sends can stand in for the human. `run` gets the confirmer as the delegating human.
+ *
+ * @param steps.prepare - Reads input and derives what the human is asked about. May throw.
+ * @param steps.askHuman - Asks the human through the host's transport. Throws when no human can be
+ *   asked; a no-answer returns `{ confirmed: false, result }` and `result` is the tool's result.
+ * @param steps.run - Performs the action on a yes.
+ * @returns A handler {@link assertToolIsWirable} accepts for a tool carrying the rule.
+ * @complexity O(1) plus the three steps.
+ */
+export function humanConfirmedHandler(steps) {
+    const handler = async (ctx) => {
+        const prepared = await steps.prepare(ctx);
+        const answer = await steps.askHuman(ctx, prepared);
+        if (answer.confirmed !== true)
+            return answer.result;
+        return steps.run(ctx, prepared, { id: ctx.principal.id, kind: "user" });
+    };
+    HUMAN_CONFIRMED_HANDLERS.add(handler);
+    return handler;
+}
 /**
  * Indexes a domain catalog by tool id — the single lookup used for descriptors, risk metadata, and
  * schema-bearing error messages.
@@ -256,8 +281,8 @@ export function decorateWithSchema(params) {
 /**
  * Build-time gate on a single tool's risk metadata: refuses to wire a tool whose declared
  * `sideEffects` disagrees with the wiring layer's own {@link DerivedRiskByToolId} classification,
- * whose id that layer has not classified at all, or whose `actorClassRule` needs a confirmation
- * transport that does not exist.
+ * whose id that layer has not classified at all, or whose `actorClassRule` needs a human confirmer
+ * its handler does not ask for.
  *
  * Throws rather than warning, and at registration time rather than call time: a metadata
  * inconsistency is a developer error that should stop the daemon booting, not a runtime condition
@@ -266,7 +291,10 @@ export function decorateWithSchema(params) {
  * @param params.toolId - The wired tool id.
  * @param params.catalogEntry - Its `agent-tools.ts` entry, the declared side of the comparison.
  * @param params.derivedRisk - The wiring layer's independent classification, the derived side.
- * @throws {Error} If the tool is unclassified, misclassified, or needs missing confirmation support.
+ * @param params.handler - The handler being wired; checked only for a tool carrying a rule in
+ *   {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}.
+ * @throws {Error} If the tool is unclassified, misclassified, or needs a human confirmer its handler
+ *   does not ask for.
  * @complexity O(1) — two map/set lookups.
  * @overallScore 100
  */
@@ -279,8 +307,9 @@ export function assertToolIsWirable(params) {
     if (derived !== catalogEntry.sideEffects) {
         throw new Error(`tool-registrations: '${toolId}' declares sideEffects '${catalogEntry.sideEffects}' but this layer derives '${derived}' from what its handler calls — reconcile the two rather than trusting the declaration`);
     }
-    if (catalogEntry.actorClassRule && ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT.has(catalogEntry.actorClassRule)) {
-        throw new Error(`tool-registrations: '${toolId}' declares actorClassRule '${catalogEntry.actorClassRule}', which requires a human-confirmation transport this host has not wired — leave it unwired until one exists (see ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT)`);
+    const needsHuman = catalogEntry.actorClassRule && ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT.has(catalogEntry.actorClassRule);
+    if (needsHuman && !(params.handler && HUMAN_CONFIRMED_HANDLERS.has(params.handler))) {
+        throw new Error(`tool-registrations: '${toolId}' declares actorClassRule '${catalogEntry.actorClassRule}', which needs a human confirmer — build its handler with humanConfirmedHandler so a human answers through the host's confirmation transport (see ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT)`);
     }
 }
 /**
@@ -302,9 +331,9 @@ export function assertToolIsWirable(params) {
  * the same rule, and a `ToolPolicy`-only check would be bypassable by any future non-tool caller of
  * the same domain function, which is precisely why the chokepoint owns the gate.
  *
- * `descriptor.requiresConfirmation` is deliberately never set — see
- * {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT} for why that omission is safe rather
- * than a hole.
+ * `descriptor.requiresConfirmation` is deliberately never set — a tool that needs a human confirm
+ * asks inside its own {@link humanConfirmedHandler}; see
+ * {@link ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT}.
  *
  * @param spec.domain - Human-readable domain name, used only in failure messages.
  * @param spec.catalogModule - Path of the catalog file, named in the drift message so the failure
@@ -326,7 +355,7 @@ export function buildDomainRegistrations(spec) {
         if (!catalogEntry) {
             throw new Error(`tool-registrations: ${spec.domain} catalog has no entry named '${id}' — ${spec.catalogModule} drifted`);
         }
-        assertToolIsWirable({ toolId: id, catalogEntry, derivedRisk: spec.derivedRisk });
+        assertToolIsWirable({ toolId: id, catalogEntry, derivedRisk: spec.derivedRisk, handler });
         if (!catalogEntry.inputSchema) {
             throw new Error(`tool-registrations: wired tool '${id}' publishes no inputSchema — add one to its entry in ${spec.catalogModule} so the model gets a contract, or leave the tool unwired`);
         }

package/dist/media/media-service.js

@@ -51,6 +51,7 @@
  * bespoke `MediaRecord` table in place of a generic-entries model.
  */
 import { createHash } from "node:crypto";
+import { assertEntityLive } from "../core/entity-liveness.js";
 import { MediaConflictError, MediaNotFoundError, MediaSourceImmutableError, MediaStillReferencedError, MediaValidationError, } from "./types.js";
 import { withSha256Lock } from "./blob-gc-lock.js";
 import { tombstoneBlobIfUnreferenced } from "./blob-gc.js";
@@ -457,6 +458,7 @@ export async function updateMediaMetadata(required, _optional = {}) {
     const existing = await deps.mediaRepo.findById({ workspaceId: input.workspaceId, id: input.id });
     if (!existing)
         throw new MediaNotFoundError(`media '${input.id}' was not found`);
+    assertEntityLive({ entityType: "media", entityId: input.id, state: existing.status === "trashed" ? "trashed" : "live" });
     if (input.width !== undefined && input.width !== null)
         assertPositiveIntegerOrThrow(input.width, "width");
     if (input.height !== undefined && input.height !== null)

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

@@ -1,27 +1,3 @@
-/**
- * @file Write-service for the `navigation` library.
- *
- * Purpose:
- * Implements the menu mutation slice: create, whole-tree update (OCC), soft
- * delete → hard purge, and location assignment. Mirrors the host's `post`
- * feature style (required/optional param objects, typed errors, OCC via
- * `version`).
- *
- * How it relates to the project:
- * - Storage is `MenuRepoPort` (`repo.memory.ts`) — a self-contained repo, not
- *   the generic entries repo (see `repo.memory.ts`'s file header for why).
- * - Location assignment additionally writes `NavLocationBindingRepoPort`
- *   (`ports.ts`), the one real port this library declares.
- * - In production this whole module runs inside the command
- *   gateway/write chokepoint (same-transaction revision, attribution,
- *   `entry_refs` extraction). That gateway is not implemented as running code
- *   yet, so these functions are the chokepoint's future *contents*, called
- *   directly for now.
- *
- * Architectural role:
- * Feature logic only. No Express/route code, no direct SQL — everything goes
- * through the injected repo ports (`deps`).
- */
 import type { ClockPort, IdGeneratorPort, OutboxPort, UUID } from "../core/ports.js";
 import type { MenuRepoPort } from "./repo.memory.js";
 import type { NavLocationBindingRepoPort } from "./ports.js";

package/dist/navigation/menu-service.js

@@ -1,3 +1,28 @@
+/**
+ * @file Write-service for the `navigation` library.
+ *
+ * Purpose:
+ * Implements the menu mutation slice: create, whole-tree update (OCC), soft
+ * delete → hard purge, and location assignment. Mirrors the host's `post`
+ * feature style (required/optional param objects, typed errors, OCC via
+ * `version`).
+ *
+ * How it relates to the project:
+ * - Storage is `MenuRepoPort` (`repo.memory.ts`) — a self-contained repo, not
+ *   the generic entries repo (see `repo.memory.ts`'s file header for why).
+ * - Location assignment additionally writes `NavLocationBindingRepoPort`
+ *   (`ports.ts`), the one real port this library declares.
+ * - In production this whole module runs inside the command
+ *   gateway/write chokepoint (same-transaction revision, attribution,
+ *   `entry_refs` extraction). That gateway is not implemented as running code
+ *   yet, so these functions are the chokepoint's future *contents*, called
+ *   directly for now.
+ *
+ * Architectural role:
+ * Feature logic only. No Express/route code, no direct SQL — everything goes
+ * through the injected repo ports (`deps`).
+ */
+import { assertEntityLive } from "../core/entity-liveness.js";
 import { NAV_DOC_TYPE, } from "./types.js";
 // ---------------------------------------------------------------------------
 // Outbox event publication — each mutating function below
@@ -293,6 +318,7 @@ export async function updateMenuTree(required, optional = {}) {
     const existing = await deps.repo.findById({ workspaceId: input.workspaceId, id: input.id });
     if (!existing)
         throw new MenuNotFoundError(`menu '${input.id}' was not found`);
+    assertEntityLive({ entityType: "menu", entityId: input.id, state: existing.status === "trash" ? "trashed" : "live" });
     if (existing.version !== input.expectedVersion) {
         throw new MenuConflictError(`menu '${input.id}' was modified concurrently (expected version ${input.expectedVersion}, found ${existing.version})`);
     }
@@ -360,6 +386,7 @@ export async function assignLocation(required, _optional = {}) {
     const menu = await deps.repo.findById({ workspaceId: input.workspaceId, id: input.menuId });
     if (!menu)
         throw new MenuNotFoundError(`menu '${input.menuId}' was not found`);
+    assertEntityLive({ entityType: "menu", entityId: input.menuId, state: menu.status === "trash" ? "trashed" : "live" });
     const now = deps.clock.nowIso();
     const existingBinding = await deps.bindingRepo.findByLocation({
         workspaceId: input.workspaceId,

package/dist/navigation/tool-registrations.d.ts

@@ -1,14 +1,3 @@
-/**
- * @file Navigation's (Menus') half of the agent-tool authorization wiring: maps `agent-tools.ts`'s five
- * catalog entries onto `menu-service.ts`'s read/create/update/assign operations, as
- * `ToolRegistration`s. The entire catalog is wired — `deleteMenu` is deliberately absent from the
- * catalog rather than present-but-unwired; see `navigation/agent-tools.ts`'s own header.
- *
- * Authorization shape: like Media and unlike Forms/Identity/Widgets, `menu-service.ts`'s functions
- * perform NO internal `authorize()` call of their own — every admin HTTP route a host builds gates
- * inline. Every handler here does the same via the kit's `requireToolPermission`, which is the
- * single evaluation for these tools, located where the real route locates it.
- */
 import type { AuthorizeFn } from "../core/commands/command.js";
 import type { OutboxPort } from "../core/ports.js";
 import { type DerivedRiskByToolId, type ToolRegistration } from "../core/tools/registration-kit.js";

package/dist/navigation/tool-registrations.js

@@ -1,3 +1,15 @@
+/**
+ * @file Navigation's (Menus') half of the agent-tool authorization wiring: maps `agent-tools.ts`'s five
+ * catalog entries onto `menu-service.ts`'s read/create/update/assign operations, as
+ * `ToolRegistration`s. The entire catalog is wired — `deleteMenu` is deliberately absent from the
+ * catalog rather than present-but-unwired; see `navigation/agent-tools.ts`'s own header.
+ *
+ * Authorization shape: like Media and unlike Forms/Identity/Widgets, `menu-service.ts`'s functions
+ * perform NO internal `authorize()` call of their own — every admin HTTP route a host builds gates
+ * inline. Every handler here does the same via the kit's `requireToolPermission`, which is the
+ * single evaluation for these tools, located where the real route locates it.
+ */
+import { ToolInputError } from "@jini-ai/core";
 import { buildDomainRegistrations, indexCatalogById, requireInputRecord, requireNumber, requireString, requireToolPermission, withSchemaOnRejection, } from "../core/tools/registration-kit.js";
 import { menusAgentToolCatalog } from "./agent-tools.js";
 import { assignLocation, createMenu, MenuNotFoundError, MenuValidationError, updateMenuTree } from "./menu-service.js";
@@ -65,6 +77,9 @@ export function buildMenusRegistrations(routeDeps) {
         menus_create_menu: async (ctx) => {
             const input = requireInputRecord(ctx.input);
             await requireToolPermission(routeDeps, { principalId: ctx.principal.id, permission: "admin.menus.create", entityType: "menu" });
+            if (input.items !== undefined && !Array.isArray(input.items)) {
+                throw new ToolInputError("'items' must be an array of nav items");
+            }
             return withSchemaOnRejection({ toolId: "menus_create_menu", catalog: CATALOG_BY_ID, isShapeRejection: isMenusShapeRejection }, async () => {
                 const { menu } = await createMenu({
                     deps: menusDeps(routeDeps),

package/dist/taxonomy/agent-tools.d.ts

@@ -26,18 +26,12 @@
  *   - `confirm()` structurally refuses an agent: `gateway.ts`'s own body — "if (principalKind ===
  *     'agent') throw new ForbiddenError('agent principals may not confirm a gated mutation', ...)"
  *     — before any permission check even runs. No `taxonomy_confirm_merge_term`-equivalent tool
- *     exists in this catalog, and no description below may even imply that step (mirrors
- *     `features/recovery/agent-tools.ts`'s own discipline for `backup_execute_restore`: "the
- *     human confirmation step is exactly the one act the gated-mutations gateway reserves for
- *     kind='user'/api_key principals").
- *   - `execute()` needs a confirmation token a human already minted through the admin UI's own
- *     ceremony (`server/routes/admin/taxonomy/merge-term.ts`'s `/merge/confirm` route) — the same
- *     `confirmer-must-equal-own-delegatedBy` actor-class rule `database_execute_migrate_forward`/
- *     `backup_execute_restore` carry, which `assistant/tool-registration-kit.ts`'s
- *     `ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT` refuses to build regardless of this
- *     catalog's own choice, because the host's `ToolExecutor` has no confirmation transport wired.
- *     `taxonomy_execute_merge_term` is declared here (so the exclusion is a structural build-time
- *     refusal, not just an absent handler) but is NEVER wired by `tool-registrations.ts`.
+ *     exists in this catalog.
+ *   - `taxonomy_execute_merge_term` (2026-09-24) asks the human in chat before it runs: the host
+ *     wires it with the kit's `humanConfirmedHandler`, which shows a confirm dialog and only on the
+ *     human's own click confirms as that human (`kind='user'`) and executes as the agent acting for
+ *     them — the `confirmer-must-equal-own-delegatedBy` rule. The model never sees or supplies a
+ *     token. A merge deletes the source term's assignments with no Trash or undo, so it is gated.
  *
  * Naming: `taxonomy_*`, matching this package's own name — distinct from `features/content-types`'
  * `collections_*` prefix (a different pairing) and from `features/entries`' own
@@ -66,7 +60,7 @@ export interface AgentToolDefinition {
     /**
      * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
      * (`assistant/tool-registration-kit.ts`'s `buildDomainRegistrations`, which refuses to wire any
-     * tool lacking one). Optional — `taxonomy_execute_merge_term` is never wired, so it carries none.
+     * tool lacking one).
      */
     inputSchema?: Readonly<Record<string, unknown>>;
 }

package/dist/taxonomy/agent-tools.js

@@ -26,18 +26,12 @@
  *   - `confirm()` structurally refuses an agent: `gateway.ts`'s own body — "if (principalKind ===
  *     'agent') throw new ForbiddenError('agent principals may not confirm a gated mutation', ...)"
  *     — before any permission check even runs. No `taxonomy_confirm_merge_term`-equivalent tool
- *     exists in this catalog, and no description below may even imply that step (mirrors
- *     `features/recovery/agent-tools.ts`'s own discipline for `backup_execute_restore`: "the
- *     human confirmation step is exactly the one act the gated-mutations gateway reserves for
- *     kind='user'/api_key principals").
- *   - `execute()` needs a confirmation token a human already minted through the admin UI's own
- *     ceremony (`server/routes/admin/taxonomy/merge-term.ts`'s `/merge/confirm` route) — the same
- *     `confirmer-must-equal-own-delegatedBy` actor-class rule `database_execute_migrate_forward`/
- *     `backup_execute_restore` carry, which `assistant/tool-registration-kit.ts`'s
- *     `ACTOR_CLASS_RULES_REQUIRING_CONFIRMATION_TRANSPORT` refuses to build regardless of this
- *     catalog's own choice, because the host's `ToolExecutor` has no confirmation transport wired.
- *     `taxonomy_execute_merge_term` is declared here (so the exclusion is a structural build-time
- *     refusal, not just an absent handler) but is NEVER wired by `tool-registrations.ts`.
+ *     exists in this catalog.
+ *   - `taxonomy_execute_merge_term` (2026-09-24) asks the human in chat before it runs: the host
+ *     wires it with the kit's `humanConfirmedHandler`, which shows a confirm dialog and only on the
+ *     human's own click confirms as that human (`kind='user'`) and executes as the agent acting for
+ *     them — the `confirmer-must-equal-own-delegatedBy` rule. The model never sees or supplies a
+ *     token. A merge deletes the source term's assignments with no Trash or undo, so it is gated.
  *
  * Naming: `taxonomy_*`, matching this package's own name — distinct from `features/content-types`'
  * `collections_*` prefix (a different pairing) and from `features/entries`' own
@@ -172,9 +166,7 @@ export const taxonomyAgentToolCatalog = [
         description: "Previews merging one term into another: recomputes and returns the current overlap-loss disclosure (how many pieces of content are " +
             "already assigned to BOTH terms, whose duplicate assignment would be silently lost by the merge's own dedup step) plus a planId/planHash " +
             "a human can use in the admin UI's own merge confirmation ceremony. Read-only — performs no merge. Rejects immediately if fromTermId " +
-            "equals intoTermId, before computing anything. This tool can only PLAN a merge; actually executing one requires a human to confirm " +
-            "through the admin UI — no tool in this catalog can do that step (by design: merges are destructive and irreversible for the merged-away " +
-            "term's own identity).",
+            "equals intoTermId, before computing anything. To actually merge, call taxonomy_execute_merge_term, which asks the user to confirm first.",
         sideEffects: "none",
         authorization: { permission: "admin.taxonomy.manage" },
         inputSchema: {
@@ -188,13 +180,22 @@ export const taxonomyAgentToolCatalog = [
         },
     },
     {
-        // EXCLUDED BY DESIGN, never wired: see this file's header. Token-gated; `core/gated-mutations`'s
-        // own confirm() step structurally refuses an agent principal, and no confirmation transport
-        // exists for an agent to be handed a human-minted token through anyway.
+        // Asks the human first — see this file's header.
         name: "taxonomy_execute_merge_term",
-        description: "Executes a previously confirmed term merge using a human-minted confirmation token. NEVER agent-callable — see file header.",
+        description: "Merges one term into another: every piece of content tagged with fromTermId is re-tagged with intoTermId, and fromTermId is " +
+            "deprecated. Shows the user a confirm dialog first and only merges if they confirm. The merge can't be undone. Call " +
+            "taxonomy_plan_merge_term first to see how many items are affected.",
         sideEffects: "mutates-durable-state",
         authorization: { permission: "admin.taxonomy.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["fromTermId", "intoTermId"],
+            properties: {
+                fromTermId: { ...TERM_ID_SCHEMA, description: "The term to merge away. It is deprecated after the merge." },
+                intoTermId: { ...TERM_ID_SCHEMA, description: "The term that receives every assignment." },
+            },
+        },
         actorClassRule: "confirmer-must-equal-own-delegatedBy",
     },
 ];

package/dist/taxonomy/content-lookup.d.ts

@@ -36,8 +36,14 @@ export interface ContentRecordLookupPort {
     }): Promise<{
         workspaceId: string;
         kind: string;
+        deletedAt?: string | null;
     } | null>;
 }
+/**
+ * Row 63 (web-high fix plan, 2026-09-24): a trashed post/page must refuse a term assign/unassign,
+ * not silently accept one — `assertEntityLive` throws `EntityNotLiveError` the moment `deletedAt`
+ * is set, before this ever returns a resolvable target to `write-service.ts`'s join guards.
+ */
 export declare function createPostBackedContentLookup(deps: {
     postRepo: ContentRecordLookupPort;
     workspaceId: string;

package/dist/taxonomy/content-lookup.js

@@ -1,9 +1,19 @@
+import { assertEntityLive } from "../core/entity-liveness.js";
 import { isContentTypeOnAllowList } from "./write-service.js";
+/**
+ * Row 63 (web-high fix plan, 2026-09-24): a trashed post/page must refuse a term assign/unassign,
+ * not silently accept one — `assertEntityLive` throws `EntityNotLiveError` the moment `deletedAt`
+ * is set, before this ever returns a resolvable target to `write-service.ts`'s join guards.
+ */
 export function createPostBackedContentLookup(deps) {
     return {
         async resolve({ contentId }) {
             const post = await deps.postRepo.findById({ workspaceId: deps.workspaceId, id: contentId });
-            return post ? { workspaceId: post.workspaceId, kind: post.kind } : null;
+            if (!post)
+                return null;
+            if (post.deletedAt)
+                assertEntityLive({ entityType: post.kind, entityId: contentId, state: "trashed" });
+            return { workspaceId: post.workspaceId, kind: post.kind };
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/cms",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Content-model capability for Jini-hosted products: framework-free contracts, ports, and domain services in `/core` and per-domain subpaths; Node-bound persistence adapters in `/server`.",
   "license": "Apache-2.0",
   "repository": {