@jini-ai/cms 0.3.7 → 0.3.8

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

@@ -2,6 +2,30 @@ import { ContentTypeNotFoundError, ForbiddenError, InvalidFieldKindError, Invali
 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 +58,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)) {
@@ -125,11 +147,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/cms",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "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": {