@jini-ai/cms 0.3.11 → 0.4.0

package/dist/core/commands/command.js

@@ -1,24 +1,27 @@
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
 /**
  * Thrown when a command's idempotency key was already used in the workspace.
  * Callers should re-read current state instead of retrying the mutation.
  */
 export class DuplicateCommandError extends Error {
     changeSetId;
-    constructor(message, changeSetId) {
+    constructor(requiredArgs, optionalArgs = {}) {
+        const { message, changeSetId } = requiredArgs;
         super(message);
         this.changeSetId = changeSetId;
     }
 }
 /**
- * Thrown when `authorize()` denies the caller. Routes map
- * this to 403 `FORBIDDEN`. Raised before the idempotency check (INV-04) — a
+ * Thrown when `authorize` denies the caller. Routes map
+ * this to 403 `FORBIDDEN`. Raised before the idempotency check — a
  * replayed command id from a denied caller therefore never produces
- * `DuplicateCommandError` either (EC-08).
+ * `DuplicateCommandError` either.
+ * See docs/decisions/DR-006-mutation-audit-atomicity.md.
  */
 export class ForbiddenError extends Error {
     permission;
     reason;
-    constructor(message, permission, reason) {
+    constructor({ message, permission, reason }, _optional = {}) {
         super(message);
         this.permission = permission;
         this.reason = reason;
@@ -47,26 +50,29 @@ function isIdempotencyKeyConflict(error) {
  * If execute throws, nothing is recorded; if inverse capture throws, the
  * mutation never runs.
  *
- * The feature mutation and its change-set record commit as one unit of work
- * (REQ-01): if `changeSets.insert` fails after `execute` has applied the
- * mutation, the gateway rolls the mutation back via `mutation.rollback` and
- * re-throws, so no change set and no outbox event survive (EC-08 / AC-17,
- * INV-01).
+ * With a working `mutation.rollback`, the feature mutation and its change-set
+ * record form one compensated unit of work : failures in version capture,
+ * record preparation or `changeSets.insert` after `execute` trigger rollback and
+ * rejection. When rollback is omitted, the gateway still
+ * rejects but cannot undo the applied feature mutation; a caller-owned outer
+ * transaction must supply atomicity. Record/event atomicity depends on the repo
+ * honoring its port contract.
  *
- * The `change-set.applied` event is passed as `changeSets.insert()`'s third argument, not a
- * separate `deps.outbox.enqueue()` call afterward — a durable adapter co-persists it inside the
+ * The `change-set.applied` event is passed in `changeSets.insert`'s optional object, not a
+ * separate `deps.outbox.enqueue` call afterward — a durable adapter co-persists it inside the
  * same transaction as the change-set record, so it can never land without a durable delivery
  * record (or vice versa). This still does NOT cover the domain mutation itself
- * (`mutation.execute()` stays outside any shared transaction, covered only by the compensating
+ * (`mutation.execute` stays outside any shared transaction, covered only by the compensating
  * rollback above), and it covers only this producer. See
  * `docs/decisions/change-set-outbox-transaction-boundary.md` for the full rationale, including the
- * other direct `OutboxPort.enqueue()` producers this decision deliberately leaves untouched.
+ * other direct `OutboxPort.enqueue` producers this decision deliberately leaves untouched.
+ * See docs/decisions/DR-006-mutation-audit-atomicity.md.
  */
 export async function executeCommand(required, _optional = {}) {
     const { deps, command, mutation } = required;
     // authorize() runs BEFORE the idempotency check, so
     // a denied caller never learns whether a replayed command id previously
-    // succeeded (no DUPLICATE_COMMAND / changeSetId leak, EC-08). `permission`
+    // succeeded (no DUPLICATE_COMMAND / changeSetId leak). `permission`. See docs/decisions/DR-006-mutation-audit-atomicity.md.
     // and `authorize` are wired together or not at all (see ExecuteCommandDeps
     // doc) — partial wiring is a programming error, not a silent allow/skip.
     if (Boolean(deps.authorize) !== Boolean(command.permission)) {
@@ -82,7 +88,7 @@ export async function executeCommand(required, _optional = {}) {
             entityId: mutation.entityId,
         });
         if (!authResult.allowed) {
-            throw new ForbiddenError(`principal '${command.actor.id}' is not authorized for '${command.permission}' (${authResult.reason})`, command.permission, authResult.reason);
+            throw new ForbiddenError({ message: `principal '${command.actor.id}' is not authorized for '${command.permission}' (${authResult.reason})`, permission: command.permission, reason: authResult.reason });
         }
     }
     if (command.idempotencyKey) {
@@ -91,63 +97,68 @@ export async function executeCommand(required, _optional = {}) {
             idempotencyKey: command.idempotencyKey,
         });
         if (existing) {
-            throw new DuplicateCommandError(`command with idempotency key '${command.idempotencyKey}' was already executed`, existing.id);
+            throw new DuplicateCommandError({ message: `command with idempotency key '${command.idempotencyKey}' was already executed`, changeSetId: existing.id });
         }
     }
     const inversePayload = await mutation.captureInverse();
     const result = await mutation.execute();
-    const entityVersionAtApply = mutation.captureEntityVersion?.(result) ?? undefined;
-    const now = deps.clock.nowIso();
-    const changeSetId = deps.idGen.newId();
-    // BR-04: the event rides into insert()'s third argument (see this function's doc comment) so a
-    // durable adapter co-persists it atomically with the record it belongs to. Built unconditionally
-    // (cheap, pure data) but only passed through when an outbox is actually wired.
-    const event = {
-        id: deps.idGen.newId(),
-        name: "change-set.applied",
-        occurredAt: now,
-        aggregateId: changeSetId,
-        workspaceId: command.workspaceId,
-        actorId: command.actor.id,
-        changeSetId,
-        payload: {
-            changeSetId,
-            entityType: mutation.entityType,
-            entityId: mutation.entityId,
-        },
-    };
-    // Unit of work: the change-set record (and, when an outbox is wired, its delivery event) must
-    // land together, or the feature mutation is rolled back (REQ-01 / EC-08). On the in-memory
-    // adapter this is a compensating restore via `mutation.rollback`; the SQLite adapter does this
-    // as one real transaction and the rollback becomes a no-op for this step.
+    let insertingRecord = false;
     try {
-        await deps.changeSets.insert({
-            id: changeSetId,
+        const entityVersionAtApply = mutation.captureEntityVersion?.({ result }) ?? undefined;
+        const now = kernelNowIso({ clock: deps.clock });
+        const changeSetId = deps.idGen.newId();
+        // the event rides into insert's optional object (see this function's doc comment) so a. See docs/decisions/DR-006-mutation-audit-atomicity.md.
+        // durable adapter co-persists it atomically with the record it belongs to. Built unconditionally
+        // (cheap, pure data) but only passed through when an outbox is actually wired.
+        const event = {
+            id: deps.idGen.newId(),
+            name: "change-set.applied",
+            occurredAt: now,
+            aggregateId: changeSetId,
             workspaceId: command.workspaceId,
             actorId: command.actor.id,
-            status: "applied",
-            summary: command.summary,
-            idempotencyKey: command.idempotencyKey,
-            intentRef: command.intentRef,
-            createdAt: now,
-            appliedAt: now,
-        }, [
-            {
-                id: deps.idGen.newId(),
+            changeSetId,
+            payload: {
                 changeSetId,
                 entityType: mutation.entityType,
                 entityId: mutation.entityId,
-                operation: mutation.operation,
-                inversePayload: inversePayload ?? undefined,
-                entityVersionAtApply,
-                position: 0,
             },
-        ], deps.outbox ? event : undefined);
+        };
+        // Unit of work: the change-set record (and, when an outbox is wired, its delivery event) must
+        // land together, or the feature mutation is rolled back. On the in-memory. See docs/decisions/DR-006-mutation-audit-atomicity.md.
+        // adapter this is a compensating restore via `mutation.rollback`; a caller-owned transaction
+        // can instead cover the feature mutation and record together (see the rollback contract).
+        const itemId = deps.idGen.newId();
+        insertingRecord = true;
+        await deps.changeSets.insert({ record: {
+                id: changeSetId,
+                workspaceId: command.workspaceId,
+                actorId: command.actor.id,
+                status: "applied",
+                summary: command.summary,
+                idempotencyKey: command.idempotencyKey,
+                intentRef: command.intentRef,
+                createdAt: now,
+                appliedAt: now,
+            },
+            items: [
+                {
+                    id: itemId,
+                    changeSetId,
+                    entityType: mutation.entityType,
+                    entityId: mutation.entityId,
+                    operation: mutation.operation,
+                    inversePayload: inversePayload ?? undefined,
+                    entityVersionAtApply,
+                    position: 0,
+                },
+            ] }, { event: deps.outbox ? event : undefined });
+        return { result, changeSetId };
     }
     catch (recordError) {
-        // AC-17 / EC-08: the mutation applied but its record did not. Undo the
-        // mutation so INV-01 holds (no mutation without a record). We surface the
-        // original persist error; a rollback that itself throws is a harder failure
+        // the mutation applied but its record did not. Undo the. See docs/decisions/DR-006-mutation-audit-atomicity.md.
+        // mutation so holds when rollback is supplied (no mutation without a record). See docs/decisions/DR-006-mutation-audit-atomicity.md.
+        // We surface the original preparation/persist error; a rollback that itself throws is a harder failure
         // that the SQLite transaction path is designed to remove.
         await mutation.rollback?.();
         // TOCTOU: the idempotency check above and this insert are separated by
@@ -157,17 +168,16 @@ export async function executeCommand(required, _optional = {}) {
         // change set) rather than letting the raw driver error escape, so callers' existing
         // `instanceof DuplicateCommandError` handling (409) catches this race the same as the
         // already-covered non-racing replay.
-        if (command.idempotencyKey && isIdempotencyKeyConflict(recordError)) {
+        if (insertingRecord && command.idempotencyKey && isIdempotencyKeyConflict(recordError)) {
             const winner = await deps.changeSets.findByIdempotencyKey({
                 workspaceId: command.workspaceId,
                 idempotencyKey: command.idempotencyKey,
             });
             if (winner) {
-                throw new DuplicateCommandError(`command with idempotency key '${command.idempotencyKey}' was already executed`, winner.id);
+                throw new DuplicateCommandError({ message: `command with idempotency key '${command.idempotencyKey}' was already executed`, changeSetId: winner.id });
             }
         }
         throw recordError;
     }
-    return { result, changeSetId };
 }
 //# sourceMappingURL=command.js.map

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

@@ -1,6 +1,6 @@
 import { ToolInputError } from "@jini-ai/core";
 /**
- * @file The write-side counterpart to `not-trashed.ts`'s read-side `notTrashed()` filter (Tovu
+ * @file The write-side counterpart to `not-trashed.ts`'s read-side `notTrashed()` filter (host
  * `features/trash/not-trashed.ts`).
  *
  * Purpose:
@@ -11,13 +11,13 @@ import { ToolInputError } from "@jini-ai/core";
  * 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
+ * Why it lives in `@jini-ai/cms/core` rather than in a host module or a Jini domain package:
+ * a host's writers (pages, SEO, redirects) and Jini's own domain writers (media, content-types,
+ * taxonomy) both need it, Jini cannot import anything a host 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
+ * executor already treats `ToolInputError` as caller-facing (see the kernel registration kit'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`
@@ -36,11 +36,15 @@ export type EntityLiveness = "live" | "trashed" | "tombstoned";
  * the instance so a caller that wants to branch on them (rather than parse the message) can.
  */
 export declare class EntityNotLiveError extends ToolInputError {
+    readonly code: "ENTITY_IN_TRASH" | "ENTITY_TOMBSTONED";
     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");
+    constructor(requiredArgs: {
+        entityType: string;
+        entityId: string;
+        state: "trashed" | "tombstoned";
+    }, _optionalArgs?: Record<string, never>);
 }
 /**
  * Throws {@link EntityNotLiveError} unless `required.state` is `"live"`. Call this immediately

package/dist/core/entity-liveness.js

@@ -5,12 +5,13 @@ import { ToolInputError } from "@jini-ai/core";
  * the instance so a caller that wants to branch on them (rather than parse the message) can.
  */
 export class EntityNotLiveError extends ToolInputError {
+    code;
     entityType;
     entityId;
     state;
-    code;
-    constructor(entityType, entityId, state) {
-        super(buildEntityNotLiveMessage(entityType, entityId, state));
+    constructor(requiredArgs, _optionalArgs = {}) {
+        const { entityType, entityId, state } = requiredArgs;
+        super({ message: buildEntityNotLiveMessage(entityType, entityId, state) });
         this.entityType = entityType;
         this.entityId = entityId;
         this.state = state;
@@ -33,6 +34,6 @@ function buildEntityNotLiveMessage(entityType, entityId, state) {
 export function assertEntityLive(required) {
     if (required.state === "live")
         return;
-    throw new EntityNotLiveError(required.entityType, required.entityId, required.state);
+    throw new EntityNotLiveError({ entityType: required.entityType, entityId: required.entityId, state: required.state });
 }
 //# sourceMappingURL=entity-liveness.js.map

package/dist/core/index.d.ts

@@ -8,10 +8,16 @@
  * kit every domain's agent-tool layer builds on. No Express, no `node:*`, no DOM, no concrete
  * adapters.
  *
- * ## What belongs in `../server`
+ * ## What belongs in Node-bound domain entries
  *
  * Only the Node-bound half: concrete repository implementations (SQLite/Postgres), filesystem blob
- * stores, and anything importing `node:*`.
+ * stores, image transformers, and anything importing `node:*` or a native dependency. These
+ * adapters depend on core; the reverse is a boundary violation. User-management tool registration
+ * composition belongs to its own server entry point.
+ *
+ * HTTP routing and request/response handling belong in domain HTTP entries, composed through
+ * `@jini-ai/http-kit` and `@jini-ai/server`. The source runtime's Express composition root stays
+ * out of this kernel: putting its routes here would reproduce the coupling described below.
  *
  * ## Why the split is drawn here, and why it is enforced by `exports` rather than convention
  *
@@ -26,7 +32,7 @@
  * A package's `exports` map is exactly the enforcement a single `src/` tree cannot provide: a
  * consumer of `@jini-ai/cms/core` physically cannot reach a Node adapter, and `/core` physically
  * cannot import a transport type, because the module resolver refuses it. Keep it that way — if a
- * core module wants something from `/server`, the dependency is pointing the wrong way and the fix
+ * core module wants something from a Node-bound adapter, the dependency points the wrong way and the fix
  * is a port (interface) in core, not a widened export.
  *
  * ## Why the barrel does not re-export `./commands/appliers`
@@ -38,9 +44,10 @@
  * measured reason no domain could be extracted on its own. A per-entity applier registry belongs
  * behind a registration call the host makes, not behind a kernel barrel.
  */
-export type { UUID, ISODateTime, JsonPrimitive, JsonValue, JsonObject, JsonArray, DomainEvent, EventBusPort, OutboxRecord, OutboxPort, ClockPort, IdGeneratorPort, } from './ports.js';
+export type { DomainEvent, EventBusPort, OutboxRecord, OutboxPort, } 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';
+export * from './tools/args.js';
+export type { AuthorizationPort, AuthorizationRequired, AuthorizationOptional } from './authorization.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -8,10 +8,16 @@
  * kit every domain's agent-tool layer builds on. No Express, no `node:*`, no DOM, no concrete
  * adapters.
  *
- * ## What belongs in `../server`
+ * ## What belongs in Node-bound domain entries
  *
  * Only the Node-bound half: concrete repository implementations (SQLite/Postgres), filesystem blob
- * stores, and anything importing `node:*`.
+ * stores, image transformers, and anything importing `node:*` or a native dependency. These
+ * adapters depend on core; the reverse is a boundary violation. User-management tool registration
+ * composition belongs to its own server entry point.
+ *
+ * HTTP routing and request/response handling belong in domain HTTP entries, composed through
+ * `@jini-ai/http-kit` and `@jini-ai/server`. The source runtime's Express composition root stays
+ * out of this kernel: putting its routes here would reproduce the coupling described below.
  *
  * ## Why the split is drawn here, and why it is enforced by `exports` rather than convention
  *
@@ -26,7 +32,7 @@
  * A package's `exports` map is exactly the enforcement a single `src/` tree cannot provide: a
  * consumer of `@jini-ai/cms/core` physically cannot reach a Node adapter, and `/core` physically
  * cannot import a transport type, because the module resolver refuses it. Keep it that way — if a
- * core module wants something from `/server`, the dependency is pointing the wrong way and the fix
+ * core module wants something from a Node-bound adapter, the dependency points the wrong way and the fix
  * is a port (interface) in core, not a widened export.
  *
  * ## Why the barrel does not re-export `./commands/appliers`
@@ -40,5 +46,5 @@
  */
 export * from './commands/command.js';
 export * from './entity-liveness.js';
-export * from './tools/registration-kit.js';
+export * from './tools/args.js';
 //# sourceMappingURL=index.js.map

package/dist/core/ports.d.ts

@@ -21,14 +21,7 @@
  * Core/domain code depends on interfaces from this file only, never on concrete
  * infrastructure SDKs or framework-specific implementations.
  */
-export type UUID = string;
-export type ISODateTime = string;
-export type JsonPrimitive = string | number | boolean | null;
-export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
-export interface JsonObject {
-    [key: string]: JsonValue;
-}
-export type JsonArray = JsonValue[];
+import type { UUID, ISODateTime } from "@jini-ai/core/primitives";
 /**
  * Immutable domain event emitted by synchronous command handlers and delivered
  * asynchronously via the outbox pipeline.
@@ -73,19 +66,26 @@ export interface EventBusPort {
     /** Publish a single event to subscribers. */
     publish<TPayload>(event: DomainEvent<TPayload>): Promise<void>;
     /** Publish multiple events in order. */
-    publishBatch<TPayload>(events: Array<DomainEvent<TPayload>>): Promise<void>;
+    publishBatch<TPayload>(required: {
+        events: Array<DomainEvent<TPayload>>;
+    }, optional?: Record<string, never>): Promise<void>;
     /**
      * Subscribe a handler to an event name.
      * Returns an async unsubscriber function.
      */
-    subscribe<TPayload>(eventName: string, handler: (event: DomainEvent<TPayload>) => Promise<void>): Promise<() => Promise<void>>;
+    subscribe<TPayload>(required: {
+        eventName: string;
+        handler: (event: DomainEvent<TPayload>) => Promise<void>;
+    }, optional?: Record<string, never>): Promise<() => Promise<void>>;
     /**
      * Subscribe a handler to every event published on this bus, regardless of name. Additive to
      * `subscribe` — existing per-name callers are unaffected.
      * The Integrations fan-out (`registerWebhookFanout`) is the first real consumer: it narrows
      * by topic itself rather than requiring a fixed list of event names up front.
      */
-    subscribeAll(handler: (event: DomainEvent) => Promise<void>): Promise<() => Promise<void>>;
+    subscribeAll(required: {
+        handler: (event: DomainEvent) => Promise<void>;
+    }, optional?: Record<string, never>): Promise<() => Promise<void>>;
 }
 /**
  * Persisted outbox row used for reliable async event delivery.
@@ -120,9 +120,14 @@ export interface OutboxPort {
     /** Append an event for later delivery. */
     enqueue(event: DomainEvent): Promise<void>;
     /** Claim pending rows for processing. */
-    claimPending(batchSize: number, nowIso: ISODateTime): Promise<OutboxRecord[]>;
+    claimPending(required: {
+        batchSize: number;
+        nowIso: ISODateTime;
+    }, optional?: Record<string, never>): Promise<OutboxRecord[]>;
     /** Mark a row as delivered. */
-    markDelivered(id: UUID): Promise<void>;
+    markDelivered(required: {
+        id: UUID;
+    }, optional?: Record<string, never>): Promise<void>;
     /**
      * Mark a row as failed and set its next retry time.
      *
@@ -134,16 +139,12 @@ export interface OutboxPort {
      * is terminal — `claimPending` only ever selects `"pending"` rows, so a `"failed"` row is
      * permanently excluded from retry regardless of `nextAttemptAt`.
      */
-    markFailed(id: UUID, error: string, nextAttemptAt: ISODateTime, nextStatus: Extract<OutboxRecord["status"], "pending" | "failed">): Promise<void>;
-}
-/** Clock abstraction to make time deterministic in tests. */
-export interface ClockPort {
-    /** Current wall-clock time as ISO string. */
-    nowIso(): ISODateTime;
-}
-/** ID generator abstraction to keep ID strategy swappable and testable. */
-export interface IdGeneratorPort {
-    /** Create a new globally unique ID. */
-    newId(): UUID;
+    markFailed(required: {
+        id: UUID;
+        error: string;
+        nextAttemptAt: ISODateTime;
+        nextStatus: Extract<OutboxRecord["status"], "pending" | "failed">;
+    }, optional?: Record<string, never>): Promise<void>;
 }
+/** Clock and ID generator contracts are owned by the shared kernel primitives. */
 //# sourceMappingURL=ports.d.ts.map

package/dist/core/ports.js

@@ -1,2 +1,3 @@
 export {};
+/** Clock and ID generator contracts are owned by the shared kernel primitives. */
 //# sourceMappingURL=ports.js.map

package/dist/core/tools/args.d.ts

@@ -0,0 +1,49 @@
+/** CMS permission checking preserves the CMS command denial contract. Generic registration wiring lives in the kernel. */
+import { type AuthorizeFn } from "../commands/command.js";
+import type { AuthorizationPort } from "../authorization.js";
+export type { AuthorizationPort, AuthorizationRequired, AuthorizationOptional } from "../authorization.js";
+export interface RequireToolPermissionRequired {
+    authorize: AuthorizationPort;
+    workspaceId: string;
+    principalId: string;
+    permission: string;
+}
+export interface RequireToolPermissionOptional {
+    entityType?: string | undefined;
+    entityId?: string | undefined;
+}
+/**
+ * Runs the identical inline `authorize()` check the corresponding admin HTTP route performs, for a
+ * tool whose own domain function carries no `authorize()` call to inherit.
+ *
+ * This is NOT a second evaluator alongside another check — that is exactly the single-evaluator
+ * rule's concern. For each tool that
+ * calls it, this IS the only gate that tool's execution ever reaches, reached by an identical path
+ * to the one a human clicking the same admin route reaches. Domains split cleanly on which kind
+ * they are: content-types/Forms/Identity mutations and every Widgets write-service call self-enforce
+ * inside the domain function and must NOT call this; Comments/Members/Newsletter/Media/Menus/
+ * Database/Recovery gate in the route instead, so their handlers call this in the route's place.
+ * Which kind a given tool is stays documented next to that tool's handler, not here.
+ *
+ * Throws `core/commands`'s `ForbiddenError` — the same class `executeCommand` itself throws — so a
+ * tool caller and a route caller see the identical error shape for an identical denial. Throw
+ * rather than a 403 body because the caller here is `ToolExecutor`, which reads a thrown error as a
+ * failed execution and has no response to write to.
+ *
+ * Import the defining command module directly: its barrel also exports mutation appliers that
+ * name content features. Pulling that barrel into shared permission wiring would couple every
+ * tool domain to those features; the direct import preserves the identical denial class without
+ * that dependency closure.
+ *
+ * @param required - The `authorize()` evaluator and the workspace the run is scoped to.
+ * @param optional - Entity scope for who is asking, for what permission, optionally against which entity.
+ * @throws {ForbiddenError} If `authorize()` denies.
+ * @complexity O(1) beyond the injected `authorize()` call.
+ * @overallScore 100
+ */
+export declare function requireToolPermission(required: RequireToolPermissionRequired, optional?: RequireToolPermissionOptional): Promise<void>;
+/** Adapt an existing evaluator without losing entity scope. @complexity O(1) plus evaluation. */
+export declare function adaptLegacyAuthorize(required: {
+    authorize: AuthorizeFn;
+}, _optional?: Record<string, never>): AuthorizationPort;
+//# sourceMappingURL=args.d.ts.map

package/dist/core/tools/args.js

@@ -0,0 +1,46 @@
+/** CMS permission checking preserves the CMS command denial contract. Generic registration wiring lives in the kernel. */
+import { ForbiddenError } from "../commands/command.js";
+/**
+ * Runs the identical inline `authorize()` check the corresponding admin HTTP route performs, for a
+ * tool whose own domain function carries no `authorize()` call to inherit.
+ *
+ * This is NOT a second evaluator alongside another check — that is exactly the single-evaluator
+ * rule's concern. For each tool that
+ * calls it, this IS the only gate that tool's execution ever reaches, reached by an identical path
+ * to the one a human clicking the same admin route reaches. Domains split cleanly on which kind
+ * they are: content-types/Forms/Identity mutations and every Widgets write-service call self-enforce
+ * inside the domain function and must NOT call this; Comments/Members/Newsletter/Media/Menus/
+ * Database/Recovery gate in the route instead, so their handlers call this in the route's place.
+ * Which kind a given tool is stays documented next to that tool's handler, not here.
+ *
+ * Throws `core/commands`'s `ForbiddenError` — the same class `executeCommand` itself throws — so a
+ * tool caller and a route caller see the identical error shape for an identical denial. Throw
+ * rather than a 403 body because the caller here is `ToolExecutor`, which reads a thrown error as a
+ * failed execution and has no response to write to.
+ *
+ * Import the defining command module directly: its barrel also exports mutation appliers that
+ * name content features. Pulling that barrel into shared permission wiring would couple every
+ * tool domain to those features; the direct import preserves the identical denial class without
+ * that dependency closure.
+ *
+ * @param required - The `authorize()` evaluator and the workspace the run is scoped to.
+ * @param optional - Entity scope for who is asking, for what permission, optionally against which entity.
+ * @throws {ForbiddenError} If `authorize()` denies.
+ * @complexity O(1) beyond the injected `authorize()` call.
+ * @overallScore 100
+ */
+export async function requireToolPermission(required, optional = {}) {
+    const result = await required.authorize({
+        principalId: required.principalId, permission: required.permission, workspaceId: required.workspaceId,
+    }, optional);
+    if (!result.allowed)
+        throw new ForbiddenError({
+            message: `principal '${required.principalId}' is not authorized for '${required.permission}' (${result.reason})`,
+            permission: required.permission, reason: result.reason,
+        });
+}
+/** Adapt an existing evaluator without losing entity scope. @complexity O(1) plus evaluation. */
+export function adaptLegacyAuthorize(required, _optional = {}) {
+    return (request, optional = {}) => required.authorize({ ...request, ...optional });
+}
+//# sourceMappingURL=args.js.map

package/dist/core/tools/index.d.ts

@@ -0,0 +1,3 @@
+/** CMS authorization helpers; generic tool-registration wiring is exported by the kernel. */
+export * from './args.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/tools/index.js

@@ -0,0 +1,3 @@
+/** CMS authorization helpers; generic tool-registration wiring is exported by the kernel. */
+export * from './args.js';
+//# sourceMappingURL=index.js.map

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

@@ -1,76 +1,4 @@
-/**
- * @file The Entries agent-tool catalog — this domain's instance of the per-domain `agent-tools.ts`
- * convention `features/content-types/agent-tools.ts`, `features/settings/agent-tools.ts`, and every
- * other domain catalog already use.
- *
- * Purpose:
- * A static, in-process catalog describing every agent-callable tool this domain exposes. Every
- * entry maps 1:1 onto a real exported function of `features/entries/write-service.ts` (`createEntry`,
- * `updateEntry`, `publishEntry`, `unpublishEntry`) or `features/entries/list.ts` (`listEntries`) —
- * this catalog never names an operation the domain cannot perform.
- *
- * Naming and scope — a real discrepancy from this dispatch's own brief, disclosed rather than
- * silently reconciled: the brief framed this domain as "backing the Pages, Posts, and Collections
- * admin sections", but reading the actual admin routes shows that is only true for Collections.
- * `server/routes/admin/entries/{create,update,lifecycle,list}.ts` (`/api/admin/v1/entries`, gated by
- * `admin.collections.manage`/`admin.collections.read`) are the ONLY routes backed by THIS package's
- * `write-service.ts`/`list.ts` — exactly what this catalog wraps. Pages and Posts
- * (`server/routes/admin/pages/*`, `server/routes/admin/posts/*`) are, in this codebase's CURRENT
- * state, backed by a wholly separate legacy `features/post` module (`createPost`/`updatePost`/
- * `getAdminPostById`/`listAdminPages`, its own `post` table, routed through `core/commands`'s
- * `executeCommand` gateway, gated by `content.write`/`content.read` — a different permission
- * namespace entirely). `features/entries` has no relationship to that module at all: no shared
- * table, no shared write chokepoint, no shared permission. So this catalog's tools name their
- * resource `collections_entry_*` (pairing with `features/content-types/agent-tools.ts`'s own
- * `collections_content_type_*` prefix — the two packages are "one cohesive domain" per
- * `server/routes/admin/content-types/deps.ts`'s own file header), not `entry_*`/`page_*`/`post_*` —
- * a name that could be misread as covering Pages/Posts. Wiring Pages/Posts agent tools would mean
- * wrapping `features/post`, a different backend this dispatch was not asked to touch and has not
- * inspected for the same safety discipline this catalog applies here.
- *
- * Deliberate absences (the point of a catalog, not an oversight):
- * - There is no delete/purge tool: `write-service.ts` exposes no delete function at all (confirmed
- *   by reading the whole file) — there is nothing to wrap or exclude on that front.
- * - `collections_entry_update`'s schema omits `bodyJson` even though `updateEntry` itself accepts an
- *   optional `bodyJson` (REQ-44/45, used internally by `widgets/embed-service.ts`'s own guardrailed
- *   mutation path). The generic Collections admin route (`entries/update.ts`) never forwards
- *   `body.bodyJson` at all — only `title`/`fieldsJson`/`expectedVersion` — so exposing it here would
- *   invent capability beyond what the human admin UI's own Collections editor exposes. Omitting it
- *   from the input is enough: `updateEntry` leaves `bodyJson` unchanged whenever the field is
- *   `undefined`, so this exclusion changes nothing about what a call can still do.
- * - `collections_entry_list`'s schema omits `status`/`orderBy`/`limit` even though
- *   `EntryListPort.listByWorkspace` supports all three (added for `widgets/resolvers/recent-entries.ts`'s
- *   own bounded-query need) — `server/routes/admin/entries/list.ts` only ever forwards `type` from
- *   its query string, so the other three are not part of what the Collections admin list screen
- *   itself can do; adding them here would again exceed the human surface this catalog mirrors.
- *
- * What IS included, and why it is safe: all four write-service functions are `admin.collections.*`
- * self-enforcing (each opens with its own `deps.authorize()` call before any other side effect —
- * confirmed by reading `write-service.ts` directly), and `publishEntry`/`unpublishEntry` are ordinary,
- * fully reversible status flips with a full revision trail (`entryRepo.appendRevision`) — publishing
- * and unpublishing are each other's own undo.
- *
- * How it relates to the project:
- * `features/entries/tool-registrations.ts` maps these entries into `@jini-ai/core` `ToolRegistration`s.
- *
- * Architectural role:
- * `features/entries` domain declaration. No dependencies.
- */
-export type AgentToolSideEffect = "none" | "mutates-durable-state" | "mints-token";
-export interface AgentToolDefinition {
-    name: string;
-    description: string;
-    sideEffects: AgentToolSideEffect;
-    authorization: {
-        permission: string;
-    };
-    /**
-     * 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).
-     */
-    inputSchema?: Readonly<Record<string, unknown>>;
-}
+import type { AgentToolDefinition } from "@jini-ai/core";
 /** The Entries domain's fixed agent-tool catalog: the Collections authoring surface's 4 writes
  * (create/update/publish/unpublish) plus its 1 read (list) — see this file's header for the
  * Pages/Posts naming disclosure and the 3 deliberate scope exclusions. */