stitchkit 0.99.0 → 0.100.1

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/dist/server/realtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/server/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,wBAAwB,CACvC,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB,EAC7C,KAAK,GAAG,GAAG;IAEX;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACrE,MAAM,EAAE,uBAAuB,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IAClE,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,cAAc,CAC7B,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB,EAC7C,KAAK,GAAG,GAAG;IAEX,YAAY,CACV,OAAO,EAAE,CACP,UAAU,EAAE,wBAAwB,CAAC,eAAe,EAAE,eAAe,EAAE,KAAK,CAAC,KAC1E,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACxB,MAAM,IAAI,CAAC;IACd,IAAI,EAAE,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9E,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,oBAAoB,CAAC,KAAK,GAAG,GAAG;IAC/C,EAAE,EAAE,cAAc,CAAC,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;CAC7E;AAED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,GAAG,GAAG,EAEX,QAAQ,EAAE,gBAAgB,CAAC,eAAe,EAAE,eAAe,CAAC,EAC5D,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,EACnC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,yBAAyB,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,GAC9E,cAAc,CAAC,eAAe,EAAE,eAAe,EAAE,KAAK,CAAC,CAwCzD"}
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../src/server/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,yBAAyB,EAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,wBAAwB,CACvC,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB,EAC7C,KAAK,GAAG,GAAG;IAEX;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACrE,MAAM,EAAE,uBAAuB,CAAC,eAAe,EAAE,eAAe,CAAC,CAAC;IAClE,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,cAAc,CAC7B,eAAe,SAAS,qBAAqB,EAC7C,eAAe,SAAS,qBAAqB,EAC7C,KAAK,GAAG,GAAG;IAEX,YAAY,CACV,OAAO,EAAE,CACP,UAAU,EAAE,wBAAwB,CAAC,eAAe,EAAE,eAAe,EAAE,KAAK,CAAC,KAC1E,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACxB,MAAM,IAAI,CAAC;IACd,IAAI,EAAE,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9E,EAAE,CACA,IAAI,EAAE,MAAM,GACX,IAAI,CAAC,uBAAuB,CAAC,qBAAqB,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,oBAAoB,CAAC,KAAK,GAAG,GAAG;IAC/C,EAAE,EAAE,cAAc,CAAC,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;CAC7E;AAED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,CAAC,eAAe,SAAS,qBAAqB,EACnD,KAAK,GAAG,GAAG,EAEX,QAAQ,EAAE,gBAAgB,CAAC,eAAe,EAAE,eAAe,CAAC,EAC5D,MAAM,EAAE,oBAAoB,CAAC,KAAK,CAAC,EACnC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,yBAAyB,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAAO,GAC9E,cAAc,CAAC,eAAe,EAAE,eAAe,EAAE,KAAK,CAAC,CAyDzD"}

package/llms/agent-runtime.2.txt

@@ -772,3 +772,105 @@ 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 keeps parts up to half of it; past
+that the evidence carries `truncated: { parts, sha256 }` over the whole stream, and
+the answer itself is never cut. A receipt that cannot be written never changes an
+outcome: `complete()` returns it with `receiptError` beside it, and a succeeded
+answer keeps its `text`. 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 finds the keyed
+event by its identity through the driver's optional `events.find` — one index probe
+in SQLite — so admission costs the same on a long conversation as on a new one; a
+custom driver without `find` falls back to paging the log in one transaction.
+`store.findEventOnce({ conversationId, kind, key })` reads the same event back.
+Invocation payload artifacts are keyed by their artifact id the same way.
+
+### 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. Available since 0.100.0;
+existing runtime configurations need no migration.

package/llms/agent-runtime.3.txt

@@ -111,7 +111,7 @@ Server-only optional application runtime. See the
 | `AgentSandboxProcess` / `AgentSandboxOutputStream` | _types_ | structural child/output interface for optional lifecycle-owned `AgentProcessSandbox.spawn`, without Node ambient type dependencies |
 | `AgentEventSearchResultSchema` / `AgentEventSearchResult` / `createSqliteAgentEventSearch` / `createAgentEventSearchTools` | schema / _type_ / functions | authorized FTS5 search with exact event addresses and `session_*` tools |
 | `createSqliteAgentSpillStore` | function | durable content-address-checked artifact storage, bounded read/search, retention facts and archive participation |
-| `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `AgentScheduleDeliveryOutcomeSchema` / `AgentScheduleDeliveryOutcome` / `createAgentScheduleService` / `createAgentScheduleTools` | schemas / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, indexed retry eligibility, typed retry/terminal failure, bounded dispatch and fenced stable occurrence identity (ADR 0202) |
+| `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `AgentScheduleDeliveryOutcomeSchema` / `AgentScheduleDeliveryOutcome` / `createAgentScheduleService` / `createAgentScheduleTools` | schemas / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, indexed retry eligibility, typed retry/terminal failure (any other returned value delivers), `maxAttempts` (default 1000) per occurrence — a one-off ends `failed`, a recurring schedule skips to its next slot — bounded dispatch and fenced stable occurrence identity (ADR 0202) |
 | `AgentChildBudgetSchema` / `AgentChildBudget` / `AgentChildStateSchema` / `AgentChildState` / `AgentChildRecordSchema` / `AgentChildRecord` | schema / _type_ | durable child graph, bounded seed and measured budget state |
 | `AgentChildBlockingKindSchema` / `AgentChildBlockingKind` / `AgentChildBlockingSourceSchema` / `AgentChildBlockingSource` / `AgentChildBlockingEventSchema` / `AgentChildBlockingEvent` / `AgentChildBlockingDecision` | schemas / _types_ | parent-owned request identities; responses discriminate approval decisions from JSON input values |
 | `AgentChildHandle` / `AgentChildManager` / `SqliteAgentChildManagerConfig` / `createSqliteAgentChildManager` / `createAgentChildTools` / `agentChildBudgetStopPolicy` | _type_ / functions | host execution port, child lifecycle, cascade (given to `createAgentRuntime` as `children`), messaging, Agent tools, and the child runtime's own budget stop policy — `recordStepUsage` at every step boundary, `policy_stop` as `child-budget` when spent |
@@ -266,6 +266,35 @@ 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. It
+resolves `{ invocationId, outcome, text?, receiptError? }`: `receiptError` says a
+receipt could not be written and never changes `outcome` or drops `text`.
+`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, and
+`AgentRuntimeStore.findEventOnce` reads the event it wrote by kind and key. Built-in
+stores supply both; custom adapters must honor the once-only transaction contract.
+A driver's optional `events.find(transaction, { conversationId, eventId })` makes
+both one lookup instead of a scan of the conversation log.
+
 ==============================================================================
 # API reference: `stitchkit-tui`  (docs/api/reference.md)
 ==============================================================================

package/llms/agent-runtime.txt

@@ -19,7 +19,7 @@ description: Configure Stitchkit's optional durable history, stream loop, run co
 type: architecture
 status: active
 created: 2026-08-22
-updated: 2026-09-26 16:00 +07:00
+updated: 2026-09-28 18:39 +07:00
 ---
 
 # Agent application runtime
@@ -636,9 +636,14 @@ has invoked a tool is never automatically replayed.
 `createAgentScheduleService` persists `at`, `after` and `every` input. Repeating
 schedules require an explicit IANA time zone. Dispatch uses a stable
 `schedule:<id>:<occurrence>` idempotency key, and restart lateness is recorded.
-Resolve `void` after durable admission; return `{ status: 'retry', reason }` for a
+Resolve after durable admission; return `{ status: 'retry', reason }` for a
 transient refusal or `{ status: 'terminal', reason }` to stop the entire schedule in
-`failed` state. Throws retry too. Backoff is 1, 2, 4, 8, 16, 32, then 60 seconds,
+`failed` state. Only those two shapes are failures: any other returned value — a
+queue length, a receipt — means the callback returned, so it delivered. Throws retry
+too. `maxAttempts` (default 1000, about sixteen hours at the retry ceiling) bounds
+one occurrence: a one-off schedule then becomes `failed`, a recurring one gives up
+that occurrence (`schedule/failed` with `skipped: true` and the `nextAt` it moves
+to) and keeps its cadence. A failure reason is kept to 1000 characters. Backoff is 1, 2, 4, 8, 16, 32, then 60 seconds,
 capped at 60 seconds and persisted across restart. `retryAt`, `attempts` and `lastError`
 show retry diagnostics; success resets them. `nextAt` and `lateByMs` retain the original
 occurrence time. Recurring schedules fire once after an idle stretch and advance to the

package/llms/application.2.txt

@@ -5,7 +5,42 @@
 
 Parts of this slice:
 - `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md)
-- `llms/application.2.txt`: Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
+- `llms/application.2.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Managed application kernel  (docs/guide/application-kernel.md)  (continued)
+==============================================================================
+
+## Multi-action notification delivery
+
+Opt into `delivery: { version, actions, project }` on `createNotificationOutbox`.
+The pure `actions(payload)` selector runs at enqueue; the versioned plan remains
+fixed throughout retry. Each `send` receives its action and a stable idempotency
+key; return a small JSON receipt such as a remote message or uploaded object ID.
+An action that returned is confirmed and is never sent again: a result that is not
+JSON, or does not fit the state's byte budget, is kept as `receipt: null` with
+`unrecorded: 'not-json' | 'too-large'` and reported to `onError`.
+`project(notification, receipts)` applies all confirmed results locally and must
+be idempotent. Checkpoints and the final projection timestamp live in the existing
+atomic StateStore; completed receipts retain them within retention/byte limits.
+
+This supports, for example, text plus attachment delivery with a local timeline
+projection, or upload plus publication with a local asset index. These are protocol
+examples, not claims of deployed consumer adoption. A failure in projection does
+not repeat confirmed sends. A crash after remote success but before receipt commit
+is ambiguous: the provider must deduplicate the action key or reconcile its result.
+A projection can also repeat if its completion checkpoint is lost.
+
+A plan keeps its actions from enqueue, so an older version needs only its
+projection to finish: a new executor lists it in `retiredVersions: { v1: project }`
+until the queue has drained. A plan version the executor does not know is reported
+to `onError` as `NotificationPlanVersionError` and waits — at least a poll interval,
+spending no attempt, without `classify` — for a process that knows it: the other
+side of a rolling deploy, the version a rollback returns to, or this one once it
+lists the version. Whole-state file and memory stores
+remain supported. Atomic enqueue with an unrelated business transaction is not
+provided by this contract; retain the application's transactional adapter when that
+boundary is required. Send and projection callbacks own their external deadlines.
 
 ==============================================================================
 # Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
@@ -386,7 +421,7 @@ cutovers are covered by the executable
 | `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
 | `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
 | `DiagnosticJournalLockPolicySchema` / `DiagnosticJournalLockPolicy` | schema / _type_ | `refuse` (default) or `reclaim-stale`, which reclaims only a lock whose recorded owner is provably gone |
-| `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — owner alive, another machine, or a lock this host cannot attribute — read off the thrown `EEXIST` |
+| `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — attribution, PID liveness and optional process `identity` evidence (`matched`, `different-boot`, `reused-pid`, `pid-gone`, `legacy`, `unavailable`) — read off the thrown `EEXIST` |
 | `DiagnosticJournalSubmitResultSchema` / `DiagnosticJournalSubmitResult` | schema / _type_ | accepted epoch/sequence or explicit invalid, oversized, capacity, closed or failed refusal |
 | `DiagnosticJournalStatusSchema` / `DiagnosticJournalStatus` | schema / _type_ | state, limits, exact admission/write/failure counters, pending ownership, rotations, partial tails and last safe sequences |
 | `DiagnosticJournalFrameSchema` / `DiagnosticJournalFrame` | schema / _type_ | version-1 JSONL frame carrying process epoch, contiguous accepted sequence and schema-validated JSON event |
@@ -488,3 +523,50 @@ vocabulary with an event topic declared `mode: 'decision'`.
 
 → [ADR 0152](../decisions/0152-a-keyspace-is-memory-that-nothing-reaches-before-it-is-durable.md),
 [ADR 0153](../decisions/0153-a-watched-read-is-one-read-per-question.md).
+
+### Managed change subscriptions and scoped watches
+
+`changeSubscriptionResource` (`stitchkit/application`) accepts
+`ChangeSubscriptionConfig`: `id`, unique `keys` (1–128, at most 256 characters each),
+`connect(signal)`, `reconcile(key, context)`, required `reconcileIntervalMs` (10 ms–1 h),
+optional `timeoutMs` (30000; 1 ms–1 h), `backoff`, and `onError`.
+`ChangeConnection` supplies `subscribe({ signal, hint, disconnected })`, which completes subscription
+before the first read; `close()` releases it. `ChangeReconciliation` exposes `signal`
+and a synchronous `commit(callback)` guard against late publication. Drivers must
+honor cancellation. Uncooperative work retains its slot until settled instead of
+allowing overlapping connections/reads. Errors reach `onError`; no raw payload or
+connection string is logged by this resource. Recovery runs after reconnect and
+periodically even when no notification arrives.
+
+`WatchHubConfig` adds `maxSources` (1024), `maxSubscribers` (1024), and optional
+`reconcileIntervalMs` (10 ms–1 h). `hub.attach(subscriber, scope?)` accepts a
+`WatchAdmissionScope` containing a **server-verified** `key` (1–512 characters) and
+revocation `signal`. The key separates sharing and is the optional third argument
+of `read(operation, args, scope)`; a key's `instance` routes frames and never
+separates sources. Attached over `maxSubscribers`, a subscriber gets a watcher whose
+`open` refuses with `Watch subscriber capacity exceeded`; `attach` does not throw
+for capacity. It must represent account, session and permissions;
+never trust a client-supplied owner ID as that scope.
+
+
+
+### Notification action and projection receipts
+
+`NotificationOutboxConfig.delivery` accepts `NotificationDeliveryConfig`:
+immutable executor `version`, pure `actions(payload)` plan selector (1–128 unique
+names, each at most 128 characters), and idempotent `project(notification, receipts)`.
+`send` receives optional `action` and stable `idempotencyKey`, and returns a JSON
+remote receipt (void becomes null). A result that is not JSON or does not fit the
+byte budget is kept as `receipt: null` with `unrecorded: 'not-json' | 'too-large'`;
+the action stays confirmed and is not sent again. `retiredVersions` maps earlier
+plan versions to their `NotificationProjection` so queued items drain after an
+executor upgrade; an unknown version is reported to `onError` as
+`NotificationPlanVersionError` and waits, spending no attempt and not consulting
+`classify`, for an executor that knows it. `NotificationDeliveryStateSchema` validates the
+optional `NotificationDeliveryState` on queued items and completed receipts:
+`version`, `actions`, `receipts` and optional `projectedAt`. Checkpoints share the
+existing atomic StateStore and lease fence. Receipt retention and serialized byte
+budgets still apply. Single-send configuration remains valid without `delivery`.
+A remote result lost before its checkpoint may be sent again; provider idempotency
+or reconciliation is required. A projection may repeat after a crash before its
+checkpoint. Business-transaction enqueue and durable quarantine are not implied.

package/llms/application.txt

@@ -6,7 +6,7 @@
 
 Parts of this slice:
 - `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md)
-- `llms/application.2.txt`: Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
+- `llms/application.2.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)
@@ -656,7 +656,12 @@ refusals are explicit; accepted ordered frames are never evicted.
 The absolute path's parent must already exist and be operator-controlled. One manager owns it via
 an exclusive `.lock`; new files use mode `0600` by default. `maxFiles` includes the active file,
 and a non-newline startup tail is rotated intact rather than guessed or repaired. An abrupt process
-death may leave the lock for an operator to remove only after proving the former owner is gone.
+death may leave a lock. The default `refuse` policy leaves recovery to the operator;
+`lock: 'reclaim-stale'` compares machine, boot and process birth identity before
+recovery. A reused PID cannot impersonate a modern owner. Legacy records with a
+live PID, foreign namespaces and unavailable identity refuse automatic recovery;
+see the upgrading guide for quiescent legacy recovery. The same mechanism owns the
+short-lived reclaim guard.
 
 `flush()` means every accepted append through that call's boundary settled. It is not `fsync`, a
 durable receipt, exactly-once execution or remote delivery. Timeout/cancellation bound only the
@@ -986,3 +991,28 @@ so a scheduler stall on a loaded host cannot pull a live lock from under its
 holder — after which the heartbeat wins and the lock is abandoned. Temporary files a crashed writer left beside the state are swept on
 the store's first update. Ledger corruption may be declared reconstructable;
 an outbox must fail closed rather than silently discard pending delivery.
+
+## Recovering change subscriptions
+
+`changeSubscriptionResource` is an optional resource over a consumer-owned driver.
+It uses a finite declared key set, subscribes before reading, reconciles after
+reconnect and periodically repairs lost hints. `reconcileIntervalMs` is explicit;
+notifications alone cannot prove freshness. Within a key, hints coalesce into one
+trailing read and a failed read retries with backoff. Use the supplied
+`context.commit(() => publish(value))` after awaits to reject an obsolete connection.
+
+Drivers implement `connect(signal)` and return `subscribe({ signal, hint,
+disconnected })` plus `close()`. Subscribe must establish the notification boundary
+before resolving. A database LISTEN driver owns its connection, channels, decoding
+and transaction ordering; no SQL or database driver is included here. The resource
+owns reconnect, deadlines and shutdown. Drivers must honor abort. If one ignores it,
+its slot remains occupied until settlement; deadlines cannot safely manufacture
+successful cleanup or permit an overlapping connection.
+
+For watched reads, set `reconcileIntervalMs` on the existing `createWatchHub` rather
+than building a second read loop. Its per-key machinery is shared with managed
+subscriptions. Limits default to 1024 sources and 1024 subscribers per hub; set
+explicit finite values for larger workloads. Supply a server-verified admission
+scope to `attach` and abort it on logout, permission revocation or session replacement.
+The read callback receives the trusted scope as its third argument. A client owner
+ID in arguments is not authentication.

package/llms/files.txt

@@ -27,7 +27,7 @@ available from `stitchkit/contract`.
 | `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
 | `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
-| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
+| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 
 ---

package/llms/live.txt

@@ -469,3 +469,11 @@ realtime contract from `stitchkit`, and the server halves live in `stitchkit/app
 | `watchDiff` / `applyWatchDelta` / `watchDeltaWins` | functions | build a difference (`undefined` when equal), rebuild the value from one (throws rather than inventing), and whether it is actually smaller than the value |
 
 ---
+
+### Session-scoped watch lifetime
+
+`WatchClientConfig.session` captures a `SessionOperation`; `maxKeys` (1024) and
+`maxListenersPerKey` (128) bound retained subscriptions; a handle takes its key on
+`subscribe`, which is where capacity refuses. Its lifetime nonce travels
+in optional `WatchKey.instance`, preventing old-session frames from matching a new
+client on the same socket. This is routing identity, never authorization.

package/llms/react.txt

@@ -182,3 +182,11 @@ Browser- and server-render-safe React data-layer helpers. Needs the
 For the rationale behind these APIs — why `Bun.serve` and not a framework, why
 two context types, why thin wrappers — see the
 [Architecture Decisions](../decisions/).
+
+### Watched handles in the query cache
+
+`CacheBridgeConfig.watched` accepts `WatchCacheBinding` entries with `handle`,
+`queryKey` and optional `state(frame)` observer. Include the session in query keys.
+`CacheBridgeConfig.session` fences events and removes bound queries when that login
+ends. Watch loss marks a query stale without triggering an independent refetch;
+recovery belongs to the watched read.

package/llms/server.3.txt

@@ -1029,3 +1029,60 @@ registry, and a name seen once does not live on in a map. This ordering exists o
 through `emitTo`; a broadcast through `realtime.to(room).emit` reaches the
 socket immediately, replay or not, so keep room traffic whose order matters
 relative to the snapshot on the registry.
+
+## Session-scoped watches and query cache
+
+Pass the captured login operation as `createWatchClient(contract, { transport,
+session })`. It adds a lifetime nonce to watch keys and detaches on invalidation;
+a late frame for a previous login cannot match a new client's key on the same socket.
+Both client and server must support the new optional `WatchKey.instance` field.
+The nonce is not authorization: the server still admits a verified identity and
+uses `hub.attach(subscriber, { key: verifiedScope, signal: revocationSignal })`.
+The scope key must change with session and permission boundaries.
+
+One scope and one question share one source and one read, however many client
+instances watch it: the hub routes each frame to every instance under its own
+key. A new tab of the same session costs a route, not a read.
+
+### Capacity
+
+A hub admits at most `maxSources` sources (1024) and `maxSubscribers` attached
+subscribers (1024); a client holds at most `maxKeys` keys (1024) and
+`maxListenersPerKey` listeners per key (128). Every excess is a refusal, never
+unbounded state: `open` answers `{ accepted: false, reason }` — including for a
+subscriber attached over capacity, whose `attach` returns a watcher that refuses
+every `open` — and a client's `subscribe` throws. A client handle takes its key
+when it subscribes, so handles a render creates and never subscribes cost
+nothing. A connection handler that throws closes that connection and is logged;
+the server goes on. A subscriber attached over capacity is not tracked: its
+refusals stand until it reconnects.
+
+A read that fails sends its subscribers `unavailable` / `source-error` with the
+`code` and `message` of an `AppError`, which is written for its caller. Any other
+error reaches only the hub's `logger`; the browser reads `The watched read failed`. Set larger finite limits for larger workloads, and
+`reconcileIntervalMs` when a lost invalidation must recover without a reconnect.
+
+`createCacheBridge` can bind watched handles directly:
+
+```ts
+const bridge = createCacheBridge({
+  socket, queryClient, handlers: {}, session,
+  watched: [{
+    handle: watches.list({ folderId }),
+    queryKey: ['items', session.id, folderId],
+    state: frame => showWatchState(frame),
+  }],
+})
+bridge.connect()
+```
+
+A value updates that exact query; non-live state marks it stale while retaining its
+value. The existing phases (`opening`, `live`, `unavailable`, `resync-required`)
+remain the status model. Do not replace unavailable data with an empty collection.
+Session invalidation removes bound queries. Include the session identity in query
+keys and guard any application-level side effects with that same operation.
+
+Use existing shared watches for paginated lists and selected-detail queries; bind
+each exact argument set to its query key. No global domain/query registry or new
+UI components are needed. Reconnect and revision/delta recovery remain owned by the
+watch client; silent lost notifications are repaired by hub reconciliation.