@jini-ai/core 0.3.1 → 0.4.1

package/dist/api-token-auth.js

@@ -4,27 +4,27 @@
  * Whether a bearer-style API token gate should be enforced, and what the
  * expected token value is. Generalized from an upstream flat daemon module:
  * the origin hardcoded its host product's env-var names, now fields on
- * {@link ApiTokenAuthEnvConfig} — see `source-map.md` for the exact mapping.
+ * {@link ApiTokenAuthEnvConfig} — see `archived provenance ledger` for the exact mapping.
  */
 /**
  * Interprets `value` as a truthy flag: `'1'`, `'true'`, `'yes'`, or `'on'`
  * (case-insensitive, trimmed). Anything else, including `undefined`, is
  * falsy.
  */
-export function isTruthyEnvFlag(value) {
+export function isTruthyEnvFlag({ value }) {
     const normalized = String(value || '').trim().toLowerCase();
     return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
 }
 /** Whether the API auth gate has been explicitly force-disabled. */
-export function isApiAuthDisabled(config, env = process.env) {
-    return isTruthyEnvFlag(env[config.disableEnvVar]);
+export function isApiAuthDisabled({ config, env }) {
+    return isTruthyEnvFlag({ value: env[config.disableEnvVar] });
 }
 /** The configured expected token value, trimmed; `''` when unset. */
-export function apiTokenFromEnv(config, env = process.env) {
+export function apiTokenFromEnv({ config, env }) {
     return (env[config.tokenEnvVar] ?? '').trim();
 }
 /** Whether the token gate should actually run: a token is configured and it hasn't been disabled. */
-export function isApiTokenMiddlewareEnabled(config, env = process.env) {
-    return apiTokenFromEnv(config, env).length > 0 && !isApiAuthDisabled(config, env);
+export function isApiTokenMiddlewareEnabled({ config, env }) {
+    return apiTokenFromEnv({ config, env }).length > 0 && !isApiAuthDisabled({ config, env });
 }
 //# sourceMappingURL=api-token-auth.js.map

package/dist/bindings.d.ts

@@ -5,14 +5,25 @@ import type { ManyToken, Token } from './token.js';
  * `Exclude<RequiredTokenIds<Packs>, BoundIds>` at compile time (see daemon.ts).
  */
 export declare class Bindings<BoundIds extends string = never> {
+    constructor(_required: Record<string, never>);
     private readonly one;
     private readonly many;
-    bind<T, Id extends string>(t: Token<T, Id>, impl: T): Bindings<BoundIds | Id>;
-    bindMany<T, Id extends string>(t: ManyToken<T, Id>, impl: T): Bindings<BoundIds | Id>;
+    bind<T, Id extends string>({ token: t, impl }: {
+        token: Token<T, Id>;
+        impl: T;
+    }): Bindings<BoundIds | Id>;
+    bindMany<T, Id extends string>({ token: t, impl }: {
+        token: ManyToken<T, Id>;
+        impl: T;
+    }): Bindings<BoundIds | Id>;
     /** @internal */
-    resolveOne<T>(t: Token<T, string>): T;
+    resolveOne<T>({ token: t }: {
+        token: Token<T, string>;
+    }): T;
     /** @internal */
-    resolveMany<T>(t: ManyToken<T, string>): T[];
+    resolveMany<T>({ token: t }: {
+        token: ManyToken<T, string>;
+    }): T[];
 }
-export declare function bindings(): Bindings<never>;
+export declare function bindings(required: Record<string, never>): Bindings<never>;
 //# sourceMappingURL=bindings.d.ts.map

package/dist/bindings.js

@@ -4,23 +4,24 @@
  * `Exclude<RequiredTokenIds<Packs>, BoundIds>` at compile time (see daemon.ts).
  */
 export class Bindings {
+    constructor(_required) { }
     one = new Map();
     many = new Map();
-    bind(t, impl) {
+    bind({ token: t, impl }) {
         if (this.one.has(t.id)) {
             throw new Error(`duplicate binding: ${t.id} is already bound (a singleton token accepts exactly one binding)`);
         }
         this.one.set(t.id, { value: impl, version: t.version });
         return this;
     }
-    bindMany(t, impl) {
+    bindMany({ token: t, impl }) {
         const list = this.many.get(t.id) ?? [];
         list.push(impl);
         this.many.set(t.id, list);
         return this;
     }
     /** @internal */
-    resolveOne(t) {
+    resolveOne({ token: t }) {
         const entry = this.one.get(t.id);
         if (!entry) {
             throw new Error(`missing binding: ${t.id}`);
@@ -31,11 +32,11 @@ export class Bindings {
         return entry.value;
     }
     /** @internal */
-    resolveMany(t) {
+    resolveMany({ token: t }) {
         return (this.many.get(t.id) ?? []);
     }
 }
-export function bindings() {
-    return new Bindings();
+export function bindings(required) {
+    return new Bindings(required);
 }
 //# sourceMappingURL=bindings.js.map

package/dist/{internal.d.ts → composition.d.ts}

@@ -1,9 +1,9 @@
 /**
- * @module @jini-ai/core/internal
+ * @module @jini-ai/core/composition
  *
- * Package-internal entry point — NOT part of `@jini-ai/core`'s public
- * contract. Two unrelated escape hatches live here, each for its own
- * single intended consumer:
+ * Composition boundary for daemon assembly and authorized tool invocation.
+ * These capabilities stay off the root entry point; each has its own
+ * intended consumer:
  *
  * - {@link authorizeToolInvocation} so `@jini-ai/daemon`'s `ToolExecutor` can
  *   resolve a registered tool and run its authorization gate — the tool's
@@ -24,18 +24,18 @@
  *
  * **Correction (2026-07-19 hardening pass):** a package.json `exports` map
  * subpath is NOT a language-level or per-consumer access modifier — Node's
- * module resolution will happily resolve `@jini-ai/core/internal` for *any*
+ * module resolution will happily resolve `@jini-ai/core/composition` for *any*
  * package that depends on `@jini-ai/core`, not just the intended consumer.
  * Earlier revisions of this doc comment claimed this boundary was
  * "enforced" by the exports map; that was inaccurate and left the leak
  * undetected. The actual enforcement is `scripts/check-engine-boundaries.ts`'s
- * rule forbidding any *value* import from `@jini-ai/core/internal` outside
+ * R6-internal-leak rule forbidding any *value* import from `@jini-ai/core/composition` outside
  * `packages/daemon/**` (type-only imports of the DI-token-derivation types
- * remain unrestricted, since they carry no runtime capability) — that guard
- * is wired in, but is a second, independent layer on top of the 2026-07-29
+ * remain unrestricted, since they carry no runtime capability). R6 checks this
+ * exact composition specifier as a second, independent layer on top of the 2026-07-29
  * structural fix above, not a substitute for it.
  */
 export { authorizeToolInvocation } from './tool-registry.js';
 export type { ToolAuthorizationDelegate, ToolInvocationAuthorization } from './tool-registry.js';
 export type { AnyPack, MissingTokenIds, RequiredTokenIds } from './daemon.js';
-//# sourceMappingURL=internal.d.ts.map
+//# sourceMappingURL=composition.d.ts.map

package/dist/{internal.js → composition.js}

@@ -1,9 +1,9 @@
 /**
- * @module @jini-ai/core/internal
+ * @module @jini-ai/core/composition
  *
- * Package-internal entry point — NOT part of `@jini-ai/core`'s public
- * contract. Two unrelated escape hatches live here, each for its own
- * single intended consumer:
+ * Composition boundary for daemon assembly and authorized tool invocation.
+ * These capabilities stay off the root entry point; each has its own
+ * intended consumer:
  *
  * - {@link authorizeToolInvocation} so `@jini-ai/daemon`'s `ToolExecutor` can
  *   resolve a registered tool and run its authorization gate — the tool's
@@ -24,16 +24,16 @@
  *
  * **Correction (2026-07-19 hardening pass):** a package.json `exports` map
  * subpath is NOT a language-level or per-consumer access modifier — Node's
- * module resolution will happily resolve `@jini-ai/core/internal` for *any*
+ * module resolution will happily resolve `@jini-ai/core/composition` for *any*
  * package that depends on `@jini-ai/core`, not just the intended consumer.
  * Earlier revisions of this doc comment claimed this boundary was
  * "enforced" by the exports map; that was inaccurate and left the leak
  * undetected. The actual enforcement is `scripts/check-engine-boundaries.ts`'s
- * rule forbidding any *value* import from `@jini-ai/core/internal` outside
+ * R6-internal-leak rule forbidding any *value* import from `@jini-ai/core/composition` outside
  * `packages/daemon/**` (type-only imports of the DI-token-derivation types
- * remain unrestricted, since they carry no runtime capability) — that guard
- * is wired in, but is a second, independent layer on top of the 2026-07-29
+ * remain unrestricted, since they carry no runtime capability). R6 checks this
+ * exact composition specifier as a second, independent layer on top of the 2026-07-29
  * structural fix above, not a substitute for it.
  */
 export { authorizeToolInvocation } from './tool-registry.js';
-//# sourceMappingURL=internal.js.map
+//# sourceMappingURL=composition.js.map

package/dist/contribution-registry.d.ts

@@ -0,0 +1,16 @@
+/** Replace-by-key registry for host-owned contributions; no singleton or execution surface. */
+export interface ContributionRegistry<TContribution> {
+    register(required: {
+        contribution: TContribution;
+    }): void;
+    /** Detached array snapshot; contribution values retain their identity. */
+    list(_required: Record<string, never>): readonly TContribution[];
+    clear(_required: Record<string, never>): void;
+}
+/** O(1) register/clear, O(n) list and O(n) retained entries. Replacement preserves position. */
+export declare function createContributionRegistry<TContribution, TKey>(required: {
+    keyOf: (required: {
+        contribution: TContribution;
+    }) => TKey;
+}): ContributionRegistry<TContribution>;
+//# sourceMappingURL=contribution-registry.d.ts.map

package/dist/contribution-registry.js

@@ -0,0 +1,12 @@
+/** O(1) register/clear, O(n) list and O(n) retained entries. Replacement preserves position. */
+export function createContributionRegistry(required) {
+    const contributions = new Map();
+    return {
+        register({ contribution }) {
+            contributions.set(required.keyOf({ contribution }), contribution);
+        },
+        list(_required) { return [...contributions.values()]; },
+        clear(_required) { contributions.clear(); },
+    };
+}
+//# sourceMappingURL=contribution-registry.js.map

package/dist/daemon.d.ts

@@ -1,10 +1,10 @@
 import type { Bindings } from './bindings.js';
 import type { Pack } from './pack.js';
 /**
- * Exported (not just used locally) so `./internal.js` can re-derive `createDaemon`'s exact
+ * Exported (not just used locally) so `./composition.js` can re-derive `createDaemon`'s exact
  * compile-time "missing binding" gate for a wrapper composition function (today:
  * `@jini-ai/server`'s `createLocalNodeDaemon`) without duplicating the type-level logic. Not
- * re-exported from `index.ts` — see `./internal.ts`'s module doc for why this stays off the
+ * re-exported from `index.ts` — see `./composition.ts`'s module doc for why this stays off the
  * public surface (same boundary pattern as `tool-registry.ts`'s `authorizeToolInvocation`).
  */
 export type AnyPack = Pack<any, any, string>;
@@ -21,6 +21,9 @@ export interface Daemon<Packs extends readonly AnyPack[] = readonly AnyPack[]> {
 export interface DaemonConfig<Packs extends readonly AnyPack[], BoundIds extends string> {
     packs: Packs;
     bindings: Bindings<BoundIds>;
+}
+/** Optional transport metadata, separate from required packs and bindings. */
+export interface DaemonOptions {
     transports?: readonly unknown[];
 }
 /**
@@ -28,13 +31,15 @@ export interface DaemonConfig<Packs extends readonly AnyPack[], BoundIds extends
  * declares a dep whose id isn't in `BoundIds`, the config parameter widens to
  * require an (unsatisfiable) `__missingBindings` property carrying the exact
  * missing-id union, so the call site fails to typecheck with that union
- * visible in the error. Runtime: `bindings.bind()` already rejects duplicate
- * singletons and version mismatches at bind time; resolving here (eagerly,
- * per pack, at compose time) surfaces "missing binding" even if the
- * compile-time gate was bypassed with `any`.
+ * visible in the error. Runtime: `bindings.bind()` rejects duplicate
+ * singletons at bind time; singleton resolution checks presence and version.
+ * Resolve every declared dependency before constructing any services, so an
+ * unused singleton still surfaces "missing binding" or a version mismatch
+ * even if the compile-time gate was bypassed with `any`. Many-token resolution
+ * preserves its existing empty-list behavior and does not check versions.
  */
 export declare function createDaemon<const Packs extends readonly AnyPack[], BoundIds extends string>(config: DaemonConfig<Packs, BoundIds> & (MissingTokenIds<Packs, BoundIds> extends never ? unknown : {
     readonly __missingBindings: MissingTokenIds<Packs, BoundIds>;
-})): Daemon<Packs>;
+}), _optional?: DaemonOptions): Daemon<Packs>;
 export {};
 //# sourceMappingURL=daemon.d.ts.map

package/dist/daemon.js

@@ -6,13 +6,13 @@ function makeContainer(pack, bound) {
         }
     };
     return {
-        get(t) {
+        get({ token: t }) {
             guard(t.id);
-            return bound.resolveOne(t);
+            return bound.resolveOne({ token: t });
         },
-        getMany(t) {
+        getMany({ token: t }) {
             guard(t.id);
-            return bound.resolveMany(t);
+            return bound.resolveMany({ token: t });
         },
     };
 }
@@ -21,12 +21,24 @@ function makeContainer(pack, bound) {
  * declares a dep whose id isn't in `BoundIds`, the config parameter widens to
  * require an (unsatisfiable) `__missingBindings` property carrying the exact
  * missing-id union, so the call site fails to typecheck with that union
- * visible in the error. Runtime: `bindings.bind()` already rejects duplicate
- * singletons and version mismatches at bind time; resolving here (eagerly,
- * per pack, at compose time) surfaces "missing binding" even if the
- * compile-time gate was bypassed with `any`.
+ * visible in the error. Runtime: `bindings.bind()` rejects duplicate
+ * singletons at bind time; singleton resolution checks presence and version.
+ * Resolve every declared dependency before constructing any services, so an
+ * unused singleton still surfaces "missing binding" or a version mismatch
+ * even if the compile-time gate was bypassed with `any`. Many-token resolution
+ * preserves its existing empty-list behavior and does not check versions.
  */
-export function createDaemon(config) {
+export function createDaemon(config, _optional = {}) {
+    // Validate the whole composition before service factories acquire resources;
+    // checking one pack at a time could leave earlier packs initialized on failure.
+    for (const pack of config.packs) {
+        for (const dependency of pack.deps) {
+            if (dependency.cardinality === 'one')
+                config.bindings.resolveOne({ token: dependency });
+            else
+                config.bindings.resolveMany({ token: dependency });
+        }
+    }
     const services = {};
     for (const pack of config.packs) {
         const container = makeContainer(pack, config.bindings);

package/dist/gated-mutations/actor-identity.d.ts

@@ -0,0 +1,20 @@
+/** Pure composite actor references; reject references across workspace boundaries. O(1). */
+export declare class WorkspaceMismatchError extends Error {
+    constructor(required: {
+        message: string;
+    }, optional?: ErrorOptions);
+}
+export declare function appendActorReference(required: {
+    referencingRowWorkspaceId: string;
+    actorWorkspaceId: string;
+    actorId: string;
+}, optional?: {
+    delegatedByWorkspaceId?: string | null;
+    delegatedById?: string | null;
+}): {
+    actorWorkspaceId: string;
+    actorId: string;
+    delegatedByWorkspaceId: string | null;
+    delegatedById: string | null;
+};
+//# sourceMappingURL=actor-identity.d.ts.map

package/dist/gated-mutations/actor-identity.js

@@ -0,0 +1,31 @@
+/** Pure composite actor references; reject references across workspace boundaries. O(1). */
+export class WorkspaceMismatchError extends Error {
+    constructor(required, optional = {}) {
+        super(required.message, optional);
+    }
+}
+// Composite (workspace, actor) references retain the tenant boundary even when an agent or
+// API key acts for a delegating user. Reject mismatches before a caller persists the row.
+// This helper performs no I/O or foreign-key checks: dependent domains own read-time orphan
+// tolerance and reconciliation, rather than making identity population depend on storage.
+export function appendActorReference(required, optional = {}) {
+    const { referencingRowWorkspaceId, actorWorkspaceId, actorId } = required;
+    const { delegatedByWorkspaceId, delegatedById } = optional;
+    if (actorWorkspaceId !== referencingRowWorkspaceId) {
+        throw new WorkspaceMismatchError({
+            message: `actor workspace '${actorWorkspaceId}' does not match referencing row workspace '${referencingRowWorkspaceId}'`
+        });
+    }
+    if (delegatedByWorkspaceId != null && delegatedByWorkspaceId !== referencingRowWorkspaceId) {
+        throw new WorkspaceMismatchError({
+            message: `delegator workspace '${delegatedByWorkspaceId}' does not match referencing row workspace '${referencingRowWorkspaceId}'`
+        });
+    }
+    return {
+        actorWorkspaceId,
+        actorId,
+        delegatedByWorkspaceId: delegatedByWorkspaceId ?? null,
+        delegatedById: delegatedById ?? null,
+    };
+}
+//# sourceMappingURL=actor-identity.js.map

package/dist/gated-mutations/gateway.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Transport-neutral plan -> confirm -> execute approval ceremony.
+ * Ordering: authorize, token state, fresh actor identity, scope/hash, atomic redeem, mutation.
+ * Mutation receives the verified plan and must not independently rederive its write set.
+ * O(1) local work plus injected port costs; no lock or transactional rollback is implied.
+ */
+import { type Clock, type IdGenerator } from "../primitives/index.js";
+import type { AuthorizeFn, InstanceAuthorizeFn, PrincipalKind } from "./ports.js";
+import { type ConfirmationTokenRecord, type TokenStorePort } from "./token.js";
+export interface GatedMutationHooks<TDetails, TResult> {
+    domain: string;
+    readPermission: string;
+    mutatePermission: string;
+    /** Workspace scope is the authorization target; for instance scope this is only an opaque
+     * audit label. A workspace grant must never stand in for authority over every workspace. */
+    scopeId: string;
+    /** Omission preserves workspace authorization; instance scope uses its own injected evaluator. */
+    scopeKind?: "workspace" | "instance";
+    computePlan(required: Record<string, never>): Promise<{
+        planHash: string;
+        details: TDetails;
+    }>;
+    /**
+     * Apply the verified plan, never recompute it: token redemption and any intervening mutation
+     * work separate verification from application, and this gateway takes no operation lock.
+     * Re-deriving there can apply a different write set from the one the operator approved.
+     * A mutation without plan-dependent work can ignore this argument.
+     */
+    executeMutation(verified: {
+        planHash: string;
+        details: TDetails;
+    }): Promise<TResult>;
+    /** Resolve fresh at execution: the user itself, an agent's current delegator, or an API key's
+     * owning user. Confirm-time identity can become stale before redemption. */
+    resolveActorClassIdentity(params: {
+        principalId: string;
+        principalKind: PrincipalKind;
+    }): Promise<string | null>;
+}
+export interface GatewayDeps {
+    /** Required token policy: caller supplies the complete opaque token and TTL. */
+    generateToken: (required: Record<string, never>) => string;
+    ttlSeconds: number;
+    clock: Clock;
+    idGen: IdGenerator;
+    authorize: AuthorizeFn;
+    /** Missing instance authorization must deny, never fall back to a workspace-scoped grant. */
+    authorizeInstance?: InstanceAuthorizeFn;
+    tokens: TokenStorePort;
+}
+export interface GatewayPlan {
+    domain: string;
+    planId: string;
+    planHash: string;
+    details: unknown;
+}
+export declare class ForbiddenError extends Error {
+    readonly reasonCode: string;
+    constructor(required: {
+        message: string;
+        reasonCode: string;
+    }, optional?: ErrorOptions);
+}
+export declare class PlanStaleError extends Error {
+    constructor(required: {
+        message: string;
+    }, optional?: ErrorOptions);
+}
+export declare class UnauthenticatedError extends Error {
+    constructor(required: {
+        message: string;
+    }, optional?: ErrorOptions);
+}
+/**
+ * Share this scope decision with route authorization before operation-lock acquisition. A route
+ * that hardcodes workspace authorization can briefly acquire a lock with insufficient instance
+ * authority before the deeper gate refuses it. Missing instance wiring therefore denies outright.
+ */
+export declare function authorizeForHooks(required: {
+    deps: GatewayDeps;
+    hooks: GatedMutationHooks<unknown, unknown>;
+    principalId: string;
+    permission: string;
+}): Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+export declare function plan(required: {
+    deps: GatewayDeps;
+    principalId: string;
+    principalKind: PrincipalKind;
+    hooks: GatedMutationHooks<unknown, unknown>;
+}, _optional?: Record<string, never>): Promise<GatewayPlan>;
+export declare function confirm(required: {
+    deps: GatewayDeps;
+    principalId: string;
+    principalKind: PrincipalKind;
+    hooks: GatedMutationHooks<unknown, unknown>;
+    planId: string;
+    planHash: string;
+}, _optional?: Record<string, never>): Promise<ConfirmationTokenRecord>;
+/**
+ * Rejection precedence is binding when failures co-occur: fresh authorization, token state,
+ * fresh actor identity, then plan validity. Expired/redeemed tokens win over identity mismatch;
+ * identity mismatch wins over a simultaneously stale plan. Typed errors keep these outcomes
+ * distinct for callers. Only atomic redemption permits the domain mutation.
+ */
+export declare function execute<TResult>(required: {
+    deps: GatewayDeps;
+    principalId: string;
+    principalKind: PrincipalKind;
+    hooks: GatedMutationHooks<unknown, TResult>;
+    confirmationToken: string;
+}, _optional?: Record<string, never>): Promise<TResult>;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/gated-mutations/gateway.js

@@ -0,0 +1,123 @@
+/**
+ * Transport-neutral plan -> confirm -> execute approval ceremony.
+ * Ordering: authorize, token state, fresh actor identity, scope/hash, atomic redeem, mutation.
+ * Mutation receives the verified plan and must not independently rederive its write set.
+ * O(1) local work plus injected port costs; no lock or transactional rollback is implied.
+ */
+import { nowIso } from "../primitives/index.js";
+import { TokenAlreadyRedeemedError, TokenExpiredError, isRedeemable, mintToken, } from "./token.js";
+export class ForbiddenError extends Error {
+    reasonCode;
+    constructor(required, optional = {}) {
+        super(required.message, optional);
+        this.reasonCode = required.reasonCode;
+    }
+}
+export class PlanStaleError extends Error {
+    constructor(required, optional = {}) {
+        super(required.message, optional);
+    }
+}
+// Reserved for a host that cannot establish caller identity before entering the ceremony;
+// the gateway itself does not currently raise this error.
+export class UnauthenticatedError extends Error {
+    constructor(required, optional = {}) {
+        super(required.message, optional);
+    }
+}
+/**
+ * Share this scope decision with route authorization before operation-lock acquisition. A route
+ * that hardcodes workspace authorization can briefly acquire a lock with insufficient instance
+ * authority before the deeper gate refuses it. Missing instance wiring therefore denies outright.
+ */
+export async function authorizeForHooks(required) {
+    const { deps, hooks, principalId, permission } = required;
+    if (hooks.scopeKind !== "instance") {
+        return deps.authorize({ principalId, permission, workspaceId: hooks.scopeId });
+    }
+    if (!deps.authorizeInstance) {
+        return { allowed: false, reason: "INSTANCE_AUTHORIZATION_NOT_CONFIGURED" };
+    }
+    return deps.authorizeInstance({ principalId, permission });
+}
+// Planning is read-only: check read permission and derive details, never invoke executeMutation.
+export async function plan(required, _optional = {}) {
+    const { deps, principalId, hooks } = required;
+    const authResult = await authorizeForHooks({ deps, hooks, principalId, permission: hooks.readPermission });
+    if (!authResult.allowed) {
+        throw new ForbiddenError({ message: `principal '${principalId}' is not authorized for '${hooks.readPermission}' (${authResult.reason})`, reasonCode: "NOT_AUTHORIZED" });
+    }
+    const { planHash, details } = await hooks.computePlan({});
+    return { domain: hooks.domain, planId: deps.idGen.newId(), planHash, details };
+}
+// Confirmation is a human/API-key act: an agent may redeem its delegator's approval later,
+// but may never mint its own confirmation, regardless of its mutation permissions.
+export async function confirm(required, _optional = {}) {
+    const { deps, principalId, principalKind, hooks, planId, planHash } = required;
+    if (principalKind === "agent") {
+        throw new ForbiddenError({ message: `agent principals may not confirm a gated mutation`, reasonCode: "AGENT_CANNOT_CONFIRM" });
+    }
+    const authResult = await authorizeForHooks({ deps, hooks, principalId, permission: hooks.mutatePermission });
+    if (!authResult.allowed) {
+        throw new ForbiddenError({ message: `principal '${principalId}' is not authorized for '${hooks.mutatePermission}' (${authResult.reason})`, reasonCode: "NOT_AUTHORIZED" });
+    }
+    const token = mintToken({
+        planId,
+        planHash,
+        scopeId: hooks.scopeId,
+        confirmerPrincipalId: principalId,
+        now: nowIso({ clock: deps.clock }),
+        generateToken: deps.generateToken,
+        ttlSeconds: deps.ttlSeconds,
+    });
+    await deps.tokens.save({ record: token });
+    return token;
+}
+/**
+ * Rejection precedence is binding when failures co-occur: fresh authorization, token state,
+ * fresh actor identity, then plan validity. Expired/redeemed tokens win over identity mismatch;
+ * identity mismatch wins over a simultaneously stale plan. Typed errors keep these outcomes
+ * distinct for callers. Only atomic redemption permits the domain mutation.
+ */
+export async function execute(required, _optional = {}) {
+    // Reevaluate authorization here; confirm-time permission is not authority to execute later.
+    const { deps, principalId, principalKind, hooks, confirmationToken } = required;
+    const authResult = await authorizeForHooks({ deps, hooks, principalId, permission: hooks.mutatePermission });
+    if (!authResult.allowed) {
+        throw new ForbiddenError({ message: `principal '${principalId}' is not authorized for '${hooks.mutatePermission}' (${authResult.reason})`, reasonCode: "NOT_AUTHORIZED" });
+    }
+    const record = await deps.tokens.findByToken({ token: confirmationToken });
+    if (!record) {
+        throw new TokenExpiredError({ message: `confirmation token was not found` });
+    }
+    if (!isRedeemable({ record, now: nowIso({ clock: deps.clock }) })) {
+        if (record.status === "redeemed") {
+            throw new TokenAlreadyRedeemedError({ message: `confirmation token has already been redeemed` });
+        }
+        throw new TokenExpiredError({ message: `confirmation token has expired` });
+    }
+    const resolvedIdentity = await hooks.resolveActorClassIdentity({ principalId, principalKind });
+    if (resolvedIdentity !== record.confirmerPrincipalId) {
+        throw new ForbiddenError({ message: `principal '${principalId}' (kind '${principalKind}') is not the confirmer of this token`, reasonCode: "ACTOR_CLASS_MISMATCH" });
+    }
+    if (record.scopeId !== hooks.scopeId) {
+        throw new ForbiddenError({ message: `confirmation token belongs to a different scope`, reasonCode: "SCOPE_MISMATCH" });
+    }
+    // Retain these verified details through redemption so application cannot choose a new plan.
+    const { planHash, details } = await hooks.computePlan({});
+    if (planHash !== record.planHash) {
+        throw new PlanStaleError({
+            message: `the plan backing this confirmation has changed since it was confirmed; re-plan and re-confirm`
+        });
+    }
+    // Concurrent executions can pass every earlier check; atomic redemption makes the loser fail
+    // before its domain mutation, preventing a second application of the same approval.
+    const { redeemed, record: latestRecord } = await deps.tokens.tryRedeem({ token: confirmationToken, now: nowIso({ clock: deps.clock }) });
+    if (!redeemed) {
+        if (!latestRecord || latestRecord.status !== "redeemed")
+            throw new TokenExpiredError({ message: `confirmation token has expired` });
+        throw new TokenAlreadyRedeemedError({ message: `confirmation token has already been redeemed` });
+    }
+    return hooks.executeMutation({ planHash, details });
+}
+//# sourceMappingURL=gateway.js.map

package/dist/gated-mutations/ports.d.ts

@@ -0,0 +1,27 @@
+/** Authorization ports; custom actor kinds use the injected actor-identity resolver. */
+export type PrincipalKind = "user" | "agent" | "api_key" | (string & {});
+/** The host binds its identity evaluator as a closure; core must not import the identity feature. */
+export type AuthorizeFn = (required: {
+    principalId: string;
+    permission: string;
+    workspaceId: string;
+}, optional?: {
+    entityType?: string;
+    entityId?: string;
+}) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+/**
+ * Instance-wide mutations need a separate evaluator, without a workspace id. Using a sentinel
+ * workspace either finds no principal or lets one tenant's admin approve a cross-tenant mutation.
+ * A workspace authorization result must never stand in for authority over the whole instance.
+ */
+export type InstanceAuthorizeFn = (params: {
+    principalId: string;
+    permission: string;
+}) => Promise<{
+    allowed: boolean;
+    reason: string;
+}>;
+//# sourceMappingURL=ports.d.ts.map

package/dist/gated-mutations/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map