@loomwork/live-query 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/NOTICE

@@ -0,0 +1,8 @@
+Loom
+Copyright 2026 Sushil Chhetri
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this project except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @loomwork/live-query — live reads of in-flight executions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`loadState` folds an execution's state on demand; a **live query** is that plus a subscription:
+re-fold and push the new state each time an event lands. No syscall, no new event type — a read-model
+over `loadState` + `EventStore.subscribe` (P10). See [ADR 0040](../../docs/adr/0040-live-query-and-orchestration.md).
+
+```ts
+import { liveQuery } from "@loomwork/live-query";
+
+const lq = liveQuery({ eventStore, reader: runtime });
+
+await lq.snapshot(executionId); // current folded state, or null
+
+const unsubscribe = await lq.subscribe(executionId, (state) => {
+  render(state);              // called now with the current state, then on every new event
+  if (state.status === "completed") unsubscribe();
+});
+```
+
+Updates are **coalesced**: only one re-fold runs at a time, and a burst of events triggers exactly
+one more (latest-wins), so a subscriber never sees stale-then-newer out of order.
+
+A wake-up lost across nodes, for example to a full Postgres NOTIFY queue, is not sent later. So each subscription
+also re-reads the log every `pollMs` (default 5 s) until its state is terminal, and a lost wake-up costs that much
+delay. A live subscription costs at most two indexed reads per interval. `pollMs: 0` turns this off, and then a lost
+wake-up is only recovered by that execution's next event.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { type LiveQuery, type LiveQueryDeps, type StateReader, liveQuery } from "./liveQuery";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+// @loomwork/live-query — live reads of in-flight executions.
+//
+// `snapshot(id)` folds current state on demand; `subscribe(id, cb)` pushes the state
+// again on every new event. A read-model over loadState + EventStore.subscribe — no
+// syscall, no new event type (P10).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liveQuery = void 0;
+var liveQuery_1 = require("./liveQuery");
+Object.defineProperty(exports, "liveQuery", { enumerable: true, get: function () { return liveQuery_1.liveQuery; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,6DAA6D;AAC7D,EAAE;AACF,qFAAqF;AACrF,oFAAoF;AACpF,oCAAoC;;;AAEpC,yCAA8F;AAA/B,sGAAA,SAAS,OAAA"}

package/dist/liveQuery.d.ts

@@ -0,0 +1,42 @@
+import type { ExecutionState } from "@loomwork/core";
+import type { EventStore } from "@loomwork/event-runtime";
+/** The runtime capability a live query needs — just the folding read. */
+export interface StateReader {
+    loadState(executionId: string, options?: {
+        principal?: unknown;
+    }): Promise<ExecutionState | null>;
+}
+export interface LiveQuery {
+    /** The current folded state (null if the execution is unknown). */
+    snapshot(executionId: string): Promise<ExecutionState | null>;
+    /**
+     * Push the current state now, then again after every subsequent event, until the
+     * returned unsubscribe is called. `onState` receives a coalesced latest-wins state;
+     * a terminal state is delivered before teardown so callers can stop on completion.
+     */
+    subscribe(executionId: string, onState: (state: ExecutionState) => void): Promise<() => void>;
+}
+export interface LiveQueryDeps {
+    eventStore: EventStore;
+    reader: StateReader;
+    /**
+     * Reports a BACKGROUND re-fold that failed — a store read that rejected, or an `onState`
+     * callback that threw. Those run from the store's subscribe callback with nothing
+     * awaiting them, so without this the rejection is unhandled and the process exits.
+     *
+     * The subscription stays live: one failed re-fold costs that update, and the next event
+     * folds from the log again. Unset, failures are swallowed — never rethrown, because
+     * there is no caller left to catch them.
+     */
+    onError?: (err: unknown) => void;
+    /**
+     * How often each subscription re-reads the log, in case a wake-up was lost. It stops once the
+     * state is terminal, and each quiet pass costs one or two indexed reads, so a live subscription
+     * costs at most two reads per interval. `0` turns it off, which means a lost wake-up is only
+     * recovered by that execution's next event. Default 5000.
+     */
+    pollMs?: number;
+}
+/** Build a {@link LiveQuery} over a store + a state reader (typically the runtime). */
+export declare function liveQuery(deps: LiveQueryDeps): LiveQuery;
+//# sourceMappingURL=liveQuery.d.ts.map

package/dist/liveQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveQuery.d.ts","sourceRoot":"","sources":["../src/liveQuery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAsD1D,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACnG;AAED,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC9D;;;;OAIG;IACH,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;CAC/F;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAUD,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,SAAS,CAgGxD"}

package/dist/liveQuery.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liveQuery = liveQuery;
+const replay_vm_1 = require("@loomwork/replay-vm");
+const DEFAULT_POLL_MS = 5_000;
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+    "continued",
+]);
+/** Build a {@link LiveQuery} over a store + a state reader (typically the runtime). */
+function liveQuery(deps) {
+    const snapshot = (executionId) => deps.reader.loadState(executionId);
+    return {
+        snapshot,
+        async subscribe(executionId, onState) {
+            // Coalesce: only ever one re-fold in flight; if events arrive during a fold,
+            // do exactly one more afterwards (latest-wins) so a burst is O(1) extra folds,
+            // not one per event, and callers never see stale-then-newer out of order.
+            let refolding = false;
+            let dirty = false;
+            // Per-subscription incremental fold state. `state === null` means "no baseline
+            // yet" — the ONLY condition under which a pass does the full `reader.loadState`;
+            // every other pass reads just the tail past `tip` and folds it onto `state`.
+            let state = null;
+            let tip = -1;
+            const pump = async () => {
+                if (refolding) {
+                    dirty = true;
+                    return;
+                }
+                refolding = true;
+                try {
+                    do {
+                        dirty = false;
+                        if (state === null) {
+                            state = await deps.reader.loadState(executionId);
+                            if (state !== null)
+                                tip = state.sequence;
+                        }
+                        else {
+                            const delta = await deps.eventStore.readFrom(executionId, tip + 1);
+                            if (delta.length === 0) {
+                                // Nothing new — UNLESS a compaction truncated everything after `tip` with
+                                // no later event yet to reveal the gap. Only checked when the store has a
+                                // cheap indexed tip, so an empty wake-up never costs a full read.
+                                const head = deps.eventStore.head
+                                    ? await deps.eventStore.head(executionId)
+                                    : undefined;
+                                if (head === undefined || head === null || head >= tip)
+                                    continue; // truly nothing new
+                                state = await deps.reader.loadState(executionId);
+                                if (state !== null)
+                                    tip = state.sequence;
+                            }
+                            else if (delta[0].sequence !== tip + 1 ||
+                                delta[delta.length - 1].sequence - tip !== delta.length) {
+                                // Non-contiguous: a compaction truncated events between `tip` and the
+                                // first surviving one out from under this subscription — or, since ADR 0106
+                                // keeps an app's pinned-kind events in place, a kept event sits at `tip + 1`
+                                // and the gap is INSIDE the delta (sequences are unique and sorted, so the
+                                // delta is contiguous iff its span equals its length: O(1)). Folding `delta`
+                                // onto `state` here would silently produce a WRONG `ExecutionState` — fall
+                                // back to a full fold, exactly like the one-time initial load.
+                                state = await deps.reader.loadState(executionId);
+                                if (state !== null)
+                                    tip = state.sequence;
+                            }
+                            else {
+                                // `foldEvents` treats `state` as immutable (fresh audit-list ownership per
+                                // pass), so folding the delta onto the kept state never mutates what a
+                                // previous `onState` call was handed.
+                                state = (0, replay_vm_1.foldEvents)(delta, state);
+                                tip = delta[delta.length - 1].sequence;
+                            }
+                        }
+                        if (state !== null)
+                            onState(state);
+                    } while (dirty);
+                }
+                finally {
+                    refolding = false;
+                }
+            };
+            const unsubscribe = await deps.eventStore.subscribe(executionId, (_e) => {
+                // Background re-fold: nothing awaits it, so it must never escape as an unhandled
+                // rejection. The FIRST fold below is different — the caller awaits `subscribe`, so
+                // a failure there is theirs to see and is deliberately left to propagate.
+                void pump().catch((err) => deps.onError?.(err));
+            });
+            // Emit the current state immediately so a subscriber isn't blind until the next event.
+            await pump();
+            const pollMs = deps.pollMs ?? DEFAULT_POLL_MS;
+            if (!(pollMs > 0))
+                return unsubscribe;
+            const poll = setInterval(() => {
+                if (state !== null && TERMINAL_STATUSES.has(state.status)) {
+                    clearInterval(poll);
+                    return;
+                }
+                if (refolding)
+                    return; // the pass in flight already reads the log
+                void pump().catch((err) => deps.onError?.(err));
+            }, pollMs);
+            poll.unref?.();
+            return () => {
+                clearInterval(poll);
+                unsubscribe();
+            };
+        },
+    };
+}
+//# sourceMappingURL=liveQuery.js.map

package/dist/liveQuery.js.map

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

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@loomwork/live-query",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Live queries over in-flight Loom executions — read the current folded state and subscribe to updates as new events land, without a syscall. A read-model over loadState + EventStore.subscribe.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@loomwork/replay-vm": "^0.1.1",
+    "@loomwork/core": "^0.1.1",
+    "@loomwork/workflow-runtime": "^0.1.1",
+    "@loomwork/event-runtime": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.11.0",
+    "pg": "^8.13.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8",
+    "zod": "^3.23.8",
+    "@loomwork/plugin-postgres": "0.1.1",
+    "@loomwork/snapshot-runtime": "0.1.1",
+    "@loomwork/plugin-content": "0.1.1",
+    "@loomwork/effect-runtime": "0.1.1"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom.git",
+    "directory": "packages/live-query"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__",
+    "!src/**/__snapshots__",
+    "!src/**/__golden__",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  }
 }

package/src/index.ts

@@ -0,0 +1,7 @@
+// @loomwork/live-query — live reads of in-flight executions.
+//
+// `snapshot(id)` folds current state on demand; `subscribe(id, cb)` pushes the state
+// again on every new event. A read-model over loadState + EventStore.subscribe — no
+// syscall, no new event type (P10).
+
+export { type LiveQuery, type LiveQueryDeps, type StateReader, liveQuery } from "./liveQuery";

package/src/liveQuery.ts

@@ -0,0 +1,199 @@
+import type { EventEnvelope, ExecutionState } from "@loomwork/core";
+import type { EventStore } from "@loomwork/event-runtime";
+import { foldEvents } from "@loomwork/replay-vm";
+
+// ── Live query over an in-flight execution ────────────────────────────────────
+//
+// Loom's `loadState` already folds an execution's durable state on demand (bounded by
+// snapshots) — that IS a query. A LIVE query is that plus a subscription: re-fold and
+// push the new state each time an event lands. This needs NO syscall and NO new event
+// type — it composes `loadState` with `EventStore.subscribe`, so it stays a read-model
+// concern (P10), never a kernel primitive.
+//
+// INCREMENTAL FOLD — the one-time full load, then deltas only. `loadState` bounds a
+// single fold's I/O with snapshots, but a live subscriber re-folding from genesis on
+// EVERY event is still O(N) rows per event and O(N²) over an execution's lifetime (see
+// `WorkflowRuntime.foldState`'s docstring). So `subscribe` calls `reader.loadState`
+// exactly ONCE per subscription — establishing `state` and `tip` (the last folded
+// sequence) — and every later wake-up instead reads only the tail since `tip`
+// (`eventStore.readFrom(id, tip + 1)`) and folds that delta onto the kept `state` with
+// the kernel's own `foldEvents` (no new fold, no new version — `fold(snapshot, suffix)
+// === fold(events)` is already load-bearing for snapshots/compaction). Total I/O goes
+// from O(N²) to O(N).
+//
+// It reads the delta rather than folding the delivered envelope because delivery can be
+// gapped, duplicated or cross-node — `readFrom` handles all three for free — and because
+// `ContentResolvingEventStore.subscribe` deliberately delivers the RAW ref-bearing event
+// when resolution fails, whereas its read path throws `ContentMissingError` loudly. An
+// empty delta emits nothing; a deleted execution (`readFrom` returns `[]` forever) stays
+// silent, same as today's `null`-skipping.
+//
+// The gate for "still need the one-time full load" is `state === null` — not a separate
+// boolean — because a subscription started before the execution exists must keep asking
+// the reader (cheaply: an empty log) until the reader hands back a real baseline with the
+// executionId/workflowId identity `foldEvents([], undefined)` cannot invent on its own.
+//
+// COMPACTION CAN MOVE THE FLOOR OUT FROM UNDER `tip`. `LogLifecycle.compact` (K10.4)
+// checkpoints a snapshot and then truncates `(0..throughSequence]` out of the log — legal,
+// because `fold(snapshot, suffix) === fold(events)`, but it invalidates `readFrom(tip + 1)`
+// for any subscriber whose `tip` sits behind `throughSequence`: the returned delta either
+// starts PAST `tip + 1` (a gap — the events in between were truncated) or comes back empty
+// while the log's own tip has moved BEHIND ours (nothing left there to read `tip + 1`
+// from). Folding a non-contiguous delta onto stale `state` would silently produce a WRONG
+// `ExecutionState` with no error — so both signals fall back to a full `reader.loadState`
+// (the same one-time-load path as the initial fold) instead, and folding resumes
+// incrementally from ITS tip. The empty-delta check only runs when the store exposes the
+// optional, O(1) `head` — a store without it is tolerated (no fallback full read; the very
+// next non-empty delta still self-heals via the gap check), so this can never turn an
+// empty wake-up into an unbounded read and break the O(N) bound above.
+//
+// A WAKE-UP CAN BE LOST. Cross-node delivery is not guaranteed: a dropped listener or a full
+// Postgres NOTIFY queue costs a wake-up, and a lost one is not sent later. An execution whose last
+// event was the lost one would otherwise never pump again, so a caller waiting to see `completed`
+// would wait forever. So each subscription also pumps on a timer, until its state is terminal. A
+// quiet pump reads only the empty tail past `tip` (the O(N) bound above holds) and emits nothing.
+
+/** The runtime capability a live query needs — just the folding read. */
+export interface StateReader {
+  loadState(executionId: string, options?: { principal?: unknown }): Promise<ExecutionState | null>;
+}
+
+export interface LiveQuery {
+  /** The current folded state (null if the execution is unknown). */
+  snapshot(executionId: string): Promise<ExecutionState | null>;
+  /**
+   * Push the current state now, then again after every subsequent event, until the
+   * returned unsubscribe is called. `onState` receives a coalesced latest-wins state;
+   * a terminal state is delivered before teardown so callers can stop on completion.
+   */
+  subscribe(executionId: string, onState: (state: ExecutionState) => void): Promise<() => void>;
+}
+
+export interface LiveQueryDeps {
+  eventStore: EventStore;
+  reader: StateReader;
+  /**
+   * Reports a BACKGROUND re-fold that failed — a store read that rejected, or an `onState`
+   * callback that threw. Those run from the store's subscribe callback with nothing
+   * awaiting them, so without this the rejection is unhandled and the process exits.
+   *
+   * The subscription stays live: one failed re-fold costs that update, and the next event
+   * folds from the log again. Unset, failures are swallowed — never rethrown, because
+   * there is no caller left to catch them.
+   */
+  onError?: (err: unknown) => void;
+  /**
+   * How often each subscription re-reads the log, in case a wake-up was lost. It stops once the
+   * state is terminal, and each quiet pass costs one or two indexed reads, so a live subscription
+   * costs at most two reads per interval. `0` turns it off, which means a lost wake-up is only
+   * recovered by that execution's next event. Default 5000.
+   */
+  pollMs?: number;
+}
+
+const DEFAULT_POLL_MS = 5_000;
+const TERMINAL_STATUSES: ReadonlySet<string> = new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "continued",
+]);
+
+/** Build a {@link LiveQuery} over a store + a state reader (typically the runtime). */
+export function liveQuery(deps: LiveQueryDeps): LiveQuery {
+  const snapshot = (executionId: string): Promise<ExecutionState | null> =>
+    deps.reader.loadState(executionId);
+
+  return {
+    snapshot,
+    async subscribe(executionId, onState): Promise<() => void> {
+      // Coalesce: only ever one re-fold in flight; if events arrive during a fold,
+      // do exactly one more afterwards (latest-wins) so a burst is O(1) extra folds,
+      // not one per event, and callers never see stale-then-newer out of order.
+      let refolding = false;
+      let dirty = false;
+
+      // Per-subscription incremental fold state. `state === null` means "no baseline
+      // yet" — the ONLY condition under which a pass does the full `reader.loadState`;
+      // every other pass reads just the tail past `tip` and folds it onto `state`.
+      let state: ExecutionState | null = null;
+      let tip = -1;
+
+      const pump = async (): Promise<void> => {
+        if (refolding) {
+          dirty = true;
+          return;
+        }
+        refolding = true;
+        try {
+          do {
+            dirty = false;
+            if (state === null) {
+              state = await deps.reader.loadState(executionId);
+              if (state !== null) tip = state.sequence;
+            } else {
+              const delta = await deps.eventStore.readFrom(executionId, tip + 1);
+              if (delta.length === 0) {
+                // Nothing new — UNLESS a compaction truncated everything after `tip` with
+                // no later event yet to reveal the gap. Only checked when the store has a
+                // cheap indexed tip, so an empty wake-up never costs a full read.
+                const head = deps.eventStore.head
+                  ? await deps.eventStore.head(executionId)
+                  : undefined;
+                if (head === undefined || head === null || head >= tip) continue; // truly nothing new
+                state = await deps.reader.loadState(executionId);
+                if (state !== null) tip = state.sequence;
+              } else if (
+                delta[0]!.sequence !== tip + 1 ||
+                delta[delta.length - 1]!.sequence - tip !== delta.length
+              ) {
+                // Non-contiguous: a compaction truncated events between `tip` and the
+                // first surviving one out from under this subscription — or, since ADR 0106
+                // keeps an app's pinned-kind events in place, a kept event sits at `tip + 1`
+                // and the gap is INSIDE the delta (sequences are unique and sorted, so the
+                // delta is contiguous iff its span equals its length: O(1)). Folding `delta`
+                // onto `state` here would silently produce a WRONG `ExecutionState` — fall
+                // back to a full fold, exactly like the one-time initial load.
+                state = await deps.reader.loadState(executionId);
+                if (state !== null) tip = state.sequence;
+              } else {
+                // `foldEvents` treats `state` as immutable (fresh audit-list ownership per
+                // pass), so folding the delta onto the kept state never mutates what a
+                // previous `onState` call was handed.
+                state = foldEvents(delta, state);
+                tip = delta[delta.length - 1]!.sequence;
+              }
+            }
+            if (state !== null) onState(state);
+          } while (dirty);
+        } finally {
+          refolding = false;
+        }
+      };
+
+      const unsubscribe = await deps.eventStore.subscribe(executionId, (_e: EventEnvelope) => {
+        // Background re-fold: nothing awaits it, so it must never escape as an unhandled
+        // rejection. The FIRST fold below is different — the caller awaits `subscribe`, so
+        // a failure there is theirs to see and is deliberately left to propagate.
+        void pump().catch((err: unknown) => deps.onError?.(err));
+      });
+      // Emit the current state immediately so a subscriber isn't blind until the next event.
+      await pump();
+      const pollMs = deps.pollMs ?? DEFAULT_POLL_MS;
+      if (!(pollMs > 0)) return unsubscribe;
+      const poll = setInterval(() => {
+        if (state !== null && TERMINAL_STATUSES.has(state.status)) {
+          clearInterval(poll);
+          return;
+        }
+        if (refolding) return; // the pass in flight already reads the log
+        void pump().catch((err: unknown) => deps.onError?.(err));
+      }, pollMs);
+      poll.unref?.();
+      return () => {
+        clearInterval(poll);
+        unsubscribe();
+      };
+    },
+  };
+}