stitchkit 0.89.0 → 0.90.1

package/CHANGELOG.md

@@ -15,6 +15,108 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.90.1] — 2026-09-15
+
+### Fixed
+
+- **An unknown spilled-output reference is a refusal, not a server fault.** The
+  SQLite spill store threw a bare `TypeError('Unknown spill reference')`, which
+  is not an `AppError`, so `toolResultFromError` scrubbed it to
+  `{"error":"INTERNAL_SERVER_ERROR","details":{"message":"Internal server
+  error"}}`. A model that passed the wrong identifier — a background terminal
+  session id where a spill reference was wanted — could not tell "fix the
+  argument" from "the store is broken"; in the run this was reported from, it
+  retried the same call three times and declared the tool broken. It now refuses
+  with `SPILL_REFERENCE_UNKNOWN` / 404, naming the reference and hinting at the
+  one the spilling command returned. Authorization, `read` and `search` shared
+  three copies of the lookup and its refusal; they now share one, so the answer
+  cannot differ by path. The lookup is scoped by conversation, so a reference
+  held by another conversation refuses identically and discloses nothing.
+
+- **A coding-tool refusal keeps its declared status across a process boundary.**
+  Those refusals carried their own private `code → status` map, while
+  `toolErrorFromResult` — which rebuilds an envelope that reached another
+  process through MCP or the CLI — resolves the status from
+  `STITCH_ERROR_STATUS`. Every refusal code missing from that map came back
+  `500`: measured, `SANDBOX_UNAVAILABLE` → 500 against its declared 503, with
+  `NOT_FOUND` → 404 and `WAIT_TIMEOUT` → 408 as controls. `SANDBOX_UNAVAILABLE`,
+  `SANDBOX_INSUFFICIENT` and `SPILL_REFERENCE_UNKNOWN` join the framework
+  vocabulary, and the refusal list is now an allowlist of names typed against
+  it — a refusal code absent from the framework map is a compile error rather
+  than a 500 on the wire.
+
+- **The mechanical refusal gate can see the artifact tools.** It enumerates
+  mounted coding tools and refuses one with no registered refusal, and
+  `read_output` / `search_output` are mounted only when an artifact store is —
+  which the gate's own profile did not do. "Every tool has a refusal" was
+  vacuously true for exactly the two tools that had none.
+  `packages/core/tests/coding-tool-refusals.test.ts` now mounts a real spill
+  store.
+
+- **Heavy release lanes no longer count memory that swap cannot back.**
+  `verify --release` sized its lane concurrency from `MemAvailable` alone. On a
+  host whose swap was 97% consumed that read 9.2 GiB and chose two lanes, and
+  the pair was killed; with swap exhausted the reclaimable half of that figure
+  is not reclaimable. It now falls back to `MemFree` when free swap is under 5%
+  of swap total — 0.97 GiB and one lane on the host that prompted this — and
+  says `GiB affordable` rather than `GiB available`.
+
+## [0.90.0] — 2026-09-15
+
+### ⚠️ Breaking changes
+
+**Who must act:** applications that bind the watch protocol themselves or read
+`WatchValueFrame.value` directly — a hand-written subscriber, a test double, a custom
+server binding. Applications using `createWatchClient` and the starter's binding need
+no code change. **Both ends must come from the same major:** a client older than 0.90.0
+reads a `delta` frame as a value of `undefined`, silently.
+
+- **`stitchkit.watch.value` is a discriminated union on `kind`.** `full` carries the value,
+  `delta` carries a structural difference against a `base` revision, `unchanged` says the
+  value held is still current. Every frame carries `fingerprint`, the order-independent
+  digest of the value the receiver holds after applying it.
+
+  ```ts
+  // before: frame.value
+  // after:
+  if (frame.kind === 'full') hold(frame.value);
+  else if (frame.kind === 'delta') hold(applyWatchDelta(held, frame.delta));
+  // 'unchanged' leaves what you hold standing
+  ```
+
+- **`AttachedWatcher.open` takes an optional third argument, `have`.** A custom server
+  binding forwarding `stitchkit.watch.open` should pass the payload's `have` through;
+  omitting it costs a whole value on every reconnection and is otherwise harmless.
+
+### Added
+
+- **Watched reads cross as differences.** The hub chooses per subscriber, from the revision
+  it last delivered to that subscriber, and sends a difference only when it is strictly
+  smaller than the value. Measured: a ~75 KB list answer with one field changed crosses as a
+  frame under 1 KB. `deltaMemoryBytes` (default 262144, `0` disables) bounds the superseded
+  values kept per key. → ADR 0183.
+- **A reconnection offers what it holds.** `stitchkit.watch.open` may carry
+  `have: { revision, fingerprint }`; a subscriber returning to an answer that has not moved
+  is told `unchanged` instead of being sent the value again. Requires the key to still exist
+  on the hub — set `holdMs` past your reconnect delay.
+- **Reassembly is checked.** The client verifies the rebuilt value against the server's
+  fingerprint on every frame and resynchronises **that one key** on any mismatch, publishing
+  `resync-required`. Other keys on the same socket are untouched.
+- **`watchDiff` / `applyWatchDelta` / `watchDeltaWins`** and the `WatchDelta` shapes are
+  exported from `stitchkit/live` for applications building their own binding.
+- **`auditChanges`** — the sink `filter` most projects were writing themselves: drops `GET`,
+  `HEAD` and `OPTIONS`, keeps `401` and `403` whatever the verb was, keeps an unrecognised
+  verb. One predicate across HTTP, MCP and agent calls. → ADR 0184.
+- **`createSpooledSink`** — writes the audit row to a local append-only file before offering
+  it to the store and replays what a previous process left undelivered. At least once; the
+  store must be idempotent on the record key (`spanId` by default).
+
+### Unchanged on purpose
+
+- **Auditing stays opt-in.** `createHandler` and the tool mounts are untouched. Making a
+  decision about audit mandatory at startup was considered and rejected — the measurement it
+  rested on counted projects without an HTTP surface as projects that had forgotten. → ADR 0184.
+
 ## [0.89.0] — 2026-09-12
 
 ### ⚠️ Breaking changes

package/dist/agent-runtime/coding-tool-refusals.d.ts

@@ -16,16 +16,19 @@
  * knows; `contained-files.ts` stays `AppError`-free, and everything it throws
  * keeps being scrubbed. Default-deny: a cause with no case here is internal.
  */
-/** Codes a coding tool may hand a model, with the status each one carries. */
-declare const REFUSAL_STATUS: {
-    readonly BAD_REQUEST: 400;
-    readonly FORBIDDEN: 403;
-    readonly NOT_FOUND: 404;
-    readonly CONFLICT: 409;
-    readonly SANDBOX_UNAVAILABLE: 503;
-    readonly SANDBOX_INSUFFICIENT: 503;
-};
-export type CodingRefusalCode = keyof typeof REFUSAL_STATUS;
+/**
+ * The codes a coding tool may hand a model — an allowlist of names, not a
+ * second status map.
+ *
+ * It used to carry its own `code → status` object, and the two maps disagreed
+ * where it mattered: `toolErrorFromResult` rebuilds an envelope that crossed a
+ * process boundary and reads the status from `STITCH_ERROR_STATUS`, so a
+ * refusal missing there arrived as a 500 no matter what this file declared.
+ * `satisfies readonly StitchErrorCode[]` now makes that unrepresentable — a
+ * refusal code absent from the framework vocabulary is a compile error here.
+ */
+declare const REFUSAL_CODES: readonly ["BAD_REQUEST", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "SANDBOX_UNAVAILABLE", "SANDBOX_INSUFFICIENT", "SPILL_REFERENCE_UNKNOWN"];
+export type CodingRefusalCode = (typeof REFUSAL_CODES)[number];
 /**
  * Refuse with a reason the model actually receives.
  *
@@ -57,5 +60,23 @@ export declare function codingPathRefusal(code: CodingRefusalCode, message: stri
  * model can do about it, and keeps being scrubbed. Default-deny by omission.
  */
 export declare function refuseMissingCodingPath(error: unknown, relative: string): never;
+/**
+ * Refuse a spill reference the store does not hold.
+ *
+ * The same failure this module was written for, one layer down. The SQLite
+ * spill store threw a bare `TypeError('Unknown spill reference')`, which is not
+ * an `AppError`, so `toolResultFromError` scrubbed it to an empty
+ * `INTERNAL_SERVER_ERROR`: a model that passed the wrong identifier — a
+ * background terminal session id instead of a spill reference — could not tell
+ * "fix the argument" from "the store is broken". Observed: it retried the same
+ * call three times and declared the tool broken.
+ *
+ * The reference is echoed back because it is the model's own input: naming it
+ * tells the model which of its arguments to replace, and leaks nothing it did
+ * not already send. A reference belonging to ANOTHER conversation refuses
+ * through this same path — the lookup is scoped by conversation, so a foreign
+ * reference is simply absent, and the refusal cannot distinguish the two.
+ */
+export declare function refuseUnknownSpillReference(reference: string): never;
 export {};
 //# sourceMappingURL=coding-tool-refusals.d.ts.map

package/dist/agent-runtime/coding-tool-refusals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coding-tool-refusals.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-refusals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,8EAA8E;AAC9E,QAAA,MAAM,cAAc;aAClB,WAAW,EAAE,GAAG;aAChB,SAAS,EAAE,GAAG;aACd,SAAS,EAAE,GAAG;aACd,QAAQ,EAAE,GAAG;aACb,mBAAmB,EAAE,GAAG;aACxB,oBAAoB,EAAE,GAAG;CACjB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,cAAc,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,KAAK,CAQP;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,KAAK,CAKP;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAiC/E"}
+{"version":3,"file":"coding-tool-refusals.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/coding-tool-refusals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;;;;;;;GAUG;AACH,QAAA,MAAM,aAAa,0IAQ4B,CAAC;AAEhD,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,KAAK,CAQP;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,KAAK,CAKP;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAiC/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK,CASpE"}

package/dist/agent-runtime/spill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spill.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/spill.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,wBAAwB,EAEzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAkBxD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,MAAM,EAAE,uBAAuB,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB,GAAG,wBAAwB,GAAG;IAC7B,MAAM,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;QAClF,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,EAAE,CAAC;IACJ,OAAO,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD,CAqHA"}
+{"version":3,"file":"spill.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/spill.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,wBAAwB,EAEzB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAkBxD,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,MAAM,EAAE,uBAAuB,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB,GAAG,wBAAwB,GAAG;IAC7B,MAAM,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;QAClF,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,EAAE,CAAC;IACJ,OAAO,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxD,CAgHA"}

package/dist/agent-runtime-coding-tools.js

@@ -3,12 +3,12 @@ import {
   AgentCodingToolLimitsSchema,
   AgentCodingToolPathAuthorizationSchema,
   createAgentCodingTools
-} from "./index-cp20z0n6.js";
+} from "./index-j7q0xj6d.js";
 import"./index-bn2cjajt.js";
-import"./index-gskm1k5a.js";
-import"./index-2bxcmqkb.js";
+import"./index-gte38nbm.js";
+import"./index-kazec06k.js";
 import"./index-6k1937bx.js";
-import"./index-0w9abg87.js";
+import"./index-scs3f1eg.js";
 import"./index-kzfs85xp.js";
 import"./index-kc6h6hg0.js";
 import"./index-r159gjwy.js";

package/dist/agent-runtime-harness.js

@@ -6,7 +6,7 @@ import {
   composeAgentPrompt,
   createAgentRuntime,
   createAgentRuntimeEventSink
-} from "./index-hw2chdvy.js";
+} from "./index-f475yj00.js";
 import"./index-p13mwz16.js";
 import"./index-y64k3s0h.js";
 import {
@@ -19,13 +19,13 @@ import {
   walkContainedFiles
 } from "./index-bn2cjajt.js";
 import"./index-7rkhw9ec.js";
-import"./index-zyvby92n.js";
+import"./index-44ht2790.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-7evdsyez.js";
-import"./index-2bxcmqkb.js";
+import"./index-2hryh65w.js";
+import"./index-kazec06k.js";
 import"./index-6k1937bx.js";
-import"./index-0w9abg87.js";
+import"./index-scs3f1eg.js";
 import"./index-zcgf3gqf.js";
 import"./index-7zbps32p.js";
 import"./index-kzfs85xp.js";

package/dist/agent-runtime-sandbox.js

@@ -1,15 +1,15 @@
 import {
-  codingRefusal,
   createAgentCodingTools
-} from "./index-cp20z0n6.js";
+} from "./index-j7q0xj6d.js";
 import"./index-bn2cjajt.js";
 import {
+  codingRefusal,
   missingSandboxRestrictions,
   probeAgentProcessSandbox
-} from "./index-gskm1k5a.js";
-import"./index-2bxcmqkb.js";
+} from "./index-gte38nbm.js";
+import"./index-kazec06k.js";
 import"./index-6k1937bx.js";
-import"./index-0w9abg87.js";
+import"./index-scs3f1eg.js";
 import"./index-kzfs85xp.js";
 import"./index-kc6h6hg0.js";
 import"./index-r159gjwy.js";

package/dist/agent-runtime.js

@@ -31,7 +31,7 @@ import {
   renderAgentStateSlots,
   repairedSearchCall,
   selectAgentHistory
-} from "./index-hw2chdvy.js";
+} from "./index-f475yj00.js";
 import"./index-p13mwz16.js";
 import {
   AgentAdmissionEventSchema,
@@ -163,22 +163,23 @@ import {
   AgentSandboxRestrictionSchema,
   missingSandboxRestrictions,
   probeAgentProcessSandbox,
-  recordAgentSandboxProbe
-} from "./index-gskm1k5a.js";
+  recordAgentSandboxProbe,
+  refuseUnknownSpillReference
+} from "./index-gte38nbm.js";
 import {
   buildToolManifest,
   mountAgent
-} from "./index-q3ve2d1k.js";
+} from "./index-gbqjt8jz.js";
 import"./index-7rkhw9ec.js";
-import"./index-31jw8fjq.js";
-import"./index-8c3a7m4g.js";
-import"./index-zyvby92n.js";
+import"./index-wb15909q.js";
+import"./index-2hrfpw2c.js";
+import"./index-44ht2790.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-7evdsyez.js";
-import"./index-2bxcmqkb.js";
+import"./index-2hryh65w.js";
+import"./index-kazec06k.js";
 import"./index-6k1937bx.js";
-import"./index-0w9abg87.js";
+import"./index-scs3f1eg.js";
 import {
   childSpan,
   createTraceContext
@@ -2258,16 +2259,17 @@ function decodeAuthorization(value) {
 function createSqliteAgentSpillStore(input) {
   const now = input.now ?? (() => new Date);
   const database = input.sqlite.database;
-  const authorization = (reference) => {
+  const rowFor = (reference) => {
     const raw = database.prepare(`
         SELECT payload, bytes, authorization_payload
         FROM stitchkit_agent_runtime_spills
         WHERE reference_id = ? AND conversation_id = ?
       `).get(reference, input.conversationId);
     if (raw === null || raw === undefined)
-      throw new TypeError("Unknown spill reference");
-    return decodeAuthorization(SpillRowSchema.parse(raw).authorization_payload);
+      refuseUnknownSpillReference(reference);
+    return SpillRowSchema.parse(raw);
   };
+  const authorization = (reference) => decodeAuthorization(rowFor(reference).authorization_payload);
   const write = async (request) => {
     const reference = randomUUID3();
     const createdAt = now();
@@ -2290,14 +2292,7 @@ function createSqliteAgentSpillStore(input) {
     return { reference };
   };
   const read = async (request) => {
-    const raw = database.prepare(`
-        SELECT payload, bytes, authorization_payload
-        FROM stitchkit_agent_runtime_spills
-        WHERE reference_id = ? AND conversation_id = ?
-      `).get(request.reference, input.conversationId);
-    if (raw === null || raw === undefined)
-      throw new TypeError("Unknown spill reference");
-    const row = SpillRowSchema.parse(raw);
+    const row = rowFor(request.reference);
     return {
       data: row.payload.slice(request.offset, request.offset + request.maxBytes),
       totalBytes: row.bytes,
@@ -2307,14 +2302,7 @@ function createSqliteAgentSpillStore(input) {
     };
   };
   const search = (request) => {
-    const raw = database.prepare(`
-        SELECT payload, bytes, authorization_payload
-        FROM stitchkit_agent_runtime_spills
-        WHERE reference_id = ? AND conversation_id = ?
-      `).get(request.reference, input.conversationId);
-    if (raw === null || raw === undefined)
-      throw new TypeError("Unknown spill reference");
-    const row = SpillRowSchema.parse(raw);
+    const row = rowFor(request.reference);
     const matches = [];
     new TextDecoder("utf-8", { fatal: true }).decode(row.payload).split(`
 `).forEach((text, index) => {

package/dist/application/watch-hub.d.ts

@@ -38,7 +38,7 @@
  * → ADR 0153.
  */
 import { type BackoffPolicy } from '../browser/resumable.js';
-import { type WatchKey, type WatchStateFrame, type WatchValueFrame } from '../live/watch-contract.js';
+import { type WatchHave, type WatchKey, type WatchStateFrame, type WatchValueFrame } from '../live/watch-contract.js';
 import type { StitchLogger } from '../logger.js';
 /** The operation a watched read runs — `OperationIdentity`'s two stable halves. */
 export interface WatchOperation {
@@ -52,7 +52,15 @@ export interface WatchSubscriber {
     state(frame: WatchStateFrame): void;
 }
 export interface AttachedWatcher {
-    open(key: WatchKey, args: unknown): {
+    /**
+     * Start watching a key.
+     *
+     * `have` is what the caller already holds from an earlier connection. Offered,
+     * it turns a reconnection into a difference — or into nothing at all when the
+     * answer has not moved — instead of the whole value again. Omitted, the caller
+     * is treated as holding nothing, which is what a first subscription is.
+     */
+    open(key: WatchKey, args: unknown, have?: WatchHave): {
         accepted: boolean;
         reason?: string;
     };
@@ -105,6 +113,20 @@ export interface WatchHubConfig {
     holdMs?: number;
     /** Retry pacing after a failed read. */
     backoff?: BackoffPolicy;
+    /**
+     * How many bytes of superseded values one key may keep, for differences.
+     *
+     * A difference needs the value the receiver actually holds, which is no longer
+     * the current one. This is the ceiling on that memory, per key, and it is a
+     * byte budget rather than a count of revisions because the thing being
+     * protected is the process's heap and revisions have no size.
+     *
+     * Zero disables differences entirely: every frame carries the whole value,
+     * which is what this hub did before they existed. Default 262144 (256 KiB),
+     * which holds several revisions of the large answers differences are for and
+     * a great many small ones.
+     */
+    deltaMemoryBytes?: number;
     /** Whether two answers are the same. Defaults to key-order-independent JSON equality. */
     same?(previous: unknown, next: unknown): boolean;
     logger?: StitchLogger;

package/dist/application/watch-hub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watch-hub.d.ts","sourceRoot":"","sources":["../../src/application/watch-hub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,sBAAsB,CAAC;AAEzE,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACpC,oDAAoD;IACpD,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,GAAG;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,KAAK,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,yEAAyE;IACzE,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,gFAAgF;IAChF,SAAS,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC;IAC9C;;;;;;;;;OASG;IACH,aAAa,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC;IAC3E,mFAAmF;IACnF,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3D,kEAAkE;IAClE,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,yFAAyF;IACzF,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACjD,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,UAAU,EAAE,eAAe,GAAG,eAAe,CAAC;IACrD;;;;;;OAMG;IACH,SAAS,IAAI,MAAM,CAAC;IACpB,qEAAqE;IACrE,IAAI,IAAI,MAAM,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACf;AAqBD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,CAU3E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAoR/D"}
+{"version":3,"file":"watch-hub.d.ts","sourceRoot":"","sources":["../../src/application/watch-hub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,sBAAsB,CAAC;AAEzE,OAAO,EACL,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,eAAe,EAErB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;IACpC,oDAAoD;IACpD,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7F,KAAK,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,yEAAyE;IACzE,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,gFAAgF;IAChF,SAAS,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC;IAC9C;;;;;;;;;OASG;IACH,aAAa,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC;IAC3E,mFAAmF;IACnF,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3D,kEAAkE;IAClE,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,yFAAyF;IACzF,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACjD,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,UAAU,EAAE,eAAe,GAAG,eAAe,CAAC;IACrD;;;;;;OAMG;IACH,SAAS,IAAI,MAAM,CAAC;IACpB,qEAAqE;IACrE,IAAI,IAAI,MAAM,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACf;AA2CD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,CAU3E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CA4Y/D"}

package/dist/application-grammy.js

@@ -3,7 +3,7 @@ import {
 } from "./index-2k4yrqkc.js";
 import {
   AppError
-} from "./index-0w9abg87.js";
+} from "./index-scs3f1eg.js";
 
 // src/application/grammy.ts
 import { Context } from "grammy";

package/dist/application.js

@@ -36,7 +36,7 @@ import {
   ApplicationShutdownBudgetSchema,
   ApplicationShutdownOptionsSchema,
   createApplication
-} from "./index-t7fkyxcr.js";
+} from "./index-zkcqhxx8.js";
 import {
   ApplicationAdmissionSnapshotSchema,
   ApplicationHealthSchema,
@@ -66,8 +66,10 @@ import {
   createBackoff
 } from "./index-s8cnx02s.js";
 import {
+  deltaWins,
+  diff,
   watchKeyString
-} from "./index-dre2ywck.js";
+} from "./index-2na0qrfn.js";
 import"./index-ywd0y6m1.js";
 import {
   BoundedChannelPolicySchema,
@@ -85,7 +87,7 @@ import {
   argumentsDigest,
   stableValue
 } from "./index-a916km3r.js";
-import"./index-0w9abg87.js";
+import"./index-scs3f1eg.js";
 import"./index-kzfs85xp.js";
 import"./index-77fekveh.js";
 // src/application/admission.ts
@@ -1563,17 +1565,20 @@ function createWatchHub(config) {
   const held = new Map;
   const maxWatches = config.maxWatchesPerSubscriber ?? 64;
   const holdMs = config.holdMs ?? 0;
+  const deltaMemoryBytes = config.deltaMemoryBytes ?? 262144;
   const same = config.same ?? ((previous, next) => JSON.stringify(stableValue(previous)) === JSON.stringify(stableValue(next)));
   let reads = 0;
   let closed = false;
-  function tell(key, deliver) {
+  function tell(key, deliver2) {
     try {
-      deliver();
+      deliver2();
+      return true;
     } catch (error) {
       config.logger?.warn?.("[stitchkit] watch subscriber threw", {
         key: watchKeyString(key),
         error: error instanceof Error ? error.message : String(error)
       });
+      return false;
     }
   }
   function announceState(source, state) {
@@ -1582,13 +1587,85 @@ function createWatchHub(config) {
       tell(source.key, () => subscriber.state(state));
     }
   }
-  function publish(source, value) {
+  function remember(source, revision, value, fingerprint) {
+    if (deltaMemoryBytes === 0)
+      return;
+    const bytes = (JSON.stringify(value) ?? "null").length;
+    if (bytes > deltaMemoryBytes)
+      return;
+    source.history.set(revision, { value, fingerprint, bytes });
+    source.historyBytes += bytes;
+    for (const [oldest, entry] of source.history) {
+      if (source.historyBytes <= deltaMemoryBytes)
+        break;
+      source.history.delete(oldest);
+      source.historyBytes -= entry.bytes;
+    }
+  }
+  function frameFor(source, subscriber) {
+    const value = source.value;
+    const fingerprint = source.fingerprint ?? valueFingerprint(value);
+    const full = {
+      kind: "full",
+      key: source.key,
+      revision: source.revision,
+      fingerprint,
+      value
+    };
+    const base = source.baselines.get(subscriber);
+    if (base === undefined)
+      return full;
+    if (base === source.revision) {
+      return { kind: "unchanged", key: source.key, revision: source.revision, fingerprint };
+    }
+    const held2 = source.history.get(base);
+    if (!held2)
+      return full;
+    const delta = diff(held2.value, value);
+    if (delta === undefined || !deltaWins(delta, value))
+      return full;
+    return {
+      kind: "delta",
+      key: source.key,
+      revision: source.revision,
+      fingerprint,
+      base,
+      delta
+    };
+  }
+  function adoptBaseline(source, subscriber, have) {
+    if (source.fingerprint === have.fingerprint) {
+      source.baselines.set(subscriber, source.revision);
+      return;
+    }
+    const named = source.history.get(have.revision);
+    if (named?.fingerprint === have.fingerprint) {
+      source.baselines.set(subscriber, have.revision);
+      return;
+    }
+    for (const [revision, entry] of source.history) {
+      if (entry.fingerprint !== have.fingerprint)
+        continue;
+      source.baselines.set(subscriber, revision);
+      return;
+    }
+  }
+  function deliver(source, subscriber) {
+    const frame = frameFor(source, subscriber);
+    const delivered = tell(source.key, () => subscriber.value(frame));
+    if (delivered)
+      source.baselines.set(subscriber, source.revision);
+    return delivered;
+  }
+  function publish(source, value, fingerprint) {
+    if (source.fingerprint !== undefined) {
+      remember(source, source.revision, source.value, source.fingerprint);
+    }
     source.revision += 1;
     source.value = value;
-    const frame = { key: source.key, revision: source.revision, value };
-    for (const subscriber of source.subscribers) {
-      tell(source.key, () => subscriber.value(frame));
-    }
+    source.fingerprint = fingerprint;
+    for (const subscriber of source.subscribers)
+      deliver(source, subscriber);
   }
   async function pump(source) {
     if (source.reading || closed)
@@ -1605,7 +1682,7 @@ function createWatchHub(config) {
           const unchanged = source.signature !== undefined && same(source.value, value);
           source.signature = signature;
           if (!unchanged)
-            publish(source, value);
+            publish(source, value, valueFingerprint(value));
           if (source.state.phase !== "live") {
             announceState(source, { key: source.key, phase: "live" });
           }
@@ -1655,6 +1732,9 @@ function createWatchHub(config) {
       subscribers: new Set,
       unsubscribes: [],
       revision: 0,
+      history: new Map,
+      historyBytes: 0,
+      baselines: new Map,
       reading: false,
       dirty: true,
       state: { key, phase: "opening" },
@@ -1696,7 +1776,7 @@ function createWatchHub(config) {
       const keys = new Set;
       held.set(subscriber, keys);
       return {
-        open(key, args) {
+        open(key, args, have) {
           if (closed)
             return { accepted: false, reason: "the watch hub is closed" };
           const operation = { service: key.service, action: key.action };
@@ -1718,13 +1798,18 @@ function createWatchHub(config) {
           const source = acquire(operation, key, args);
           source.subscribers.add(subscriber);
           keys.add(id);
+          if (have)
+            adoptBaseline(source, subscriber, have);
           try {
             if (source.signature !== undefined) {
-              subscriber.value({ key, revision: source.revision, value: source.value });
+              const frame = frameFor(source, subscriber);
+              subscriber.value(frame);
+              source.baselines.set(subscriber, source.revision);
             }
             subscriber.state(source.state);
           } catch (error) {
             source.subscribers.delete(subscriber);
+            source.baselines.delete(subscriber);
             keys.delete(id);
             release(source);
             return {
@@ -1743,6 +1828,7 @@ function createWatchHub(config) {
           if (!source)
             return;
           source.subscribers.delete(subscriber);
+          source.baselines.delete(subscriber);
           release(source);
         },
         detach() {
@@ -1751,6 +1837,7 @@ function createWatchHub(config) {
             if (!source)
               continue;
             source.subscribers.delete(subscriber);
+            source.baselines.delete(subscriber);
             release(source);
           }
           keys.clear();
@@ -1779,6 +1866,9 @@ function createWatchHub(config) {
     }
   };
 }
+function valueFingerprint(value) {
+  return argumentsDigest({ value });
+}
 function readErrorCode(error) {
   if (typeof error !== "object" || error === null)
     return;

package/dist/cli.js

@@ -5,17 +5,17 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-7601qfg1.js";
+} from "./index-8dph3pw6.js";
 import"./index-sbdmyz75.js";
-import"./index-31jw8fjq.js";
-import"./index-8c3a7m4g.js";
-import"./index-zyvby92n.js";
+import"./index-wb15909q.js";
+import"./index-2hrfpw2c.js";
+import"./index-44ht2790.js";
 import"./index-vsbzgd7b.js";
 import"./index-f9mb610r.js";
-import"./index-7evdsyez.js";
-import"./index-2bxcmqkb.js";
+import"./index-2hryh65w.js";
+import"./index-kazec06k.js";
 import"./index-6k1937bx.js";
-import"./index-0w9abg87.js";
+import"./index-scs3f1eg.js";
 import"./index-zcgf3gqf.js";
 import"./index-7zbps32p.js";
 import"./index-kzfs85xp.js";

package/dist/contract/errors.d.ts

@@ -92,6 +92,9 @@ export declare const STITCH_ERROR_STATUS: {
     STREAM_FRAME_TOO_LARGE: number;
     STREAM_TERMINAL_MISSING: number;
     STREAM_LIFETIME_EXCEEDED: number;
+    SANDBOX_UNAVAILABLE: number;
+    SANDBOX_INSUFFICIENT: number;
+    SPILL_REFERENCE_UNKNOWN: number;
     INTERNAL_SERVER_ERROR: number;
 };
 /** A code stitchkit itself emits — derived from `STITCH_ERROR_STATUS` (no dup). */