@jini-ai/cms 0.3.6 → 0.3.8

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

@@ -83,7 +83,7 @@ export declare function validateIdentifierGrammar(value: string): boolean;
  *
  * The PARAMETER type is deliberately the wider `ContentTypeFieldKind`. Narrowing it would be a
  * breaking change for `@jini-ai/cms`'s public consumers (`content-types/index.ts` documents this
- * function as what a host's own DDL provisioner calls, and Tovu re-exports it), and it would also
+ * function as what a host's own DDL provisioner calls, and the host re-exports it), and it would also
  * make the runtime guard below unreachable-looking to a reader while remaining fully reachable to
  * an untyped JavaScript caller. The runtime gate — not the signature — is what excludes
  * storage-only kinds.

package/dist/content-types/index-provisioning.js

@@ -113,7 +113,7 @@ const KIND_TO_CAST_LITERAL = {
  *
  * The PARAMETER type is deliberately the wider `ContentTypeFieldKind`. Narrowing it would be a
  * breaking change for `@jini-ai/cms`'s public consumers (`content-types/index.ts` documents this
- * function as what a host's own DDL provisioner calls, and Tovu re-exports it), and it would also
+ * function as what a host's own DDL provisioner calls, and the host re-exports it), and it would also
  * make the runtime guard below unreachable-looking to a reader while remaining fully reachable to
  * an untyped JavaScript caller. The runtime gate — not the signature — is what excludes
  * storage-only kinds.

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/ports.d.ts

@@ -130,7 +130,7 @@ export interface OutboxPort {
      * attempt cap) — an implementation must persist exactly what it is told, not re-derive the
      * decision from the row's own stored `attempts` (2026-09-06: this parameter replaced that
      * adapter-side re-derivation, mirroring `WebhookDeliveryRepoPort.markFailed`'s `nextStatus`
-     * shape in the Tovu host). `"pending"` re-enters the retry queue at `nextAttemptAt`; `"failed"`
+     * shape in the host). `"pending"` re-enters the retry queue at `nextAttemptAt`; `"failed"`
      * is terminal — `claimPending` only ever selects `"pending"` rows, so a `"failed"` row is
      * permanently excluded from retry regardless of `nextAttemptAt`.
      */

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/identity/auth-service.d.ts

@@ -15,7 +15,7 @@ import { type PrincipalRecord, type SessionRecord } from "./types.js";
  * verifying credentials, and a host that identifies a principal by some other means (e.g. a
  * loopback-only single-use boot token, which has nothing to verify a password against) calls it
  * directly instead of re-implementing session construction. Before this export existed, a
- * downstream host (Tovu) had duplicated this file's private `hashToken` byte-for-byte because
+ * downstream host had duplicated this file's private `hashToken` byte-for-byte because
  * `login()` was the only minter and hard-requires a password — this closes that fork.
  *
  * Architectural role:

package/dist/identity/auth-service.js

@@ -16,7 +16,7 @@ import { normalizeUsername } from "./username.js";
  * verifying credentials, and a host that identifies a principal by some other means (e.g. a
  * loopback-only single-use boot token, which has nothing to verify a password against) calls it
  * directly instead of re-implementing session construction. Before this export existed, a
- * downstream host (Tovu) had duplicated this file's private `hashToken` byte-for-byte because
+ * downstream host had duplicated this file's private `hashToken` byte-for-byte because
  * `login()` was the only minter and hard-requires a password — this closes that fork.
  *
  * Architectural role:

package/dist/identity/seed.d.ts

@@ -34,7 +34,7 @@ export interface SeedIdentityResult {
  * - A seed that RAN TO COMPLETION is a no-op — the owner-username lookup below early-returns after
  *   a single confirming read (`ensureOwnerRoleBinding`) and writes nothing. (This path does not
  *   reconcile a built-in policy whose permission list has since grown; that is the host's job — see
- *   Tovu's `applyBuiltinRoleGrants` / `migrateDeprecatedPermissionGrants`, chained onto
+ *   the host's `applyBuiltinRoleGrants` / `migrateDeprecatedPermissionGrants`, chained onto
  *   `identityReady`.)
  * - "Ran to completion" is judged on the owner user AND its role link, not the user alone. The link
  *   is the seed's last write, so the user is not on its own evidence the seed finished — see

package/dist/identity/seed.js

@@ -149,7 +149,7 @@ const BUILTIN_VIEWER_PERMISSIONS = ["content.read", "changeset.read", "plugin.re
 /**
  * Why every step below is "find, then save only what is missing" rather than a straight insert.
  *
- * This function's writes are NOT transactional and its caller is not awaited by its hosts (Tovu
+ * This function's writes are NOT transactional and its caller is not awaited by its hosts (one host
  * hands `seedIdentity`'s promise back as `RouteDeps.identityReady` and returns synchronously), so
  * a process that exits before the seed finishes — a fast-failing CLI command, a Ctrl-C, a crash —
  * leaves the workspace half-seeded. `seedIdentity`'s own early-return guard keys on the OWNER USER,
@@ -249,7 +249,7 @@ async function seedBuiltinRoleWithPolicy(required) {
  * still log in, and holds no role — and `resolveEffectivePermissions` (`authorize.ts`) starts from
  * `principal_roles` + `principal_policies`, so with neither present EVERY permission evaluates to
  * `no_grant`. Without this step the guard early-returns on the user it finds forever and the site
- * stays bricked for its owner, silently. Neither host-side reconciler closes it either: Tovu's
+ * stays bricked for its owner, silently. Neither host-side reconciler closes it either: the host's
  * `migrateDeprecatedPermissionGrants` and `applyBuiltinRoleGrants` are handed policy and role repos
  * only, never `principalRoles`, so neither can write a principal->role link at all.
  *
@@ -296,7 +296,7 @@ async function ensureOwnerRoleBinding(required) {
  * - A seed that RAN TO COMPLETION is a no-op — the owner-username lookup below early-returns after
  *   a single confirming read (`ensureOwnerRoleBinding`) and writes nothing. (This path does not
  *   reconcile a built-in policy whose permission list has since grown; that is the host's job — see
- *   Tovu's `applyBuiltinRoleGrants` / `migrateDeprecatedPermissionGrants`, chained onto
+ *   the host's `applyBuiltinRoleGrants` / `migrateDeprecatedPermissionGrants`, chained onto
  *   `identityReady`.)
  * - "Ran to completion" is judged on the owner user AND its role link, not the user alone. The link
  *   is the seed's last write, so the user is not on its own evidence the seed finished — see

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

@@ -34,9 +34,19 @@
  * content-types pass-through-`ToolPolicy` reasoning, not an oversight.
  *
  * Architectural role:
- * `media` domain declaration. Imports only the constants its own domain already enforces
- * (`DEFAULT_MAX_UPLOAD_BYTES`/`DEFAULT_ALLOWED_MIME_TYPES` from `media-service.ts`), so the
- * published JSON Schemas cannot drift from the validators.
+ * `media` domain declaration. Imports only the constant its own domain already enforces
+ * (`DEFAULT_ALLOWED_MIME_TYPES` from `media-service.ts`), so the published JSON Schema's allowed
+ * content types cannot drift from the validator.
+ *
+ * `media_upload_asset`'s size-cap wording (2026-09-21): this catalog is a module-load-time constant
+ * shared by every host (see this file's own module doc above), but a host can now override
+ * `uploadMedia`'s cap per-call via `MediaToolDeps.maxUploadBytes` (`tool-registrations.ts`). Stating
+ * `DEFAULT_MAX_UPLOAD_BYTES` (10 MiB) here would be an outright lie for a host that raised its own
+ * cap (e.g. Tovu's 50 MiB) — the model would be told a wrong, lower number than what the tool
+ * actually accepts. The description and schema below therefore describe the cap generically instead
+ * of stating a figure; the size-rejection error itself (`uploadMedia`'s `MediaValidationError`,
+ * `media-service.ts`) states the ACTUAL configured limit in MB, which is the one place that can be
+ * host-accurate.
  */
 export type AgentToolSideEffect = "none" | "mutates-durable-state" | "mints-token";
 export type AgentToolActorClassRule = "confirmer-must-equal-own-delegatedBy" | "user-only" | "none";

package/dist/media/agent-tools.js

@@ -34,11 +34,22 @@
  * content-types pass-through-`ToolPolicy` reasoning, not an oversight.
  *
  * Architectural role:
- * `media` domain declaration. Imports only the constants its own domain already enforces
- * (`DEFAULT_MAX_UPLOAD_BYTES`/`DEFAULT_ALLOWED_MIME_TYPES` from `media-service.ts`), so the
- * published JSON Schemas cannot drift from the validators.
+ * `media` domain declaration. Imports only the constant its own domain already enforces
+ * (`DEFAULT_ALLOWED_MIME_TYPES` from `media-service.ts`), so the published JSON Schema's allowed
+ * content types cannot drift from the validator.
+ *
+ * `media_upload_asset`'s size-cap wording (2026-09-21): this catalog is a module-load-time constant
+ * shared by every host (see this file's own module doc above), but a host can now override
+ * `uploadMedia`'s cap per-call via `MediaToolDeps.maxUploadBytes` (`tool-registrations.ts`). Stating
+ * `DEFAULT_MAX_UPLOAD_BYTES` (10 MiB) here would be an outright lie for a host that raised its own
+ * cap (e.g. Tovu's 50 MiB) — the model would be told a wrong, lower number than what the tool
+ * actually accepts. The description and schema below therefore describe the cap generically instead
+ * of stating a figure; the size-rejection error itself (`uploadMedia`'s `MediaValidationError`,
+ * `media-service.ts`) states the ACTUAL configured limit in MB, which is the one place that can be
+ * host-accurate.
  */
-import { DEFAULT_ALLOWED_MIME_TYPES, DEFAULT_MAX_UPLOAD_BYTES } from "./media-service.js";
+import { MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES } from "./html-attributes.js";
+import { DEFAULT_ALLOWED_MIME_TYPES } from "./media-service.js";
 const MEDIA_ID_SCHEMA = {
     type: "string",
     description: "The media asset's id, as returned by media_upload_asset or media_list_assets.",
@@ -54,7 +65,7 @@ const MEDIA_ID_SCHEMA = {
 export const mediaAgentToolCatalog = [
     {
         name: "media_list_assets",
-        description: "Lists every media asset in the workspace (all statuses — active and trashed), with id, title, alt, caption, credit, sha256, and status. Read-only. Call this to find a mediaId before updating or trashing an asset.",
+        description: "Lists every media asset in the workspace (all statuses — active and trashed), with id, slug, title, alt, caption, credit, sha256, and status. Read-only. Call this to find a mediaId before updating or trashing an asset.",
         sideEffects: "none",
         authorization: { permission: "media.read" },
         inputSchema: {
@@ -68,8 +79,9 @@ export const mediaAgentToolCatalog = [
         name: "media_upload_asset",
         description: `Uploads a new media asset from base64-encoded bytes. Rejects a content type outside the allowed set ` +
             `(${[...DEFAULT_ALLOWED_MIME_TYPES].join(", ")} — SVG is never accepted, even here: it requires a sanitizer ` +
-            `this build does not have) or a file over ${DEFAULT_MAX_UPLOAD_BYTES} bytes. Uploading the same bytes twice ` +
-            `always creates two separate library entries (the underlying blob is deduplicated, but each upload is its own asset).`,
+            `this build does not have) or a file over this host's configured size cap (a rejected upload's error ` +
+            `states the exact limit, in MB). Uploading the same bytes twice always creates two separate library ` +
+            `entries (the underlying blob is deduplicated, but each upload is its own asset).`,
         sideEffects: "mutates-durable-state",
         authorization: { permission: "media.upload" },
         inputSchema: {
@@ -86,7 +98,7 @@ export const mediaAgentToolCatalog = [
                 dataBase64: {
                     type: "string",
                     minLength: 1,
-                    description: `The file's bytes, base64-encoded. Decoded size must be over 0 and at most ${DEFAULT_MAX_UPLOAD_BYTES} bytes.`,
+                    description: "The file's bytes, base64-encoded. Decoded size must be over 0 bytes and within this host's configured upload size cap (a too-large upload's error states the exact limit, in MB).",
                 },
                 alt: { type: "string", description: "Optional accessibility alt text." },
                 caption: { type: "string", description: "Optional display caption." },
@@ -96,8 +108,11 @@ export const mediaAgentToolCatalog = [
     },
     {
         name: "media_update_metadata",
-        description: "Updates a media asset's editorial metadata (title/alt/caption/credit only). The asset's underlying bytes " +
-            "(sha256) are write-once and cannot be changed by this or any tool — to replace the file itself, upload a new asset.",
+        description: "Updates a media asset's metadata: title, alt, caption, credit, and its asset-wide presentation (cssClass, " +
+            "htmlAttributes). Omit a field to leave it unchanged. htmlAttributes/cssClass apply EVERYWHERE this asset " +
+            "renders; to change one placement on one page only, put the attribute on that page's data-embed-config " +
+            "marker element instead (pages_write_region). The bytes (sha256) are write-once and cannot be changed by " +
+            "this or any tool — to replace the file itself, upload a new asset.",
         sideEffects: "mutates-durable-state",
         authorization: { permission: "media.update" },
         inputSchema: {
@@ -110,6 +125,26 @@ export const mediaAgentToolCatalog = [
                 alt: { type: "string", description: "New alt text. Omit to leave unchanged." },
                 caption: { type: "string", description: "New caption. Omit to leave unchanged." },
                 credit: { type: "string", description: "New credit line. Omit to leave unchanged." },
+                slug: {
+                    type: "string",
+                    description: "New slug: lowercase letters, numbers and dashes, not UUID-shaped, unique in the workspace (a slug " +
+                        "another asset uses is refused and nothing is written). Changing it breaks any page marker that " +
+                        "references the OLD slug.",
+                },
+                cssClass: {
+                    type: "string",
+                    description: "Space-separated class names added to the rendered <img>/<video> tag everywhere this asset renders. " +
+                        "Replaces the stored value; empty string clears it.",
+                },
+                htmlAttributes: {
+                    type: "string",
+                    description: "Extra attributes for the rendered <img>/<video> tag, written as HTML attribute text, e.g. " +
+                        '`autoplay muted loop playsinline` or `loading="eager" data-motion="fade"`. REPLACES the whole ' +
+                        "stored value: read the current value first and keep what should stay. Empty string clears it. " +
+                        `Allowed names only: ${MEDIA_HTML_ATTRIBUTE_ALLOWED_NAMES.join(", ")}, plus any data-* or aria-*. ` +
+                        "Anything else (on* handlers, javascript: values, style, class) is rejected and NOTHING is written. " +
+                        "Browsers autoplay only video that is also muted (and playsinline on iPhone).",
+                },
             },
         },
     },