stitchkit 0.89.0 → 0.90.0

package/CHANGELOG.md

@@ -15,6 +15,62 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [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/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.js

@@ -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,
@@ -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/index-2na0qrfn.js

@@ -0,0 +1,214 @@
+import {
+  LiveStatePhaseSchema,
+  LiveStateStopReasonSchema
+} from "./index-ywd0y6m1.js";
+import {
+  stableValue
+} from "./index-a916km3r.js";
+
+// src/live/watch-delta.ts
+import { z } from "zod";
+var WatchDeltaSchema = z.lazy(() => z.union([
+  z.object({ t: z.literal("set"), v: z.unknown() }),
+  z.object({
+    t: z.literal("obj"),
+    set: z.record(z.string(), WatchDeltaSchema).optional(),
+    drop: z.array(z.string()).optional()
+  }),
+  z.object({ t: z.literal("arr"), ops: z.array(WatchArrayOpSchema) })
+]));
+var WatchArrayOpSchema = z.lazy(() => z.union([
+  z.object({
+    o: z.literal("copy"),
+    from: z.number().int().nonnegative(),
+    count: z.number().int().positive()
+  }),
+  z.object({
+    o: z.literal("patch"),
+    from: z.number().int().nonnegative(),
+    d: WatchDeltaSchema
+  }),
+  z.object({ o: z.literal("put"), v: z.unknown() })
+]));
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function signature(value) {
+  return JSON.stringify(stableValue(value)) ?? "undefined";
+}
+function diff(previous, next) {
+  if (signature(previous) === signature(next))
+    return;
+  if (isRecord(previous) && isRecord(next))
+    return objectDiff(previous, next);
+  if (Array.isArray(previous) && Array.isArray(next))
+    return arrayDiff(previous, next);
+  return { t: "set", v: next };
+}
+function objectDiff(previous, next) {
+  const set = {};
+  const drop = [];
+  for (const key of Object.keys(next)) {
+    if (!Object.hasOwn(previous, key)) {
+      set[key] = { t: "set", v: next[key] };
+      continue;
+    }
+    const nested = diff(previous[key], next[key]);
+    if (nested !== undefined)
+      set[key] = nested;
+  }
+  for (const key of Object.keys(previous)) {
+    if (!Object.hasOwn(next, key))
+      drop.push(key);
+  }
+  return {
+    t: "obj",
+    ...Object.keys(set).length > 0 && { set },
+    ...drop.length > 0 && { drop }
+  };
+}
+function arrayDiff(previous, next) {
+  const previousSignatures = previous.map(signature);
+  const positions = new Map;
+  previousSignatures.forEach((value, index) => {
+    const bucket = positions.get(value);
+    if (bucket)
+      bucket.push(index);
+    else
+      positions.set(value, [index]);
+  });
+  const taken = new Set;
+  const ops = [];
+  let cursor = 0;
+  const extend = (from) => {
+    const last = ops.at(-1);
+    if (last?.o !== "copy" || last.from + last.count !== from)
+      return false;
+    ops[ops.length - 1] = { o: "copy", from: last.from, count: last.count + 1 };
+    return true;
+  };
+  for (const element of next) {
+    const wanted = signature(element);
+    const last = ops.at(-1);
+    const continuation = last?.o === "copy" ? last.from + last.count : undefined;
+    if (continuation !== undefined && continuation < previous.length && previousSignatures[continuation] === wanted && !taken.has(continuation)) {
+      taken.add(continuation);
+      extend(continuation);
+      cursor = continuation + 1;
+      continue;
+    }
+    const bucket = positions.get(wanted);
+    const found = bucket?.find((index) => !taken.has(index));
+    if (found !== undefined) {
+      taken.add(found);
+      if (!extend(found))
+        ops.push({ o: "copy", from: found, count: 1 });
+      cursor = found + 1;
+      continue;
+    }
+    const counterpart = cursor < previous.length && !taken.has(cursor) ? cursor : undefined;
+    const nested = counterpart === undefined ? undefined : diff(previous[counterpart], element);
+    if (counterpart !== undefined && nested !== undefined) {
+      taken.add(counterpart);
+      ops.push({ o: "patch", from: counterpart, d: nested });
+      cursor = counterpart + 1;
+      continue;
+    }
+    ops.push({ o: "put", v: element });
+  }
+  return { t: "arr", ops };
+}
+function apply(previous, delta) {
+  if (delta.t === "set")
+    return delta.v;
+  if (delta.t === "obj") {
+    if (!isRecord(previous))
+      throw new Error("an object difference needs an object to apply to");
+    const result2 = { ...previous };
+    for (const key of delta.drop ?? [])
+      delete result2[key];
+    for (const [key, nested] of Object.entries(delta.set ?? {})) {
+      result2[key] = apply(Object.hasOwn(result2, key) ? result2[key] : undefined, nested);
+    }
+    return result2;
+  }
+  if (!Array.isArray(previous))
+    throw new Error("an array difference needs an array to apply to");
+  const result = [];
+  for (const op of delta.ops) {
+    if (op.o === "put") {
+      result.push(op.v);
+      continue;
+    }
+    if (op.from >= previous.length) {
+      throw new Error(`the difference reads element ${op.from} of an array of ${previous.length}`);
+    }
+    if (op.o === "patch") {
+      result.push(apply(previous[op.from], op.d));
+      continue;
+    }
+    if (op.from + op.count > previous.length) {
+      throw new Error(`the difference copies ${op.count} from ${op.from} of an array of ${previous.length}`);
+    }
+    result.push(...previous.slice(op.from, op.from + op.count));
+  }
+  return result;
+}
+function deltaWins(delta, value) {
+  return JSON.stringify(delta).length < (JSON.stringify(value) ?? "null").length;
+}
+
+// src/live/watch-contract.ts
+import { z as z2 } from "zod";
+var WatchKeySchema = z2.object({
+  service: z2.string().min(1),
+  action: z2.string().min(1),
+  digest: z2.string().min(1)
+}).strict().readonly();
+var WatchHaveSchema = z2.object({ revision: z2.number().int().nonnegative(), fingerprint: z2.string().min(1) }).strict().readonly();
+var WatchOpenSchema = z2.object({ key: WatchKeySchema, args: z2.unknown(), have: WatchHaveSchema.optional() }).readonly();
+var WatchAcceptedSchema = z2.object({
+  accepted: z2.boolean(),
+  reason: z2.string().optional()
+}).strict().readonly();
+var watchValueParts = {
+  key: WatchKeySchema,
+  revision: z2.number().int().nonnegative(),
+  fingerprint: z2.string().min(1)
+};
+var WatchValueSchema = z2.discriminatedUnion("kind", [
+  z2.object({ kind: z2.literal("full"), ...watchValueParts, value: z2.unknown() }).readonly(),
+  z2.object({
+    kind: z2.literal("delta"),
+    ...watchValueParts,
+    base: z2.number().int().nonnegative(),
+    delta: WatchDeltaSchema
+  }).readonly(),
+  z2.object({ kind: z2.literal("unchanged"), ...watchValueParts }).readonly()
+]);
+var WatchStateSchema = z2.object({
+  key: WatchKeySchema,
+  phase: LiveStatePhaseSchema,
+  reason: LiveStateStopReasonSchema.optional(),
+  code: z2.string().optional(),
+  message: z2.string().optional()
+}).readonly();
+var WATCH_OPEN = "stitchkit.watch.open";
+var WATCH_CLOSE = "stitchkit.watch.close";
+var WATCH_VALUE = "stitchkit.watch.value";
+var WATCH_STATE = "stitchkit.watch.state";
+var watchContract = {
+  serverToClient: {
+    [WATCH_VALUE]: { args: z2.tuple([WatchValueSchema]) },
+    [WATCH_STATE]: { args: z2.tuple([WatchStateSchema]) }
+  },
+  clientToServer: {
+    [WATCH_OPEN]: { args: z2.tuple([WatchOpenSchema]), ack: WatchAcceptedSchema },
+    [WATCH_CLOSE]: { args: z2.tuple([z2.object({ key: WatchKeySchema }).readonly()]) }
+  }
+};
+function watchKeyString(key) {
+  return `${key.service}/${key.action}/${key.digest}`;
+}
+
+export { WatchDeltaSchema, WatchArrayOpSchema, diff, apply, deltaWins, WatchKeySchema, WatchHaveSchema, WatchValueSchema, WatchStateSchema, WATCH_OPEN, WATCH_CLOSE, WATCH_VALUE, WATCH_STATE, watchContract, watchKeyString };

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

@@ -44,7 +44,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 WatchKey, type WatchStateFrame, type WatchValueFrame } from './watch-contract.js';
+import { WATCH_CLOSE, 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. */
@@ -107,6 +107,7 @@ export interface WatchTransport {
     request(event: typeof WATCH_OPEN, payload: {
         key: WatchKey;
         args: unknown;
+        have?: WatchHave;
     }, options: {
         timeoutMs: number;
     }): Promise<{

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

@@ -26,6 +26,20 @@ export declare const WatchKeySchema: z.ZodReadonly<z.ZodObject<{
     digest: z.ZodString;
 }, z.core.$strict>>;
 export type WatchKey = z.infer<typeof WatchKeySchema>;
+/**
+ * What a subscriber already holds, offered when it opens a key.
+ *
+ * Both halves are needed and neither is redundant. The revision says *which*
+ * answer it has; the fingerprint proves it is that answer and not a different
+ * one wearing the same number — revisions restart at zero when a hub restarts or
+ * a key is released and re-acquired, so a bare revision would let a client keep
+ * a value from a previous life of the source and be told it was current.
+ */
+export declare const WatchHaveSchema: z.ZodReadonly<z.ZodObject<{
+    revision: z.ZodNumber;
+    fingerprint: z.ZodString;
+}, z.core.$strict>>;
+export type WatchHave = z.infer<typeof WatchHaveSchema>;
 export declare const WatchOpenSchema: z.ZodReadonly<z.ZodObject<{
     key: z.ZodReadonly<z.ZodObject<{
         service: z.ZodString;
@@ -33,20 +47,46 @@ export declare const WatchOpenSchema: z.ZodReadonly<z.ZodObject<{
         digest: z.ZodString;
     }, z.core.$strict>>;
     args: z.ZodUnknown;
+    have: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+        revision: z.ZodNumber;
+        fingerprint: z.ZodString;
+    }, z.core.$strict>>>;
 }, z.core.$strip>>;
 export declare const WatchAcceptedSchema: z.ZodReadonly<z.ZodObject<{
     accepted: z.ZodBoolean;
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>>;
-export declare const WatchValueSchema: z.ZodReadonly<z.ZodObject<{
+export declare const WatchValueSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
     key: z.ZodReadonly<z.ZodObject<{
         service: z.ZodString;
         action: z.ZodString;
         digest: z.ZodString;
     }, z.core.$strict>>;
     revision: z.ZodNumber;
+    fingerprint: z.ZodString;
+    kind: z.ZodLiteral<"full">;
     value: z.ZodUnknown;
-}, z.core.$strip>>;
+}, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+    key: z.ZodReadonly<z.ZodObject<{
+        service: z.ZodString;
+        action: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    revision: z.ZodNumber;
+    fingerprint: z.ZodString;
+    kind: z.ZodLiteral<"delta">;
+    base: z.ZodNumber;
+    delta: z.ZodType<import("./watch-delta.js").WatchDelta, unknown, z.core.$ZodTypeInternals<import("./watch-delta.js").WatchDelta, unknown>>;
+}, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+    key: z.ZodReadonly<z.ZodObject<{
+        service: z.ZodString;
+        action: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+    revision: z.ZodNumber;
+    fingerprint: z.ZodString;
+    kind: z.ZodLiteral<"unchanged">;
+}, z.core.$strip>>], "kind">;
 export declare const WatchStateSchema: z.ZodReadonly<z.ZodObject<{
     key: z.ZodReadonly<z.ZodObject<{
         service: z.ZodString;
@@ -88,15 +128,37 @@ export declare const WATCH_STATE = "stitchkit.watch.state";
 export declare const watchContract: {
     readonly serverToClient: {
         readonly "stitchkit.watch.value": {
-            readonly args: z.ZodTuple<[z.ZodReadonly<z.ZodObject<{
+            readonly args: z.ZodTuple<[z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
                 key: z.ZodReadonly<z.ZodObject<{
                     service: z.ZodString;
                     action: z.ZodString;
                     digest: z.ZodString;
                 }, z.core.$strict>>;
                 revision: z.ZodNumber;
+                fingerprint: z.ZodString;
+                kind: z.ZodLiteral<"full">;
                 value: z.ZodUnknown;
-            }, z.core.$strip>>], null>;
+            }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+                key: z.ZodReadonly<z.ZodObject<{
+                    service: z.ZodString;
+                    action: z.ZodString;
+                    digest: z.ZodString;
+                }, z.core.$strict>>;
+                revision: z.ZodNumber;
+                fingerprint: z.ZodString;
+                kind: z.ZodLiteral<"delta">;
+                base: z.ZodNumber;
+                delta: z.ZodType<import("./watch-delta.js").WatchDelta, unknown, z.core.$ZodTypeInternals<import("./watch-delta.js").WatchDelta, unknown>>;
+            }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+                key: z.ZodReadonly<z.ZodObject<{
+                    service: z.ZodString;
+                    action: z.ZodString;
+                    digest: z.ZodString;
+                }, z.core.$strict>>;
+                revision: z.ZodNumber;
+                fingerprint: z.ZodString;
+                kind: z.ZodLiteral<"unchanged">;
+            }, z.core.$strip>>], "kind">], null>;
         };
         readonly "stitchkit.watch.state": {
             readonly args: z.ZodTuple<[z.ZodReadonly<z.ZodObject<{
@@ -135,6 +197,10 @@ export declare const watchContract: {
                     digest: z.ZodString;
                 }, z.core.$strict>>;
                 args: z.ZodUnknown;
+                have: z.ZodOptional<z.ZodReadonly<z.ZodObject<{
+                    revision: z.ZodNumber;
+                    fingerprint: z.ZodString;
+                }, z.core.$strict>>>;
             }, z.core.$strip>>], null>;
             readonly ack: z.ZodReadonly<z.ZodObject<{
                 accepted: z.ZodBoolean;