stitchkit 0.75.0 → 0.76.0

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

@@ -64,12 +64,33 @@ export interface WatchHubConfig {
     /**
      * Perform one read. Supplied by the application, so a watched read goes
      * through the same authorization as the request it mirrors.
+     *
+     * **It is given no subscriber, and that is the guard, not an omission.** A key
+     * shares one read across everyone asking it, so a key that did not separate
+     * callers would hand one caller's answer to another. Here it cannot: an answer
+     * that depends on who is asking has to carry the asker in `args`, and `args`
+     * are what the key's digest is taken over — so two callers who differ get two
+     * keys and two reads, by construction rather than by discipline.
+     *
+     * The one way to defeat that is to resolve an identity from ambient state
+     * *inside* this function — a request-scoped context, a module-level "current
+     * user". Then every subscriber to that key receives whatever the first read
+     * happened to resolve. Do not; put the identity in the arguments.
      */
     read(operation: WatchOperation, args: unknown): Promise<unknown>;
     /** Whether an operation may be watched at all. Refusal is answered in words. */
     watchable(operation: WatchOperation): boolean;
-    /** The topics whose announcement means this operation's answer may have changed. */
-    invalidatedBy(operation: WatchOperation): readonly string[];
+    /**
+     * The topics whose announcement means this answer may have changed.
+     *
+     * Given the arguments as well as the operation, so a topic can name what the
+     * answer actually depends on: `chat.transcript:<address>` rather than
+     * `chat.transcript`. Without that narrowing, one address changing wakes every
+     * watcher of the operation — twenty conversations open means twenty reads for
+     * one change, and nineteen of them publish nothing because nothing changed.
+     * The read is still paid.
+     */
+    invalidatedBy(operation: WatchOperation, args: unknown): readonly string[];
     /** Subscribe to a topic; returns the unsubscribe. Normally an event bus's `on`. */
     subscribe(topic: string, listener: () => void): () => void;
     /** The most keys one subscriber may watch at once. Default 64. */

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;;;OAGG;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,oFAAoF;IACpF,aAAa,CAAC,SAAS,EAAE,cAAc,GAAG,SAAS,MAAM,EAAE,CAAC;IAC5D,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,wBAAsB,QAAQ,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAU1F;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CA0M/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,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,wBAAsB,QAAQ,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAU1F;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CA4M/D"}

package/dist/application.js

@@ -1610,7 +1610,7 @@ function createWatchHub(config) {
       state: { key, phase: "opening" },
       backoff: createBackoff(config.backoff ?? DEFAULT_BACKOFF)
     };
-    for (const topic of config.invalidatedBy(operation)) {
+    for (const topic of config.invalidatedBy(operation, args)) {
       source.unsubscribes.push(config.subscribe(topic, () => {
         source.dirty = true;
         pump(source);

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

@@ -17,6 +17,23 @@
  * `createUrlBuilder`, and the identity is the contract's own
  * `(prefix, endpoint key)` — the same pair the server labels every request with.
  *
+ * ## A connection is not forever, and recovering is this client's job
+ *
+ * A socket drops and comes back, and the hub forgets everything the old
+ * connection held — it releases a subscriber's keys the moment that subscriber
+ * detaches. So a client that opened each question once and never again is a
+ * client whose face freezes the first time a server restarts, *silently*,
+ * because nothing tells the subscriber that what it is looking at stopped being
+ * live.
+ *
+ * This client holds every key and every listener, so nobody else can do it: on a
+ * drop it tells subscribers the source is gone and forgets that anything was
+ * opened; on a fresh connection it re-opens every key that still has a listener.
+ * That is why {@link WatchTransport} **requires** `onConnectionChange` rather
+ * than using it when offered — a transport that cannot say when it reconnected
+ * cannot host a recovering client, and an optional hook would turn recovery into
+ * something that silently did not happen.
+ *
  * ## Retention
  *
  * The last value of a key is kept while anyone holds it, and for `holdMs` after
@@ -49,6 +66,15 @@ export interface WatchTransport {
         accepted: boolean;
         reason?: string;
     }>;
+    /**
+     * Observe connection changes. Required, because recovery depends on it.
+     *
+     * The hub releases a subscriber's keys when its connection detaches, so every
+     * question opened over the old socket is gone the moment it drops. Without
+     * this the client would go on believing it was subscribed and show a face that
+     * had quietly stopped updating.
+     */
+    onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void;
 }
 export interface WatchClientConfig {
     readonly transport: WatchTransport;

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,eAAe,EAGrB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,cAAc,CAAC,MAAM;IACpC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kEAAkE;IAClE,KAAK,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,WAAW,CAAC,MAAM;IACjC,sFAAsF;IACtF,SAAS,CAAC,SAAS,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC;IACzD,wEAAwE;IACxE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACjE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,OAAO,CACL,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAC7B,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAcD,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI;KACnE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,WAAW,CAAC,OAAO,CAAC;CACzE,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrE,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,MAAM,EAAE,iBAAiB,GACxB,gBAAgB,CAAC,CAAC,CAAC,CAqKrB"}
+{"version":3,"file":"watch-client.d.ts","sourceRoot":"","sources":["../../src/live/watch-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,eAAe,EAGrB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,cAAc,CAAC,MAAM;IACpC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kEAAkE;IAClE,KAAK,CAAC,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,WAAW,CAAC,MAAM;IACjC,sFAAsF;IACtF,SAAS,CAAC,SAAS,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC;IACzD,wEAAwE;IACxE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACjE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5C,OAAO,CACL,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAC7B,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD;;;;;;;OAOG;IACH,kBAAkB,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACzF;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAuBD,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI;KACnE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,WAAW,CAAC,OAAO,CAAC;CACzE,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrE,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,MAAM,EAAE,iBAAiB,GACxB,gBAAgB,CAAC,CAAC,CAAC,CAwNrB"}

package/dist/live.js

@@ -122,6 +122,11 @@ function createWatchClient(contract, config) {
   const holdMs = config.holdMs ?? 0;
   const openTimeoutMs = config.openTimeoutMs ?? 1e4;
   const service = contract.meta.prefix;
+  function publishState(entry, state) {
+    entry.state = state;
+    for (const listener of [...entry.listeners])
+      listener.state?.(state);
+  }
   config.transport.on(WATCH_VALUE, (frame) => {
     const entry = entries.get(watchKeyString(frame.key));
     if (!entry)
@@ -138,9 +143,27 @@ function createWatchClient(contract, config) {
     const entry = entries.get(watchKeyString(frame.key));
     if (!entry)
       return;
-    entry.state = frame;
-    for (const listener of [...entry.listeners])
-      listener.state?.(frame);
+    publishState(entry, frame);
+  });
+  config.transport.onConnectionChange((connected, reason) => {
+    if (!connected) {
+      for (const entry of entries.values()) {
+        entry.opened = false;
+        publishState(entry, {
+          key: entry.key,
+          phase: "unavailable",
+          reason: "source-unavailable",
+          ...reason !== undefined && { message: reason }
+        });
+      }
+      return;
+    }
+    for (const entry of entries.values()) {
+      if (entry.listeners.size === 0)
+        continue;
+      publishState(entry, { key: entry.key, phase: "opening" });
+      open(entry);
+    }
   });
   function cachedDigest(action, args) {
     return digests.get(`${service}/${action}/${JSON.stringify(stableValue(args))}`);
@@ -154,7 +177,7 @@ function createWatchClient(contract, config) {
     digests.set(cacheKey, digest);
     return digest;
   }
-  function entryFor(key) {
+  function entryFor(key, args) {
     const id = watchKeyString(key);
     const existing = entries.get(id);
     if (existing) {
@@ -164,14 +187,44 @@ function createWatchClient(contract, config) {
     }
     const entry = {
       key,
+      args,
       listeners: new Set,
       revision: 0,
       hasValue: false,
+      opened: false,
       state: { key, phase: "opening" }
     };
     entries.set(id, entry);
     return entry;
   }
+  async function open(entry) {
+    if (entry.opened)
+      return;
+    entry.opened = true;
+    try {
+      const acknowledgement = await config.transport.request(WATCH_OPEN, { key: entry.key, args: entry.args }, { timeoutMs: openTimeoutMs });
+      if (!acknowledgement.accepted) {
+        const reason = acknowledgement.reason ?? "the server refused this watch";
+        config.onRefused?.(entry.key, reason);
+        publishState(entry, {
+          key: entry.key,
+          phase: "unavailable",
+          reason: "source-unavailable",
+          message: reason
+        });
+      }
+    } catch (error) {
+      entry.opened = false;
+      const code = typeof error === "object" && error !== null && "code" in error ? String(Reflect.get(error, "code")) : undefined;
+      publishState(entry, {
+        key: entry.key,
+        phase: "unavailable",
+        reason: "source-unavailable",
+        ...code !== undefined && { code },
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
   function releaseEntry(entry) {
     if (entry.listeners.size > 0)
       return;
@@ -191,36 +244,16 @@ function createWatchClient(contract, config) {
   function handleFor(action, args) {
     const mine = new Set;
     let entry;
-    let opened = false;
     const known = cachedDigest(action, args);
     if (known !== undefined)
-      entry = entryFor({ service, action, digest: known });
+      entry = entryFor({ service, action, digest: known }, args);
     const ready = (async () => {
       if (entry)
         return entry;
       const digest = await resolveDigest(action, args);
-      entry = entryFor({ service, action, digest });
+      entry = entryFor({ service, action, digest }, args);
       return entry;
     })();
-    async function open(target) {
-      if (opened)
-        return;
-      opened = true;
-      const acknowledgement = await config.transport.request(WATCH_OPEN, { key: target.key, args }, { timeoutMs: openTimeoutMs });
-      if (!acknowledgement.accepted) {
-        const reason = acknowledgement.reason ?? "the server refused this watch";
-        config.onRefused?.(target.key, reason);
-        const refusal = {
-          key: target.key,
-          phase: "unavailable",
-          reason: "source-unavailable",
-          message: reason
-        };
-        target.state = refusal;
-        for (const listener of [...target.listeners])
-          listener.state?.(refusal);
-      }
-    }
     return {
       subscribe(listeners) {
         const registered = listeners;

package/dist/server/index.js

@@ -875,6 +875,14 @@ function createTrustFence(config) {
     }
     trusted.push(authority);
   }
+  const trustedOrigins = [];
+  for (const entry of config.trustedOrigins ?? []) {
+    const authority = readAuthority(entry);
+    if (!authority) {
+      throw new Error(`[stitchkit] trust fence: trustedOrigins entry "${entry}" is not an authority. An entry is \`host\` or \`host:port\` — no scheme, no path, no wildcard, the same form as trustedHosts.`);
+    }
+    trustedOrigins.push(authority);
+  }
   function refuse(refusal) {
     config.onRefused?.(refusal);
     config.logger?.warn?.("[stitchkit] trust fence refused a request", {
@@ -911,7 +919,9 @@ function createTrustFence(config) {
       } catch {
         originAuthority = undefined;
       }
-      const agrees = originAuthority !== undefined && originAuthority.hostname === requested.hostname && comparablePort(originAuthority.port) === comparablePort(requested.port);
+      const sameAuthority = originAuthority !== undefined && originAuthority.hostname === requested.hostname && comparablePort(originAuthority.port) === comparablePort(requested.port);
+      const declared = originAuthority !== undefined && trustedOrigins.some((entry) => entry.hostname === originAuthority.hostname && (entry.port === null || entry.port === originAuthority.port));
+      const agrees = sameAuthority || declared;
       if (!agrees) {
         return refuse({ reason: "origin-mismatch", lane, host, origin, site });
       }

package/dist/server/middleware/trust-fence.d.ts

@@ -84,6 +84,27 @@ export interface TrustFenceConfig {
      * list it when you want it.
      */
     readonly trustedHosts: readonly string[];
+    /**
+     * Origins allowed to address this server from a different authority.
+     *
+     * Same entry format as {@link trustedHosts} — `host` or `host:port`, compared
+     * against the `Origin`'s authority. Absent, only an `Origin` that matches the
+     * `Host` is accepted, which is the safe default and also refuses the most
+     * ordinary arrangement there is: a UI dev server on one port talking to an API
+     * on the next. That is the case this exists for.
+     *
+     * Worth knowing what the `Origin` check is and is not for, because the
+     * question comes up the moment it refuses something. It is **not** what stops
+     * DNS rebinding: that attack is same-origin by construction — the page believes
+     * it *is* the target authority — so it sends a matching `Origin` or none at
+     * all, and {@link trustedHosts} is what refuses it. What the `Origin` check
+     * stops is a plain cross-origin request from a page that never needs to read
+     * the reply: CORS governs whether a response can be *read*, never whether the
+     * request is *sent*, so a state-changing endpoint is reachable without it.
+     * That is why the answer here is a declared list rather than dropping the
+     * check.
+     */
+    readonly trustedOrigins?: readonly string[];
     /** Called on every refusal, before the 403 is written. */
     readonly onRefused?: (refusal: TrustRefusal) => void;
     /** Refusals are logged at `warn` when a logger is supplied. */

package/dist/server/middleware/trust-fence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trust-fence.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/trust-fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,qCAAqC;AACrC,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE1C,MAAM,MAAM,kBAAkB;AAC5B,yEAAyE;AACvE,cAAc;AAChB,wEAAwE;GACtE,gBAAgB;AAClB,iEAAiE;GAC/D,iBAAiB;AACnB,4DAA4D;GAC1D,YAAY,CAAC;AAEjB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IACrD,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAClD,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;IAC7C,oFAAoF;IACpF,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;CACpE;AAyDD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAM1D;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA2FrE"}
+{"version":3,"file":"trust-fence.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/trust-fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,qCAAqC;AACrC,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE1C,MAAM,MAAM,kBAAkB;AAC5B,yEAAyE;AACvE,cAAc;AAChB,wEAAwE;GACtE,gBAAgB;AAClB,iEAAiE;GAC/D,iBAAiB;AACnB,4DAA4D;GAC1D,YAAY,CAAC;AAEjB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAC;IACrD,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;IAClD,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;IAC7C,oFAAoF;IACpF,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;CACpE;AAyDD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAM1D;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CA6GrE"}

package/llms-full.txt

@@ -62,7 +62,7 @@ own, recorded as an ADR.
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 11 of the 20 minors since 0.56.2, most recently 0.75.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 11 of the 21 minors since 0.56.2, most recently 0.75.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -70,7 +70,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | server | evolving<br>_redefined in 4 of the 20 minors since 0.56.2, most recently 0.72.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
+| `stitchkit/application` | server | evolving<br>_redefined in 4 of the 21 minors since 0.56.2, most recently 0.72.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 
@@ -7636,6 +7636,33 @@ order-independent — `{a, b}` and `{b, a}` are the same question, which a plain
 `JSON.stringify` key would get wrong exactly when two components happen to build
 their argument object in a different order.
 
+### Narrow the topic to the arguments
+
+`invalidatedBy` is given the arguments as well as the operation, so a topic can
+name what the answer actually depends on:
+
+```ts
+invalidatedBy: (operation, args) => [`chat.transcript:${args.address}`],
+```
+
+Without that, one address changing wakes every watcher of the operation. Twenty
+conversations open means twenty reads for one change — nineteen of them publish
+nothing, because nothing changed, and the read is paid anyway.
+
+### Who shares with whom
+
+A key is `(service, action, digest of arguments)`, and everyone on that key gets
+one read. So the question a sharing primitive has to answer is what keeps one
+caller's answer from reaching another — and here the answer is structural:
+`read` is **given no subscriber**. An answer that depends on who is asking has to
+carry the asker in its arguments, and the arguments are what the digest is taken
+over, so two callers who differ get two keys and two reads.
+
+The one way to defeat that is to resolve an identity from ambient state *inside*
+`read` — a request-scoped context, a module-level "current user". Then every
+subscriber on that key receives whatever the first read happened to resolve.
+Put the identity in the arguments instead.
+
 ### Three states, not two
 
 `state.phase` comes from `LiveStatePhase`, the vocabulary the live-state
@@ -7647,6 +7674,20 @@ A failed read arrives as `unavailable` with the read's own `code` and `message`.
 The hub retries on its own backoff, and a success clears the state without anyone
 asking.
 
+### Across a reconnect
+
+The hub releases a connection's keys when it detaches, so everything opened over
+the old socket is gone the moment it drops. The client recovers on its own: on a
+drop your `state` listener gets `unavailable` / `source-unavailable`, and on the
+next connection every key that still has a listener is re-opened and the values
+resume. That is what `onConnectionChange` on the transport is for, and why it is
+required rather than optional — a client that cannot be told has no way to
+notice, and the face stops updating without a word.
+
+Nothing an open can fail with escapes as a rejected promise: a disconnected
+socket, a timeout, a refusal all arrive as `unavailable` carrying the error's own
+code and message, and the next connection retries.
+
 ### `watch` or `createLiveStateController`?
 
 > **If you would have written `applyEvent` as `(_, next) => next`, you want
@@ -7731,6 +7772,32 @@ createServer({
 });
 ```
 
+### A UI on one port, an API on the next
+
+The most ordinary arrangement in development is also the one the fence refuses by
+default: a UI dev server on `:5180` calling an API on `:5181`. The browser sends
+`Origin: http://localhost:5180` to `Host: localhost:5181`, they differ, and both
+lanes answer 403. Declare the second origin:
+
+```ts
+createTrustFence({
+  trustedHosts: ['localhost:5181'],
+  trustedOrigins: ['localhost:5180'],
+});
+```
+
+Same entry format as `trustedHosts`, compared against the `Origin`'s authority.
+Declaring one does not widen anything else: an undeclared origin is still
+refused, and `trustedHosts` still decides which authority the server answers on.
+
+It is worth knowing what the `Origin` check is for, because it is not what most
+people assume. It is **not** the DNS-rebinding defence — that attack is
+same-origin by construction, so it sends a matching `Origin` or none at all, and
+`trustedHosts` is what refuses it. What the `Origin` check stops is a plain
+cross-origin request from a page that never needs to read the reply: CORS governs
+whether a response can be *read*, never whether the request is *sent*, so a
+state-changing endpoint is reachable without it.
+
 ### Install **both** halves
 
 `fence.hooks` fences HTTP. `fence.allowRequest` fences the Socket.IO lane — and
@@ -9904,6 +9971,28 @@ makes one thing your job rather than the resolver's:
 The mechanical part is identical either way. Only the *noticing* differs, and an
 exact pin moves it onto you.
 
+## Released migration: 0.76.0
+
+One change, and only if you hand `createWatchClient` a transport you wrote yourself.
+
+```bash
+rg -n "createWatchClient" --glob '*.ts'
+```
+
+If the `transport:` you pass is a bound realtime client — `bindRealtimeClient(...)` or
+`createRealtimeClient(...)` — there is nothing to do: it already carries
+`onConnectionChange`. If it is an object you assembled, add the fourth member:
+
+```ts
+onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void
+```
+
+It is required because the client recovers through it: on a drop it publishes
+`unavailable` to subscribers and forgets what was opened, and on a fresh
+connection it re-opens every key that still has a listener. Without it a watch
+stays "open" on the client after a server restart while the hub remembers
+nothing, and the face stops updating without saying so.
+
 ## Released migration: 0.75.0
 
 Two mechanical renames and one option that has to move. Nothing about a passing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",