stitchkit 0.99.0 → 0.100.0

package/dist/{index-1m2thnq0.js → index-y9qn426m.js}

@@ -10,7 +10,7 @@ import {
   AgentStoredRunSchema,
   appendEventIn,
   createAgentRuntimeStore
-} from "./index-wsm5w4ee.js";
+} from "./index-0b1cnze2.js";
 import {
   AgentRecoverableDescriptorSchema,
   AgentRecoverablePageSchema,
@@ -18,7 +18,7 @@ import {
   AgentStoreEventPageSchema,
   AppendAgentStoreEventSchema,
   canonicalAgentJson
-} from "./index-gxrt5h6v.js";
+} from "./index-cyktc4bp.js";
 import {
   AgentMessageSchema,
   AgentRunSchema

package/dist/index-zjjyynm3.js

@@ -0,0 +1,42 @@
+// src/internal/darwin-binding.ts
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function hasFunctions(value, names) {
+  return typeof value === "object" && value !== null && names.every((name) => typeof Reflect.get(value, name) === "function");
+}
+var darwinBinding;
+function loadDarwinBinding() {
+  if (darwinBinding)
+    return darwinBinding;
+  const directory = path.dirname(fileURLToPath(import.meta.url));
+  const binary = `darwin-${process.arch}.node`;
+  const candidates = [
+    path.resolve(directory, "../native", binary),
+    path.resolve(directory, "../../native", binary)
+  ];
+  const selected = candidates.find((candidate) => existsSync(candidate));
+  if (!selected) {
+    throw new Error(`Contained filesystem operations need the packaged Darwin ${process.arch} backend`);
+  }
+  const loaded = createRequire(import.meta.url)(selected);
+  const methods = [
+    "openDirectoryAt",
+    "openFileAt",
+    "createFileAt",
+    "createDirectoryAt",
+    "statAt",
+    "listAt",
+    "renameAt",
+    "unlinkAt",
+    "processIdentity"
+  ];
+  if (!hasFunctions(loaded, methods)) {
+    throw new Error("The packaged Darwin contained-files backend has an invalid surface");
+  }
+  darwinBinding = loaded;
+  return darwinBinding;
+}
+
+export { loadDarwinBinding };

package/dist/internal/coalesced-task.d.ts

@@ -0,0 +1,15 @@
+import { type BackoffPolicy } from './backoff.js';
+export interface CoalescedTask {
+    readonly running: boolean;
+    trigger(): void;
+    pauseRetry(): void;
+    close(): void;
+}
+/** One job per key; hints during work become one trailing pass, failures retain retry. */
+export declare function createCoalescedTask(config: {
+    run(): Promise<void>;
+    active(): boolean;
+    onError(error: unknown): void;
+    backoff: BackoffPolicy;
+}): CoalescedTask;
+//# sourceMappingURL=coalesced-task.d.ts.map

package/dist/internal/coalesced-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalesced-task.d.ts","sourceRoot":"","sources":["../../src/internal/coalesced-task.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,WAAW,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,OAAO,IAAI,IAAI,CAAC;IAChB,UAAU,IAAI,IAAI,CAAC;IACnB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,0FAA0F;AAC1F,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,MAAM,IAAI,OAAO,CAAC;IAClB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,aAAa,CAAC;CACxB,GAAG,aAAa,CAoDhB"}

package/dist/internal/darwin-binding.d.ts

@@ -0,0 +1,19 @@
+export interface DarwinEntry {
+    name: string;
+    mode: number;
+    size: number;
+}
+export interface DarwinBinding {
+    processIdentity(pid: number): unknown;
+    openDirectoryAt(directory: number, name: string): number;
+    openFileAt(directory: number, name: string): number;
+    createFileAt(directory: number, name: string, mode: number): number;
+    createDirectoryAt(directory: number, name: string, mode: number): boolean;
+    statAt(directory: number, name: string): Omit<DarwinEntry, 'name'> | null;
+    listAt(directory: number): readonly DarwinEntry[];
+    renameAt(directory: number, source: string, target: string): void;
+    unlinkAt(directory: number, name: string): void;
+}
+export declare function hasFunctions(value: unknown, names: readonly string[]): boolean;
+export declare function loadDarwinBinding(): DarwinBinding;
+//# sourceMappingURL=darwin-binding.d.ts.map

package/dist/internal/darwin-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"darwin-binding.d.ts","sourceRoot":"","sources":["../../src/internal/darwin-binding.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpD,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACpE,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,WAAW,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM9E;AAID,wBAAgB,iBAAiB,IAAI,aAAa,CAgCjD"}

package/dist/internal/exclusive-lock.d.ts

@@ -1,15 +1,27 @@
+import { z } from 'zod';
+import { type ProcessOwnerEvidence } from './process-instance.js';
 /** Who holds a lock, as its file records it. */
-export interface ExclusiveLockOwner {
-    readonly pid: number;
-    readonly host: string;
-    readonly acquiredAt: string;
-    /** Stable machine identity; absent where the platform offers none, and in older locks. */
-    readonly machine?: string;
-}
+declare const ExclusiveLockOwnerSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    host: z.ZodString;
+    acquiredAt: z.ZodString;
+    machine: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    process: z.ZodCatch<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        platform: z.ZodEnum<{
+            darwin: "darwin";
+            linux: "linux";
+        }>;
+        bootId: z.ZodString;
+        namespace: z.ZodString;
+        startId: z.ZodString;
+    }, z.core.$strict>>>>;
+}, z.core.$strip>;
+export type ExclusiveLockOwner = z.infer<typeof ExclusiveLockOwnerSchema>;
 /** Why a present lock was not taken. */
 export interface ExclusiveLockDiagnosis {
     readonly attribution: 'this-machine' | 'another-machine' | 'unattributable';
     readonly liveness: 'alive' | 'gone' | 'not-probed';
+    readonly identity?: ProcessOwnerEvidence['identity'];
     readonly owner: ExclusiveLockOwner | null;
 }
 /** A lock this process holds. */
@@ -48,4 +60,5 @@ export type ExclusiveLockAttempt = {
 export declare function attemptExclusiveLock(path: string, options: ExclusiveLockAttemptOptions): Promise<ExclusiveLockAttempt>;
 /** Read the owner a present lock records, for a refusal that has to name it. */
 export declare function readExclusiveLockOwner(path: string): Promise<ExclusiveLockOwner | null>;
+export {};
 //# sourceMappingURL=exclusive-lock.d.ts.map

package/dist/internal/exclusive-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/exclusive-lock.ts"],"names":[],"mappings":"AA8BA,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC3C;AAED,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IACE,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AAsLN;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAe/B;AAED,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAEpC"}
+{"version":3,"file":"exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/exclusive-lock.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,oBAAoB,CAAC;AAK5B,gDAAgD;AAChD,QAAA,MAAM,wBAAwB;;;;;;;;;;;;;;iBAO5B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC3C;AAED,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,uFAAuF;IACvF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IACE,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AAmLN;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAe/B;AAED,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAEpC"}

package/dist/internal/mutation-queue.d.ts

@@ -0,0 +1,4 @@
+/** FIFO mutations with caller-visible failures and an optional finite admission bound. */
+export type MutationQueue = <T>(mutation: () => Promise<T>) => Promise<T>;
+export declare function createMutationQueue(maxPending?: number): MutationQueue;
+//# sourceMappingURL=mutation-queue.d.ts.map

package/dist/internal/mutation-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-queue.d.ts","sourceRoot":"","sources":["../../src/internal/mutation-queue.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAE1E,wBAAgB,mBAAmB,CAAC,UAAU,SAA2B,GAAG,aAAa,CAwBxF"}

package/dist/internal/process-identity.d.ts

@@ -29,7 +29,7 @@ export declare function machineIdentity(declared: string | undefined): Promise<s
  * carries the ordinary doubt about reuse. Found by a consuming application, which measured `Z` and a
  * successful signal on both platforms of its fleet. → ADR 0147.
  */
-export declare function probeLiveness(pid: number): Promise<'alive' | 'gone'>;
+export declare function probeLiveness(pid: number, reach?: (target: number) => true): Promise<'alive' | 'gone'>;
 /**
  * The state letter of a pid, or `null` where this platform will not say.
  *

package/dist/internal/process-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-identity.d.ts","sourceRoot":"","sources":["../../src/internal/process-identity.ts"],"names":[],"mappings":"AA8CA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,SAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBtF;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW1F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAY1E;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,OAAO,CAAC,OAAO,CAAC,CAuBlB"}
+{"version":3,"file":"process-identity.d.ts","sourceRoot":"","sources":["../../src/internal/process-identity.ts"],"names":[],"mappings":"AA8CA;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,SAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBtF;AAED,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW1F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,KAAK,YAAY,MAAM,SAA4B,GAClD,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAY3B;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,OAAO,CAAC,OAAO,CAAC,CAuBlB"}

package/dist/internal/process-instance.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+import { probeLiveness } from './process-identity.js';
+export declare const ProcessInstanceSchema: z.ZodObject<{
+    platform: z.ZodEnum<{
+        darwin: "darwin";
+        linux: "linux";
+    }>;
+    bootId: z.ZodString;
+    namespace: z.ZodString;
+    startId: z.ZodString;
+}, z.core.$strict>;
+export type ProcessInstance = z.infer<typeof ProcessInstanceSchema>;
+/** /proc stat field 22 follows a command name that may itself contain spaces and parentheses. */
+export declare function linuxProcessStart(stat: string, pid: number): string | null;
+/** @internal procRoot permits kernel-format fixtures without changing a real process or boot. */
+export declare function readProcessInstance(pid: number, procRoot?: string): Promise<ProcessInstance | null>;
+export interface ProcessOwnerEvidence {
+    readonly liveness: 'alive' | 'gone' | 'not-probed';
+    readonly identity: 'matched' | 'different-boot' | 'reused-pid' | 'pid-gone' | 'legacy' | 'unavailable';
+}
+/** Compare identities only inside one machine (the caller establishes that boundary). */
+export declare function probeProcessOwner(pid: number, recorded: ProcessInstance | null | undefined, probes?: {
+    read: typeof readProcessInstance;
+    liveness: typeof probeLiveness;
+}): Promise<ProcessOwnerEvidence>;
+//# sourceMappingURL=process-instance.d.ts.map

package/dist/internal/process-instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-instance.d.ts","sourceRoot":"","sources":["../../src/internal/process-instance.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,eAAO,MAAM,qBAAqB;;;;;;;;kBAOvB,CAAC;AACZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS1E;AAED,iGAAiG;AACjG,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,SAAU,GACjB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAwCjC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;IACnD,QAAQ,CAAC,QAAQ,EACb,SAAS,GACT,gBAAgB,GAChB,YAAY,GACZ,UAAU,GACV,QAAQ,GACR,aAAa,CAAC;CACnB;AAED,yFAAyF;AACzF,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC5C,MAAM;IAAK,IAAI;IAAuB,QAAQ;CAAiB,GAC9D,OAAO,CAAC,oBAAoB,CAAC,CAyB/B"}

package/dist/live/watch-client-state.d.ts

@@ -0,0 +1,71 @@
+import type { WatchClientConfig, WatchListeners } from './watch-client.js';
+import { type WatchKey, type WatchStateFrame, type WatchValueFrame } from './watch-contract.js';
+type Listeners<T> = WatchListeners<T>;
+export interface WatchClientEntry {
+    epoch: number;
+    released: boolean;
+    readonly key: WatchKey;
+    readonly args: Record<string, unknown>;
+    readonly listeners: Set<Listeners<unknown>>;
+    revision: number;
+    value?: unknown;
+    hasValue: boolean;
+    /**
+     * The server's identity for the value held, carried back on the next `open`.
+     *
+     * Kept rather than recomputed so that what is offered is what the server
+     * actually said, not this client's opinion of the value it built — if those
+     * two ever disagree, offering the recomputed one would hide the disagreement
+     * and offering the server's one surfaces it as a difference that will not
+     * apply.
+     */
+    fingerprint?: string;
+    /**
+     * Whether the **current** connection has been told about this key.
+     *
+     * On the entry rather than on a handle: two handles asking one question share
+     * a subscription, so the second must not send a second `open` — and a
+     * reconnect has to clear it for both.
+     */
+    opened: boolean;
+    /**
+     * Whether a value frame has answered the latest `open`.
+     *
+     * A revision is a counter of one hub's life of the key, so it orders frames
+     * within one open and says nothing across two: a restarted API starts at 1
+     * again. Until the first answer to an open arrives, the held revision is not
+     * a floor — without this, a client that held revision 40 from the previous
+     * process dropped every full value of the new one as "no newer" until its
+     * counter passed 40, while showing itself live.
+     */
+    answered: boolean;
+    state: WatchStateFrame;
+    release?: ReturnType<typeof setTimeout>;
+}
+export declare function publishState(entry: WatchClientEntry, state: WatchStateFrame): void;
+/**
+ * Tell the server about a key, and turn every way that can fail into a state.
+ *
+ * Nothing here rejects. It runs from a subscribe and from a reconnect, neither
+ * of which has anywhere to put a rejected promise — and a disconnected socket
+ * rejects the request, which is exactly the moment this runs. An unhandled
+ * rejection in a console is also the one outcome that tells the subscriber
+ * nothing at all.
+ */
+export declare function openWatch(config: WatchClientConfig, openTimeoutMs: number, entry: WatchClientEntry): Promise<void>;
+/**
+ * What one value frame does to an entry: a new value, a confirmation of the
+ * held one, a late answer to drop, or a reason the key has to start over.
+ * The entry's revision, value and fingerprint move here and nowhere else.
+ */
+export declare function applyWatchFrame(entry: WatchClientEntry, frame: WatchValueFrame): {
+    kind: 'value';
+    value: unknown;
+} | {
+    kind: 'confirmed' | 'stale';
+} | {
+    kind: 'resync';
+    message: string;
+};
+export {};
+//# sourceMappingURL=watch-client-state.d.ts.map

package/dist/live/watch-client-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-client-state.d.ts","sourceRoot":"","sources":["../../src/live/watch-client-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAG1B,KAAK,SAAS,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;;;;OASG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;CACzC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAGlF;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAsDf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,eAAe,GAEpB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA2DtC"}

package/dist/live/watch-client.d.ts

@@ -1,3 +1,4 @@
+import type { SessionOperation } from '../browser/session.js';
 /**
  * The client half of a watched read.
  *
@@ -44,7 +45,7 @@
  * sense a rendering component can use.
  */
 import type { ContractDef, EndpointDef } from '../contract/define.js';
-import { WATCH_CLOSE, WATCH_OPEN, WATCH_STATE, WATCH_VALUE, type WatchHave, type WatchKey, type WatchStateFrame, type WatchValueFrame } from './watch-contract.js';
+import { WATCH_CLOSE, type WATCH_OPEN, WATCH_STATE, WATCH_VALUE, type WatchHave, type WatchKey, type WatchStateFrame, type WatchValueFrame } from './watch-contract.js';
 export interface WatchListeners<TValue> {
     value(value: TValue): void;
     /** Phase and, when unhealthy, the read's own code and message. */
@@ -125,6 +126,9 @@ export interface WatchTransport {
     onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void;
 }
 export interface WatchClientConfig {
+    readonly session?: SessionOperation<unknown>;
+    readonly maxKeys?: number;
+    readonly maxListenersPerKey?: number;
     readonly transport: WatchTransport;
     /** How long a key's value is retained after its last subscriber. Default 0. */
     readonly holdMs?: number;

package/dist/live/watch-client.d.ts.map

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

package/dist/live/watch-contract.d.ts

@@ -22,6 +22,7 @@ import { z } from 'zod';
 /** The identity of one watched read: an operation plus the arguments it was asked with. */
 export declare const WatchKeySchema: z.ZodReadonly<z.ZodObject<{
     service: z.ZodString;
+    instance: z.ZodOptional<z.ZodString>;
     action: z.ZodString;
     digest: z.ZodString;
 }, z.core.$strict>>;
@@ -43,6 +44,7 @@ export type WatchHave = z.infer<typeof WatchHaveSchema>;
 export declare const WatchOpenSchema: z.ZodReadonly<z.ZodObject<{
     key: z.ZodReadonly<z.ZodObject<{
         service: z.ZodString;
+        instance: z.ZodOptional<z.ZodString>;
         action: z.ZodString;
         digest: z.ZodString;
     }, z.core.$strict>>;
@@ -59,6 +61,7 @@ export declare const WatchAcceptedSchema: z.ZodReadonly<z.ZodObject<{
 export declare const WatchValueSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
     key: z.ZodReadonly<z.ZodObject<{
         service: z.ZodString;
+        instance: z.ZodOptional<z.ZodString>;
         action: z.ZodString;
         digest: z.ZodString;
     }, z.core.$strict>>;
@@ -69,6 +72,7 @@ export declare const WatchValueSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.
 }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
     key: z.ZodReadonly<z.ZodObject<{
         service: z.ZodString;
+        instance: z.ZodOptional<z.ZodString>;
         action: z.ZodString;
         digest: z.ZodString;
     }, z.core.$strict>>;
@@ -80,6 +84,7 @@ export declare const WatchValueSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.
 }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
     key: z.ZodReadonly<z.ZodObject<{
         service: z.ZodString;
+        instance: z.ZodOptional<z.ZodString>;
         action: z.ZodString;
         digest: z.ZodString;
     }, z.core.$strict>>;
@@ -90,6 +95,7 @@ export declare const WatchValueSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.
 export declare const WatchStateSchema: z.ZodReadonly<z.ZodObject<{
     key: z.ZodReadonly<z.ZodObject<{
         service: z.ZodString;
+        instance: z.ZodOptional<z.ZodString>;
         action: z.ZodString;
         digest: z.ZodString;
     }, z.core.$strict>>;
@@ -131,6 +137,7 @@ export declare const watchContract: {
             readonly args: z.ZodTuple<[z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
                 key: z.ZodReadonly<z.ZodObject<{
                     service: z.ZodString;
+                    instance: z.ZodOptional<z.ZodString>;
                     action: z.ZodString;
                     digest: z.ZodString;
                 }, z.core.$strict>>;
@@ -141,6 +148,7 @@ export declare const watchContract: {
             }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
                 key: z.ZodReadonly<z.ZodObject<{
                     service: z.ZodString;
+                    instance: z.ZodOptional<z.ZodString>;
                     action: z.ZodString;
                     digest: z.ZodString;
                 }, z.core.$strict>>;
@@ -152,6 +160,7 @@ export declare const watchContract: {
             }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
                 key: z.ZodReadonly<z.ZodObject<{
                     service: z.ZodString;
+                    instance: z.ZodOptional<z.ZodString>;
                     action: z.ZodString;
                     digest: z.ZodString;
                 }, z.core.$strict>>;
@@ -164,6 +173,7 @@ export declare const watchContract: {
             readonly args: z.ZodTuple<[z.ZodReadonly<z.ZodObject<{
                 key: z.ZodReadonly<z.ZodObject<{
                     service: z.ZodString;
+                    instance: z.ZodOptional<z.ZodString>;
                     action: z.ZodString;
                     digest: z.ZodString;
                 }, z.core.$strict>>;
@@ -193,6 +203,7 @@ export declare const watchContract: {
             readonly args: z.ZodTuple<[z.ZodReadonly<z.ZodObject<{
                 key: z.ZodReadonly<z.ZodObject<{
                     service: z.ZodString;
+                    instance: z.ZodOptional<z.ZodString>;
                     action: z.ZodString;
                     digest: z.ZodString;
                 }, z.core.$strict>>;
@@ -211,6 +222,7 @@ export declare const watchContract: {
             readonly args: z.ZodTuple<[z.ZodReadonly<z.ZodObject<{
                 key: z.ZodReadonly<z.ZodObject<{
                     service: z.ZodString;
+                    instance: z.ZodOptional<z.ZodString>;
                     action: z.ZodString;
                     digest: z.ZodString;
                 }, z.core.$strict>>;

package/dist/live/watch-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watch-contract.d.ts","sourceRoot":"","sources":["../../src/live/watch-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,2FAA2F;AAC3F,eAAO,MAAM,cAAc;;;;mBAkBd,CAAC;AACd,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;mBAGf,CAAC;AACd,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,eAAe;;;;;;;;;;;kBAEf,CAAC;AAEd,eAAO,MAAM,mBAAmB;;;mBAOnB,CAAC;AA6Bd,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAmB3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;kBAShB,CAAC;AAEd,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE/D,eAAO,MAAM,UAAU,yBAAyB,CAAC;AACjD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;qBAEL,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBACJ,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAGL,IAAI;;;;;;;;;;;;qBAA8B,GAAG;;;;;;qBACpC,IAAI;;;;;;;;;CAKxB,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEpD"}
+{"version":3,"file":"watch-contract.d.ts","sourceRoot":"","sources":["../../src/live/watch-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,2FAA2F;AAC3F,eAAO,MAAM,cAAc;;;;;mBAoBd,CAAC;AACd,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;mBAGf,CAAC;AACd,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,eAAe;;;;;;;;;;;;kBAEf,CAAC;AAEd,eAAO,MAAM,mBAAmB;;;mBAOnB,CAAC;AA6Bd,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAmB3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;kBAShB,CAAC;AAEd,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE/D,eAAO,MAAM,UAAU,yBAAyB,CAAC;AACjD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,WAAW,0BAA0B,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;qBAEL,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBACJ,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAGL,IAAI;;;;;;;;;;;;;qBAA8B,GAAG;;;;;;qBACpC,IAAI;;;;;;;;;;CAKxB,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CAEpD"}

package/dist/react/cache-bridge.d.ts

@@ -1,3 +1,6 @@
+import type { SessionOperation } from '../browser/session.js';
+import type { WatchHandle } from '../live/watch-client.js';
+import type { WatchStateFrame } from '../live/watch-contract.js';
 /**
  * Cache bridge — wire socket events into the TanStack Query cache.
  *
@@ -30,7 +33,14 @@ export type CacheBridgeHandler<TPayload> = (data: TPayload, ctx: CacheBridgeCont
 export type CacheBridgeHandlers<TEvents> = {
     [K in keyof TEvents & string]?: CacheBridgeHandler<EventPayload<TEvents[K]>>;
 };
+export interface WatchCacheBinding {
+    readonly handle: WatchHandle<unknown>;
+    readonly queryKey: QueryKey;
+    readonly state?: (state: WatchStateFrame) => void;
+}
 export interface CacheBridgeConfig<TEvents> {
+    readonly watched?: readonly WatchCacheBinding[];
+    readonly session?: SessionOperation<unknown>;
     socket: CacheBridgeSocket<TEvents>;
     /**
      * The TanStack Query client, or a thunk returning it. A thunk is resolved

package/dist/react/cache-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-bridge.d.ts","sourceRoot":"","sources":["../../src/react/cache-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEnE,wEAAwE;AACxE,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACzF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAElE,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;CACjF;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,gFAAgF;IAChF,OAAO,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC;CACjC;AAED,oEAAoE;AACpE,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3E,MAAM,MAAM,kBAAkB,CAAC,QAAQ,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAE7F,MAAM,MAAM,mBAAmB,CAAC,OAAO,IAAI;KACxC,CAAC,IAAI,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,EAAE,kBAAkB,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7E,CAAC;AAEF,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnC;;;;;OAKG;IACH,WAAW,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,CAAC;IAC/C,QAAQ,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACvC,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,IAAI,IAAI,CAAC;IAChB,UAAU,IAAI,IAAI,CAAC;IACnB;qEACiE;IACjE,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,2EAA2E;IAC3E,UAAU,IAAI,IAAI,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB,CAAC,QAAQ,SAAS,qBAAqB,CAC/E,SAAQ,IAAI,CAAC,iBAAiB,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC;IAC1E,MAAM,EAAE,uBAAuB,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;CAClE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,WAAW,CAsF1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,SAAS,qBAAqB,EAC9E,MAAM,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC1C,WAAW,CAKb"}
+{"version":3,"file":"cache-bridge.d.ts","sourceRoot":"","sources":["../../src/react/cache-bridge.ts"],"names":[],"mappings":"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"}

package/llms/agent-runtime.2.txt

@@ -772,3 +772,97 @@ first mutation**, so an adapter whose runtime rows reference an application-owne
 can provision those parents; the optional `cleanup(context)` removes them again, and runs once
 whether the scenario passed or failed. A factory that owns no fixture state ignores the argument and
 keeps working unchanged.
+
+## Plain completions and shared invocation receipts
+
+Use `createModelInvocationLedger` from `stitchkit/agent-runtime` when a direct text
+completion and an agent must share causal provider evidence. It uses the existing
+runtime store, not a second database. The completion path sends exactly one user
+prompt, no framework instructions and no tools. It never starts an agent loop.
+
+```ts
+import { createModelInvocationLedger } from 'stitchkit/agent-runtime';
+
+const invocations = createModelInvocationLedger({
+  store, // the same AgentRuntimeStore object passed to createAgentRuntime
+  models, // an existing defineModelRegistry result
+  payloadKey, // 32 bytes from the host's secret store; retain separately from archives
+  authorize: async ({ context, conversationId, action, trace }) => {
+    const session = await authenticate(context);
+    await authorizeConversation(session, conversationId, action, trace);
+    return { subject: session.subject }; // verified identity, never a body field
+  },
+});
+
+const completion = await invocations.complete({
+  conversationId: 'evaluation-42',
+  idempotencyKey: 'summary-case-3',
+  trace: {
+    operationId: 'summary-42', purpose: 'summarize', project: 'example',
+    parent: { traceId: 'trace-42' }, experiment: 'evaluation', case: 'case-3',
+  },
+  prompt: 'Summarize these supplied facts.',
+  models: ['primary', 'fallback'], // registry keys; repeat a key for an explicit retry
+  settings: { maxOutputTokens: 500 },
+  timeoutMs: 30_000,
+}, authenticatedContext);
+
+// Add to the existing createAgentRuntime configuration:
+const receiptConfig = {
+  ledger: invocations,
+  trace: ({ run }) => ({
+    operationId: run.id, purpose: 'assistant-turn', project: 'example',
+  }),
+};
+// createAgentRuntime({ ...existingConfig, invocations: receiptConfig });
+
+const page = await invocations.read({
+  conversationId: 'evaluation-42', limit: 100,
+}, authenticatedContext);
+// Continue with fromSeq: page.nextSeq while it is defined.
+```
+
+`complete` returns `invocationId`, `outcome` and, on success, `text`. `duplicate`
+returns the existing ID without provider execution or replaying plaintext. Changed
+input, trace or caller under the same key is a conflict. Model attempts are explicit
+and bounded to eight; SDK retries are disabled. Only provider failures trigger the
+next attempt. Abort, audit refusal and configuration errors do not. An admitted call
+whose process died stays claimed: inspect the receipt before choosing a new key.
+
+The agent retains its existing prompt, tools and loop. Both modes produce
+`invocation/started`, `provider/request`, `provider/response` and
+`invocation/finished` records through `read`. Each attempt has its own ID; response
+usage is counted once and keeps `unavailable` distinct from measured zero. Requested
+registry selection, sent adapter identity and effective provider identity are
+separate. Effective identity is null when not reported. A gateway's hidden retries
+are not visible as additional attempts.
+
+`currentModelInvocationAttempt()` returns the causal context inside a provider's
+`fetch` callback or streamed read. Use it to join a host transport audit to
+`operationId`, `invocationId`, `attemptId`, optional `runId` and `step`.
+`onAttempt` is an awaited admission hook; a rejected hook prevents the provider call.
+SDK payload hashes are not represented as hashes of HTTP wire bytes.
+
+Prompts and output are AES-256-GCM payload artifacts. `read` returns references and
+hashes; `readPayload({ conversationId, artifactId }, context)` separately authorizes
+`read-payload` and checks authentication tags and hashes. `payloadKey` must be 32
+bytes and is copied at construction. Keep it outside the event store/backups; retain
+the appropriate key when restoring an archive. `maxPayloadBytes` defaults to 4 MiB
+(range 1 KiB–64 MiB); streaming output evidence is capped at 1 MiB. Request headers
+are excluded. Protect existing agent history independently: enabling receipts does
+not encrypt its ordinary conversation records.
+
+The built-in memory and SQLite stores implement `appendEventOnce`. Custom stores
+must implement its once-only check and append atomically, returning the original
+event on a duplicate key scoped by conversation and kind. A factory without this
+capability refuses receipt setup. The driver-backed implementation reads bounded
+pages under one transaction, without another table or database.
+
+### Migration from direct SDK completions
+
+**Who must act:** applications opting into shared completion/agent receipts.
+Replace the direct `generateText` call with `invocations.complete`, configure host
+authorization and a retained payload key, and pass the same ledger in the agent's
+`invocations` option. Use the returned invocation ID and the paginated `read` method
+for receipt queries; do not import runtime internals. This API is unreleased; it is
+not present in 0.99.0. Existing runtime configurations need no migration.

package/llms/agent-runtime.3.txt

@@ -266,6 +266,30 @@ Managed effects and operator telemetry additionally export `AgentToolFenceConfig
 may accompany checkpoint/terminal writes and tool context; internal causes are redacted unless an
 operator-only observability sink explicitly opts in.
 
+### Completion and agent invocation receipts
+
+`createModelInvocationLedger` constructs a `ModelInvocationLedger` from
+`ModelInvocationConfig`: the existing store and model registry, a 32-byte payload
+key, required host authorization, optional bounded payload size and `onAttempt`.
+`complete(input, context, signal?)` executes only the supplied prompt, with no tools
+or framework instructions; repeated keys return the existing invocation ID.
+`read(input, context)` returns a bounded event page shared by agent and completion;
+`readPayload(input, context)` requires a separate authorization action to decrypt
+one protected artifact. See the [guide and migration example](../guide/agent-runtime.md#plain-completions-and-shared-invocation-receipts).
+
+| Export | Kind | Purpose |
+| --- | --- | --- |
+| `CompletionInvocationInputSchema` / `CompletionInvocationInput` | schema/type | strict prompt, model-attempt list, deadline, idempotency key and trace input |
+| `ModelInvocationTraceSchema` / `ModelInvocationTrace` | schema/type | operation, purpose, project, parent trace and optional experiment/case/profile |
+| `ModelInvocationRecordSchema` / `ModelInvocationRecord` | schema/type | discriminated invocation start/finish and per-attempt requested/sent/effective evidence |
+| `ModelInvocationAttemptContext` | type | conversation, operation, invocation, attempt, step and optional agent run identity |
+| `currentModelInvocationAttempt` | function | returns causal IDs inside the provider transport; undefined outside an invocation |
+
+The runtime `invocations` option takes this ledger and a trace callback; it requires
+the same store and preserves the existing tool loop. `AgentRuntimeStore.appendEventOnce`
+is an optional atomic capability required by receipt admission. Built-in stores
+supply it; custom adapters must honor its once-only transaction contract.
+
 ==============================================================================
 # API reference: `stitchkit-tui`  (docs/api/reference.md)
 ==============================================================================