@try-works/dsh-tool-mode 0.0.0-stage → 0.5.45

package/cordis.patch.yml

@@ -0,0 +1,39 @@
+# The dsh-tool-mode bundle patch: one insert row over the empty profile root.
+#
+# A user's profile `cordis.patch.yml` (or the file this row is installed into)
+# addresses this row by id, so a deployment can change the config without
+# forking the package. Later patch layers win per row.
+#
+# `models: []` means "no explicit allowlist": every model whose runtime resolves
+# in this process is registered. Naming ids narrows the surface; naming a model
+# that cannot run here is harmless, because the allowlist is intersected with
+# what the capability resolver proves runnable.
+
+- insert:
+    - id: model-tools
+      name: '@try-works/dsh-tool-mode'
+      config:
+        # Every model that can actually run in this process.
+        models: []
+        exclude: []
+        # Do not register a tool for a model whose runtime is missing: a tool
+        # that cannot work costs a model turn to discover.
+        exposeUnavailable: false
+        # Publish one skill per registered tool, teaching when to use it.
+        registerSkills: true
+        # Register the `model_tools` inspection and install tool.
+        registerControlTool: true
+        # Allow in-process npm packages. Set false to force every call through
+        # the CLI or the bridge below.
+        allowNpm: true
+        # The Desert Ant CLI, auto-detected on PATH (macOS and Linux). It can run
+        # every shipping model, so it is the route that needs no extra service.
+        cli:
+          enabled: true
+          command: desertant
+        # A bridge on a machine that can run what this one cannot — most
+        # importantly the Apple-only models. Leave the endpoint empty to disable.
+        # See scripts/desert-ant-bridge.mjs; the plugin never hosts this itself.
+        remote:
+          endpoint: ''
+          token: ''

package/lib/adapters/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Adapter registry: the one place that maps a catalog model to the code that
+ * can invoke it.
+ *
+ * Two kinds of adapter exist. A **model adapter** is written by hand for a model
+ * with a real in-process SDK (Tongue, Voz). A **transport adapter** is generic:
+ * it drives any model through the Desert Ant CLI or a user-hosted bridge, using
+ * only the catalog's verb and parameter declarations.
+ *
+ * @module @try-works/dsh-tool-mode/adapters/index
+ */
+import type { ModelCatalogEntry } from '../types.ts';
+import type { AdapterFactory, ModelAdapter } from './types.ts';
+import type { ProviderBridge } from '../provider-bridge.ts';
+import { type TransportOptions } from '../transport.ts';
+/**
+ * Hand-written adapters living inside the host.
+ *
+ * EMPTY, and it must stay that way (BASE-09). Every model-specific implementation
+ * is now an independently versioned extension package reached through the public
+ * extension API: Tongue is `@try-works/extension-desert-ant-tongue` and Voz is
+ * `@try-works/extension-desert-ant-voz`. The host holds no adapter for any model,
+ * so a first-party package has no privilege a published one lacks.
+ *
+ * The parameter is kept rather than deleted because a test may still inject
+ * factories, and an empty list DOCUMENTED as needing to stay empty is a stronger
+ * statement than a removed hook.
+ */
+export declare const ADAPTER_FACTORIES: readonly AdapterFactory[];
+/**
+ * Options that decide which transports a model may use.
+ *
+ * `routes` is normally the capability resolver's verdict, which is what keeps
+ * the adapter and the reported reason from disagreeing: a model is only offered
+ * through a transport the resolver already proved usable.
+ */
+export interface TransportSelection extends TransportOptions {
+    /** The resolved route for this model. */
+    readonly route: string;
+}
+/**
+ * Create the adapter for one entry.
+ *
+ * A hand-written adapter always wins for the model it serves: an in-process
+ * call is faster and needs no external service. Everything else falls to the
+ * transport the capability resolver selected.
+ *
+ * The lookup is ASYNC because an extension-backed model is reached by importing
+ * and activating its package, which cannot happen in a synchronous call. The
+ * order is deliberate: a declared extension binding wins, then a hand-written
+ * factory, then a transport.
+ * @param entry - the catalog entry.
+ * @param options - the resolved route plus transport settings.
+ * @param factories - hand-written adapter factories, defaulting to the shipped set.
+ * @param bridge - the extension provider bridge, when extensions are available.
+ * @returns the adapter, or undefined when no extension, factory or transport serves this model.
+ */
+export declare function createAdapter(entry: ModelCatalogEntry, options?: TransportSelection, factories?: readonly AdapterFactory[], bridge?: ProviderBridge): ModelAdapter | undefined;
+export type { AdapterFactory, AdapterInvocation, JsonValue, ModelAdapter } from './types.ts';
+export type { CommandTransport, TransportOptions } from '../transport.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAAO,CAAA;AAE9D;;;;;;GAMG;AACH,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAmBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,iBAAiB,EACxB,OAAO,GAAE,kBAA4C,EACrD,SAAS,GAAE,SAAS,cAAc,EAAsB,EACxD,MAAM,CAAC,EAAE,cAAc,GACtB,YAAY,GAAG,SAAS,CAoB1B;AAED,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC5F,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}

package/lib/adapters/index.js

@@ -0,0 +1,82 @@
+/**
+ * Adapter registry: the one place that maps a catalog model to the code that
+ * can invoke it.
+ *
+ * Two kinds of adapter exist. A **model adapter** is written by hand for a model
+ * with a real in-process SDK (Tongue, Voz). A **transport adapter** is generic:
+ * it drives any model through the Desert Ant CLI or a user-hosted bridge, using
+ * only the catalog's verb and parameter declarations.
+ *
+ * @module @try-works/dsh-tool-mode/adapters/index
+ */
+import { createCliTransport, createRemoteTransport, } from "../transport.js";
+/**
+ * Hand-written adapters living inside the host.
+ *
+ * EMPTY, and it must stay that way (BASE-09). Every model-specific implementation
+ * is now an independently versioned extension package reached through the public
+ * extension API: Tongue is `@try-works/extension-desert-ant-tongue` and Voz is
+ * `@try-works/extension-desert-ant-voz`. The host holds no adapter for any model,
+ * so a first-party package has no privilege a published one lacks.
+ *
+ * The parameter is kept rather than deleted because a test may still inject
+ * factories, and an empty list DOCUMENTED as needing to stay empty is a stronger
+ * statement than a removed hook.
+ */
+export const ADAPTER_FACTORIES = [];
+/**
+ * Wrap a command transport as a model adapter.
+ *
+ * The transport already returns the canonical object, so this is a pure
+ * adaptation of shape rather than a second place that knows how to parse a
+ * result.
+ * @param entry - the catalog entry.
+ * @param transport - the CLI or remote transport.
+ * @returns the adapter.
+ */
+function transportAdapter(entry, transport) {
+    return {
+        modelId: entry.id,
+        invoke: ({ args, signal }) => transport.invoke({ entry, args, signal }),
+    };
+}
+/**
+ * Create the adapter for one entry.
+ *
+ * A hand-written adapter always wins for the model it serves: an in-process
+ * call is faster and needs no external service. Everything else falls to the
+ * transport the capability resolver selected.
+ *
+ * The lookup is ASYNC because an extension-backed model is reached by importing
+ * and activating its package, which cannot happen in a synchronous call. The
+ * order is deliberate: a declared extension binding wins, then a hand-written
+ * factory, then a transport.
+ * @param entry - the catalog entry.
+ * @param options - the resolved route plus transport settings.
+ * @param factories - hand-written adapter factories, defaulting to the shipped set.
+ * @param bridge - the extension provider bridge, when extensions are available.
+ * @returns the adapter, or undefined when no extension, factory or transport serves this model.
+ */
+export function createAdapter(entry, options = { route: 'npm-native' }, factories = ADAPTER_FACTORIES, bridge) {
+    // A declared extension binding is the model's own statement of who implements
+    // it, but only the explicit extension route may use it. This keeps CLI/remote
+    // fallback routes from accidentally trying to load a provider package.
+    if (options.route === 'extension')
+        return bridge?.adapterFor(entry);
+    for (const factory of factories) {
+        const adapter = factory(entry);
+        if (adapter !== undefined)
+            return adapter;
+    }
+    // No extension and no factory: the model is reachable only through a transport.
+    if (options.route === 'cli')
+        return transportAdapter(entry, createCliTransport(entry, options));
+    if (options.route === 'remote') {
+        return transportAdapter(entry, createRemoteTransport(entry, options));
+    }
+    // No extension, no factory and no transport serves this model. Returning
+    // undefined is correct: a model with no implementation simply has no tool,
+    // rather than falling back to something that cannot run it.
+    return undefined;
+}
+//# sourceMappingURL=index.js.map

package/lib/adapters/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The adapter seam: how one catalog model is actually invoked.
+ *
+ * An adapter is responsible for exactly two things — loading its model lazily
+ * and turning validated tool arguments into the canonical JSON value the tool
+ * declares. Everything else (which models exist, whether they may run, what the
+ * model sees) belongs to the catalog, the capability resolver, and the
+ * registrar.
+ *
+ * @module @try-works/dsh-tool-mode/adapters/types
+ */
+import type { ModelCatalogEntry } from '../types.ts';
+import type { InvocationAuthority } from '../authority.ts';
+/** A lossless JSON value, the only thing a tool body may return. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** One adapter invocation. */
+export interface AdapterInvocation {
+    /** Validated tool arguments, already constrained by the registered parameter schema. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Caller cancellation, forwarded by the tool body. */
+    readonly signal: AbortSignal;
+    /**
+     * Trusted authority for this call (BASE-05).
+     *
+     * An implementation MUST resolve a caller-supplied path through
+     * `authority.resolvePath` rather than opening the argument directly: the
+     * authority is constructed by the host and cannot be supplied or widened by a
+     * request. It is optional only so a test can drive an adapter without a grant;
+     * a host always provides one.
+     */
+    readonly authority?: InvocationAuthority;
+}
+/** One model's invocation strategy. */
+export interface ModelAdapter {
+    /** The catalog id this adapter serves. */
+    readonly modelId: string;
+    /**
+     * Run the model once and return the canonical value.
+     *
+     * Every model tool declares an object output schema, so an adapter returns an
+     * object rather than an arbitrary JSON root.
+     * @param invocation - validated arguments and caller cancellation.
+     * @returns the lossless JSON object declared by the tool's output schema.
+     */
+    invoke(invocation: AdapterInvocation): Promise<Record<string, JsonValue>>;
+    /**
+     * Release any process-level model resources.
+     *
+     * Called on plugin dispose. Adapters that cache a loaded model must implement
+     * it; adapters that hold nothing may omit it.
+     */
+    dispose?(): Promise<void>;
+}
+/** Build an adapter for one runnable model, or `undefined` when none exists yet. */
+export type AdapterFactory = (entry: ModelCatalogEntry) => ModelAdapter | undefined;
+/**
+ * Reject an aborted call before doing model work.
+ * @param signal - caller cancellation.
+ * @throws the abort reason when the signal is already aborted.
+ */
+export declare function throwIfAborted(signal: AbortSignal): void;
+/**
+ * Read a required string argument.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @returns the string value.
+ * @throws when the value is absent or not a string.
+ */
+export declare function requireString(args: Readonly<Record<string, unknown>>, key: string): string;
+/**
+ * Read an optional integer argument, clamped to a range.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param options - inclusive bounds and the value to use when absent.
+ * @returns the resolved integer.
+ * @throws when the value is present but not an integer in range.
+ */
+export declare function optionalInteger(args: Readonly<Record<string, unknown>>, key: string, options: {
+    readonly min: number;
+    readonly max: number;
+    readonly fallback: number;
+}): number;
+/**
+ * Read an optional number in a range.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param options - inclusive bounds.
+ * @returns the resolved number, or undefined when absent.
+ * @throws when the value is present but not a finite number in range.
+ */
+export declare function optionalNumber(args: Readonly<Record<string, unknown>>, key: string, options: {
+    readonly min: number;
+    readonly max: number;
+}): number | undefined;
+/**
+ * Read a required boolean argument.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param fallback - value used when the argument is absent.
+ * @returns the resolved boolean.
+ * @throws when the value is present but not a boolean.
+ */
+export declare function optionalBoolean(args: Readonly<Record<string, unknown>>, key: string, fallback: boolean): boolean;
+//# sourceMappingURL=types.d.ts.map

package/lib/adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAE1D,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAErG,8BAA8B;AAC9B,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAChD,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAA;CACzC;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,MAAM,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;IACzE;;;;;OAKG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,GAAG,SAAS,CAAA;AAEnF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjF,MAAM,CAOR;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACtD,MAAM,GAAG,SAAS,CAOpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,OAAO,GAChB,OAAO,CAKT"}

package/lib/adapters/types.js

@@ -0,0 +1,85 @@
+/**
+ * The adapter seam: how one catalog model is actually invoked.
+ *
+ * An adapter is responsible for exactly two things — loading its model lazily
+ * and turning validated tool arguments into the canonical JSON value the tool
+ * declares. Everything else (which models exist, whether they may run, what the
+ * model sees) belongs to the catalog, the capability resolver, and the
+ * registrar.
+ *
+ * @module @try-works/dsh-tool-mode/adapters/types
+ */
+/**
+ * Reject an aborted call before doing model work.
+ * @param signal - caller cancellation.
+ * @throws the abort reason when the signal is already aborted.
+ */
+export function throwIfAborted(signal) {
+    if (signal.aborted)
+        throw signal.reason instanceof Error ? signal.reason : new Error('aborted');
+}
+/**
+ * Read a required string argument.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @returns the string value.
+ * @throws when the value is absent or not a string.
+ */
+export function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`argument "${key}" must be a non-empty string`);
+    }
+    return value;
+}
+/**
+ * Read an optional integer argument, clamped to a range.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param options - inclusive bounds and the value to use when absent.
+ * @returns the resolved integer.
+ * @throws when the value is present but not an integer in range.
+ */
+export function optionalInteger(args, key, options) {
+    const value = args[key];
+    if (value === undefined)
+        return options.fallback;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < options.min || value > options.max) {
+        throw new Error(`argument "${key}" must be an integer between ${options.min} and ${options.max}`);
+    }
+    return value;
+}
+/**
+ * Read an optional number in a range.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param options - inclusive bounds.
+ * @returns the resolved number, or undefined when absent.
+ * @throws when the value is present but not a finite number in range.
+ */
+export function optionalNumber(args, key, options) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < options.min || value > options.max) {
+        throw new Error(`argument "${key}" must be a number between ${options.min} and ${options.max}`);
+    }
+    return value;
+}
+/**
+ * Read a required boolean argument.
+ * @param args - validated arguments.
+ * @param key - argument name.
+ * @param fallback - value used when the argument is absent.
+ * @returns the resolved boolean.
+ * @throws when the value is present but not a boolean.
+ */
+export function optionalBoolean(args, key, fallback) {
+    const value = args[key];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        throw new Error(`argument "${key}" must be a boolean`);
+    return value;
+}
+//# sourceMappingURL=types.js.map

package/lib/approval.d.ts

@@ -0,0 +1,189 @@
+/**
+ * SEC-09 — the approval state machine for management-sensitive changes.
+ *
+ * A management-sensitive mutation (enabling a model, installing/replacing an
+ * extension, revoking a credential, changing a model URL or provider, …) must pass an
+ * EXPLICIT operator decision before it happens. This module is the standalone state
+ * machine for that flow; it deliberately owns no host wiring and no I/O:
+ *
+ *   pending ──approve──▶ approved ──commit()──▶ committed   (terminal)
+ *      │                     │
+ *      ├──deny──▶ denied    └── TTL ──▶ expired              (terminal)
+ *      └── TTL ──▶ expired
+ *
+ * Properties this module guarantees:
+ * - **No commit without an approval.** `commit()` on a pending request throws
+ *   `approval/pending` SYNCHRONOUSLY; there is no promise to await, so a deployment
+ *   with no approval UI fails promptly instead of hanging.
+ * - **One-shot commit.** The first successful commit moves the record to
+ *   `committed`; every later commit throws `approval/already-committed`.
+ * - **Idempotent decisions.** Repeating the SAME decision returns the unchanged
+ *   record (including its original decision timestamp); the opposite decision after a
+ *   decision is `approval/already-decided`.
+ * - **Scope-bound.** The request stores the exact decision scope; a commit must name
+ *   exactly that scope. An approval for one extension or one tool cannot authorize
+ *   another.
+ * - **TTL on an injected clock.** Expiry is evaluated lazily on every read/mutation
+ *   against `now()`; tests never depend on wall time.
+ * - **Plain-JSON durable-safe state.** Records contain only strings, numbers, nulls,
+ *   booleans and one nested scope object. Unknown caller fields are dropped, so a
+ *   token or API key passed by mistake is never stored or re-serialized.
+ * - **Deterministic ids.** By default the id is a hash of the request content and the
+ *   injected request time, so the same request at the same instant has the same id.
+ *
+ * @module @try-works/dsh-tool-mode/approval
+ */
+/** Every management-sensitive request kind this module admits. */
+export declare const APPROVAL_KINDS: readonly ["model-enable", "model-disable", "model-reset", "extension-install", "extension-activate", "extension-deactivate", "extension-uninstall", "extension-prepare", "extension-commit", "extension-rollback", "credential-revoke", "model-url-change", "model-provider-change"];
+/** The management-sensitive request kind. */
+export type ApprovalKind = (typeof APPROVAL_KINDS)[number];
+/** The terminal/non-terminal states a record can be in. */
+export declare const APPROVAL_STATES: readonly ["pending", "approved", "denied", "committed", "expired"];
+/** One state of an approval record. */
+export type ApprovalState = (typeof APPROVAL_STATES)[number];
+/** What an approval is scoped to. */
+export declare const APPROVAL_SCOPE_KINDS: readonly ["model", "extension", "tool", "credential", "provider"];
+/** The kind of subject an approval covers. */
+export type ApprovalScopeKind = (typeof APPROVAL_SCOPE_KINDS)[number];
+/** The exact subject an approval covers. */
+export interface ApprovalScope {
+    /** The subject kind (model, extension, tool, credential or provider). */
+    readonly kind: ApprovalScopeKind;
+    /** The subject identity, for example `@try-works/extension-laya` or `lang_detect`. */
+    readonly id: string;
+}
+/** The caller-supplied part of a request. */
+export interface ApprovalRequestInput {
+    /** What management operation the approval would allow. */
+    readonly kind: ApprovalKind;
+    /** The exact subject the approval is bound to. */
+    readonly scope: ApprovalScope;
+    /** Operator identity recorded with the request (never a secret). */
+    readonly operator: string;
+    /** Why the operator wants the change; recorded verbatim (never a secret). */
+    readonly reason: string;
+    /** Optional lifetime; defaults to the store's `defaultTtlMs`. */
+    readonly ttlMs?: number;
+}
+/** One explicit operator decision. */
+export interface ApprovalDecision {
+    /** `true` approves, `false` denies. */
+    readonly approve: boolean;
+    /** Who decided. */
+    readonly decidedBy: string;
+    /** Optional decision note. */
+    readonly reason?: string;
+}
+/** The plain-JSON record every method returns and the snapshot stores. */
+export interface ApprovalRecord {
+    readonly id: string;
+    readonly kind: ApprovalKind;
+    readonly scope: ApprovalScope;
+    readonly operator: string;
+    readonly reason: string;
+    readonly requestedAt: number;
+    readonly expiresAt: number;
+    readonly state: ApprovalState;
+    readonly decidedAt: number | null;
+    readonly decidedBy: string | null;
+    readonly decisionReason: string | null;
+    readonly committedAt: number | null;
+}
+/** The durable snapshot produced by {@link ApprovalStore.toJSON}. */
+export interface ApprovalSnapshot {
+    readonly version: 1;
+    readonly defaultTtlMs: number;
+    readonly records: readonly ApprovalRecord[];
+}
+/** The call-time dependencies, all injectable for tests. */
+export interface ApprovalStoreOptions {
+    /** The clock; defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Lifetime used when a request carries no `ttlMs`; defaults to five minutes. */
+    readonly defaultTtlMs?: number;
+    /** Deterministic id derivation; defaults to a sha256 of the request and time. */
+    readonly idFactory?: (input: {
+        readonly kind: ApprovalKind;
+        readonly scope: ApprovalScope;
+        readonly operator: string;
+        readonly reason: string;
+    }, requestedAt: number) => string;
+}
+/** The named refusals this module can raise. */
+export type ApprovalErrorCode = 'approval/invalid-request' | 'approval/invalid-serialization' | 'approval/unknown-id' | 'approval/pending' | 'approval/denied' | 'approval/expired' | 'approval/already-decided' | 'approval/already-committed' | 'approval/scope-mismatch';
+/** A refusal with a stable machine-readable code. */
+export declare class ApprovalError extends Error {
+    /** The stable refusal code. */
+    readonly code: ApprovalErrorCode;
+    /**
+     * @param code - the stable refusal code.
+     * @param message - the concrete explanation (the code is prefixed).
+     */
+    constructor(code: ApprovalErrorCode, message: string);
+}
+/**
+ * The in-memory approval store. One instance per host process, restored from its
+ * snapshot at boot (see the wiring contract in the task report).
+ */
+export declare class ApprovalStore {
+    #private;
+    /**
+     * @param options - clock, default TTL and id derivation (all injectable).
+     */
+    constructor(options?: ApprovalStoreOptions);
+    /** The default lifetime new requests receive. */
+    get defaultTtlMs(): number;
+    /**
+     * Record a pending request.
+     *
+     * A repeated request (same content at the same injected instant) returns the
+     * EXISTING record rather than resetting its TTL or decision.
+     * @param input - the request facts (kind, scope, operator, reason, optional TTL).
+     * @returns the pending record (a plain-JSON copy).
+     */
+    request(input: ApprovalRequestInput): ApprovalRecord;
+    /**
+     * Read one record, applying lazy TTL expiry.
+     * @param id - the approval id.
+     * @returns the record (a plain-JSON copy).
+     */
+    describe(id: string): ApprovalRecord;
+    /** Every record, oldest first (expiry applied). */
+    list(): readonly ApprovalRecord[];
+    /**
+     * Apply an explicit operator decision.
+     *
+     * Repeating the SAME decision is idempotent and returns the unchanged record; the
+     * opposite decision after a decision is `approval/already-decided`.
+     * @param id - the approval id.
+     * @param decision - approve/deny, the decider and an optional note.
+     * @returns the decided record.
+     */
+    decide(id: string, decision: ApprovalDecision): ApprovalRecord;
+    /**
+     * Consume an approved request for exactly its recorded scope.
+     *
+     * One-shot: the first successful call commits; every later call (and any call on a
+     * pending, denied or expired record) throws a named error WITHOUT waiting.
+     * @param id - the approval id.
+     * @param scope - the exact subject the caller is about to mutate.
+     * @returns the committed record.
+     */
+    commit(id: string, scope: ApprovalScope): ApprovalRecord;
+    /**
+     * The durable snapshot. Only the declared fields are serialized, so a caller that
+     * passed a token by mistake cannot leak it through this channel.
+     * @returns a plain-JSON snapshot.
+     */
+    toJSON(): ApprovalSnapshot;
+    /**
+     * Restore a store from {@link toJSON} output.
+     * @param value - the parsed snapshot.
+     * @param options - clock, optional TTL override and optional id factory.
+     * @returns the restored store.
+     */
+    static fromJSON(value: unknown, options?: ApprovalStoreOptions): ApprovalStore;
+}
+/** Whether a restored/default id has the module's deterministic shape. */
+export declare function isDeterministicApprovalId(id: unknown): boolean;
+//# sourceMappingURL=approval.d.ts.map

package/lib/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"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"}