@jini-ai/core 0.3.0 → 0.4.0

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

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

@@ -0,0 +1,95 @@
+/** Opaque, single-use approval tokens. Clock, generation and TTL are host policy. */
+export interface ConfirmationTokenRecord {
+    confirmationToken: string;
+    planHash: string;
+    scopeId: string;
+    confirmerPrincipalId: string;
+    status: 'minted' | 'redeemed' | 'expired';
+    createdAt: string;
+    expiresAt: string;
+}
+export interface TokenStorePort {
+    /** Insert only: never overwrite a previously issued token, including terminal states. */
+    save(required: {
+        record: ConfirmationTokenRecord;
+    }): Promise<void>;
+    findByToken(required: {
+        token: string;
+    }): Promise<ConfirmationTokenRecord | null>;
+    /** Atomically check TTL/status and transition minted -> redeemed. */
+    tryRedeem(required: {
+        token: string;
+        now: string;
+    }): Promise<{
+        redeemed: boolean;
+        record: ConfirmationTokenRecord | null;
+    }>;
+    /** Atomically transition minted -> expired without overwriting concurrent redemption. */
+    expire(required: {
+        token: string;
+    }): Promise<void>;
+}
+export declare class TokenExpiredError extends Error {
+    constructor(required: {
+        message: string;
+    }, optional?: ErrorOptions);
+}
+export declare class TokenAlreadyRedeemedError extends Error {
+    constructor(required: {
+        message: string;
+    }, optional?: ErrorOptions);
+}
+/** O(1). The complete token string comes from the injected cryptographically secure generator. */
+export declare function mintToken(required: {
+    planId: string;
+    planHash: string;
+    scopeId: string;
+    confirmerPrincipalId: string;
+    now: string;
+    ttlSeconds: number;
+    generateToken: (required: Record<string, never>) => string;
+}): ConfirmationTokenRecord;
+/** O(1). The exact expiry instant is inclusive, preserving the approval lifecycle contract. */
+export declare function isRedeemable(required: {
+    record: ConfirmationTokenRecord;
+    now: string;
+}): boolean;
+/** O(1) local work plus one atomic store operation. */
+export declare function redeemToken(required: {
+    store: TokenStorePort;
+    token: string;
+    now: string;
+}): Promise<ConfirmationTokenRecord>;
+/** Explicit revocation; now is retained for compatibility with lifecycle caller records. */
+export declare function expireToken(required: {
+    store: TokenStorePort;
+    token: string;
+    now: string;
+}): Promise<void>;
+/**
+ * Instance-owned test adapter. Operations are O(1); space O(n) issued tokens.
+ * No await splits conditional transitions. Records are returned as detached values.
+ * Hosts must supply retention/cleanup for a long-lived store.
+ */
+export declare class InMemoryTokenStore implements TokenStorePort {
+    constructor(_required: Record<string, never>);
+    private readonly recordsByToken;
+    save(required: {
+        record: ConfirmationTokenRecord;
+    }): Promise<void>;
+    findByToken(required: {
+        token: string;
+    }): Promise<ConfirmationTokenRecord | null>;
+    tryRedeem(required: {
+        token: string;
+        now: string;
+    }): Promise<{
+        redeemed: boolean;
+        record: ConfirmationTokenRecord | null;
+    }>;
+    expire(required: {
+        token: string;
+    }): Promise<void>;
+    count(_required: Record<string, never>): Promise<number>;
+}
+//# sourceMappingURL=token.d.ts.map

package/dist/gated-mutations/token.js

@@ -0,0 +1,87 @@
+export class TokenExpiredError extends Error {
+    constructor(required, optional = {}) {
+        super(required.message, optional);
+    }
+}
+export class TokenAlreadyRedeemedError extends Error {
+    constructor(required, optional = {}) {
+        super(required.message, optional);
+    }
+}
+/** O(1). The complete token string comes from the injected cryptographically secure generator. */
+export function mintToken(required) {
+    const timestamp = Date.parse(required.now);
+    if (!Number.isFinite(timestamp) || !Number.isFinite(required.ttlSeconds) || required.ttlSeconds <= 0) {
+        throw new RangeError('token timestamp must be valid and TTL must be positive and finite');
+    }
+    const expiresAt = new Date(timestamp + required.ttlSeconds * 1000).toISOString();
+    // Exact host-selected TTL, without jitter: approval expiration is a user-visible boundary.
+    const confirmationToken = required.generateToken({});
+    if (typeof confirmationToken !== 'string' || confirmationToken.length === 0) {
+        throw new Error('token generator must return a non-empty string');
+    }
+    return {
+        confirmationToken, planHash: required.planHash, scopeId: required.scopeId,
+        confirmerPrincipalId: required.confirmerPrincipalId, status: 'minted',
+        createdAt: required.now, expiresAt,
+    };
+}
+/** O(1). The exact expiry instant is inclusive, preserving the approval lifecycle contract. */
+export function isRedeemable(required) {
+    return required.record.status === 'minted' && Date.parse(required.now) <= Date.parse(required.record.expiresAt);
+}
+/** O(1) local work plus one atomic store operation. */
+export async function redeemToken(required) {
+    // Gateways may use the port directly to interleave actor/authorization/hash checks in their own
+    // required order; this wrapper owns the standalone lifecycle error contract. Missing and expired
+    // approvals share an error type, while a spent approval reports its distinct terminal state.
+    const { redeemed, record } = await required.store.tryRedeem({ token: required.token, now: required.now });
+    if (redeemed && record)
+        return record;
+    if (!record)
+        throw new TokenExpiredError({ message: 'confirmation token was not found' });
+    if (record.status === 'redeemed')
+        throw new TokenAlreadyRedeemedError({ message: 'confirmation token has already been redeemed' });
+    throw new TokenExpiredError({ message: 'confirmation token has expired' });
+}
+/** Explicit revocation; now is retained for compatibility with lifecycle caller records. */
+export async function expireToken(required) {
+    // Revocation can only advance minted -> expired; it must never un-redeem a spent approval.
+    await required.store.expire({ token: required.token });
+}
+/**
+ * Instance-owned test adapter. Operations are O(1); space O(n) issued tokens.
+ * No await splits conditional transitions. Records are returned as detached values.
+ * Hosts must supply retention/cleanup for a long-lived store.
+ */
+export class InMemoryTokenStore {
+    constructor(_required) { }
+    recordsByToken = new Map();
+    async save(required) {
+        const record = required.record;
+        if (this.recordsByToken.has(record.confirmationToken))
+            throw new Error('confirmation token already exists');
+        this.recordsByToken.set(record.confirmationToken, { ...record });
+    }
+    async findByToken(required) {
+        const record = this.recordsByToken.get(required.token);
+        return record ? { ...record } : null;
+    }
+    async tryRedeem(required) {
+        const record = this.recordsByToken.get(required.token);
+        if (!record)
+            return { redeemed: false, record: null };
+        if (!isRedeemable({ record, now: required.now }))
+            return { redeemed: false, record: { ...record } };
+        const updated = { ...record, status: 'redeemed' };
+        this.recordsByToken.set(required.token, updated);
+        return { redeemed: true, record: { ...updated } };
+    }
+    async expire(required) {
+        const record = this.recordsByToken.get(required.token);
+        if (record?.status === 'minted')
+            this.recordsByToken.set(required.token, { ...record, status: 'expired' });
+    }
+    async count(_required) { return this.recordsByToken.size; }
+}
+//# sourceMappingURL=token.js.map

package/dist/gated-mutations.d.ts

@@ -0,0 +1,5 @@
+export * from './gated-mutations/gateway.js';
+export * from './gated-mutations/token.js';
+export * from './gated-mutations/ports.js';
+export * from './gated-mutations/actor-identity.js';
+//# sourceMappingURL=gated-mutations.d.ts.map

package/dist/gated-mutations.js

@@ -0,0 +1,5 @@
+export * from './gated-mutations/gateway.js';
+export * from './gated-mutations/token.js';
+export * from './gated-mutations/ports.js';
+export * from './gated-mutations/actor-identity.js';
+//# sourceMappingURL=gated-mutations.js.map

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export * from './token.js';
 export * from './pack.js';
 export * from './bindings.js';
-export type { Daemon, DaemonConfig } from './daemon.js';
+export type { Daemon, DaemonConfig, DaemonOptions } from './daemon.js';
 export { createDaemon } from './daemon.js';
 export type { PackDisposalFailure } from './pack-lifecycle.js';
 export { disposePacks, registerPackTools } from './pack-lifecycle.js';
@@ -9,7 +9,13 @@ export * from './redact.js';
 export * from './api-token-auth.js';
 export * from './origin-validation.js';
 export * from './principal.js';
-export type { AuthorizationDecision, RunRef, SurfaceEmission, SurfaceEmitter, ToolAuthorizationContext, ToolDescriptor, ToolExecutionContext, ToolHandler, ToolPolicy, ToolRegistration, ToolRegistry, } from './tool-registry.js';
-export { createToolRegistry, ToolInputError } from './tool-registry.js';
+export type { AuthorizationDecision, RunRef, SurfaceEmission, SurfaceEmitter, ToolAuthorizationContext, ToolDescriptor, ToolExecutionContext, ToolExecutionOptions, ToolHandler, ToolPolicy, ToolRegistration, ToolRegistry, } from './tool-registry.js';
+export { createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
 export * from './tool-tokens.js';
+export * from './gated-mutations.js';
+export * from './model-facing-tool-errors.js';
+export * from './contribution-registry.js';
+export * from './naming.js';
+export type { AgentToolSideEffect, AgentToolActorClassRule, AgentToolDefinition } from './agent-tools.js';
+export * from "./registration-kit.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -7,6 +7,11 @@ export * from './redact.js';
 export * from './api-token-auth.js';
 export * from './origin-validation.js';
 export * from './principal.js';
-export { createToolRegistry, ToolInputError } from './tool-registry.js';
+export { createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
 export * from './tool-tokens.js';
+export * from './gated-mutations.js';
+export * from './model-facing-tool-errors.js';
+export * from './contribution-registry.js';
+export * from './naming.js';
+export * from "./registration-kit.js";
 //# sourceMappingURL=index.js.map