@loomwork/ui-changes 0.0.0-stage → 0.1.1

package/dist/feed.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LineageChangeFeed = exports.MAX_PAGE = exports.DEFAULT_PAGE = void 0;
+const ui_core_1 = require("@loomwork/ui-core");
+const ui_lineage_1 = require("@loomwork/ui-lineage");
+exports.DEFAULT_PAGE = 100;
+exports.MAX_PAGE = 1000;
+const err = (code, message) => ({
+    ok: false,
+    finding: { code, severity: "error", message },
+});
+const asCursor = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0 ? v : undefined;
+/**
+ * A `ChangeFeed` over a `Lineage`. `read` folds the whole line (validating it: a malformed log is a
+ * finding, never partial events) so it is O(log length) per call; a deployment with very long lines
+ * pages with `limit` but still pays the fold: cache above this seam, not inside it.
+ */
+class LineageChangeFeed {
+    lineage;
+    events;
+    signal;
+    policy;
+    constructor(opts) {
+        this.policy = (0, ui_core_1.mergeReadPolicy)(opts.lineage.readPolicy, opts.readPolicy, opts);
+        this.lineage = opts.lineage;
+        this.events = opts.events;
+        this.signal = opts.signal;
+    }
+    async read(experienceId, opts = {}) {
+        const after = opts.after === undefined ? 0 : asCursor(opts.after);
+        if (after === undefined)
+            return err("cursor-invalid", "after is not a non-negative integer");
+        const limit = opts.limit === undefined
+            ? exports.DEFAULT_PAGE
+            : Number.isSafeInteger(opts.limit) && opts.limit >= 1
+                ? Math.min(opts.limit, exports.MAX_PAGE)
+                : undefined;
+        if (limit === undefined)
+            return err("limit-invalid", "limit is not a positive integer");
+        let records;
+        try {
+            records = await this.events.read(experienceId);
+        }
+        catch (e) {
+            // The feed INHERITS the lineage's `confirmErased` hook (it classifies through `lineage.block`):
+            // a confirmed erasure is `line-erased`, any other unreadable line is `line-unreadable` (or
+            // `artifact-unsealed`); both fail closed. Anything else propagates unchanged.
+            const b = await this.lineage.block(experienceId, e);
+            if (b === undefined)
+                throw e;
+            return err(b instanceof ui_lineage_1.LineErasedError ? "line-erased" : b.reason, b instanceof ui_lineage_1.LineErasedError
+                ? `lineage "${experienceId}" is erased: its key is destroyed (confirmed)`
+                : `lineage "${experienceId}" is unreadable: its key is unavailable on this node or its ciphertext does not open; not confirmed erased`);
+        }
+        const fold = (0, ui_lineage_1.foldLineage)(experienceId, records);
+        if (!fold.ok)
+            return { ok: false, finding: fold.finding };
+        const out = [];
+        let promoted = null;
+        let more = false;
+        for (const rec of records) {
+            // The fold validated every record, so these payload reads are of checked shapes.
+            const p = rec.payload;
+            const version = fold.state.versions.get(p.versionHash);
+            let kind;
+            let base;
+            if (rec.type === ui_lineage_1.EXPERIENCE_PROMOTED) {
+                kind = "promoted";
+                base = promoted === null ? null : { experienceId, versionHash: promoted };
+                promoted = p.versionHash;
+            }
+            else {
+                kind =
+                    rec.type === ui_lineage_1.EXPERIENCE_REVERTED
+                        ? "reverted"
+                        : rec.type === ui_lineage_1.EXPERIENCE_BRANCHED
+                            ? "branched"
+                            : "composed";
+                const parent = version?.parents[0];
+                base =
+                    kind === "branched" && version?.from !== undefined
+                        ? { experienceId: version.from.experienceId, versionHash: version.from.versionHash }
+                        : parent === undefined
+                            ? null
+                            : { experienceId, versionHash: parent };
+            }
+            if (rec.sequence <= after)
+                continue;
+            if (out.length === limit) {
+                more = true;
+                break;
+            }
+            out.push({
+                id: `${experienceId}#${rec.sequence}`,
+                experienceId,
+                sequence: rec.sequence,
+                at: rec.at,
+                kind,
+                versionHash: p.versionHash,
+                base,
+            });
+        }
+        return {
+            ok: true,
+            events: out,
+            cursor: out.at(-1)?.sequence ?? after,
+            more,
+            tip: fold.state.sequence,
+        };
+    }
+    subscribe(experienceId, handler, opts = {}) {
+        let cursor = asCursor(opts.after) ?? 0;
+        let stopped = false;
+        let running = false;
+        let again = false;
+        let timer;
+        let failures = 0; // consecutive failed passes, for the backoff
+        let poisonSeq = 0;
+        let poisonAttempts = 0;
+        const baseMs = Math.max(1, finite(opts.retry?.baseMs, 250));
+        const maxMs = Math.max(baseMs, finite(opts.retry?.maxMs, 30_000));
+        const report = (e) => {
+            try {
+                opts.onError?.(e);
+            }
+            catch {
+                // a reporting hook must not break delivery
+            }
+        };
+        // The cursor is behind the tip whenever a pass failed: retry on a timer, since a quiet line
+        // raises no signal. Delay = min(max, base * 2^n), jittered into [50%, 100%].
+        const arm = () => {
+            if (stopped || timer !== undefined)
+                return;
+            const delay = Math.min(maxMs, baseMs * 2 ** Math.min(failures, 30));
+            failures += 1;
+            timer = setTimeout(() => {
+                timer = undefined;
+                void pump();
+            }, Math.max(1, Math.round(delay * (0.5 + Math.random() / 2))));
+            timer.unref?.();
+        };
+        const skipPoison = async (e) => {
+            if (poisonSeq !== e.sequence) {
+                poisonSeq = e.sequence;
+                poisonAttempts = 0;
+            }
+            poisonAttempts += 1;
+            if (opts.onPoison === undefined)
+                return false;
+            try {
+                return (await opts.onPoison(e, poisonAttempts)) === true;
+            }
+            catch (thrown) {
+                report(thrown);
+                return false;
+            }
+        };
+        const pump = async () => {
+            if (running) {
+                again = true;
+                return;
+            }
+            running = true;
+            let failed = false;
+            try {
+                do {
+                    again = false;
+                    for (;;) {
+                        if (stopped)
+                            return;
+                        const r = await this.read(experienceId, { after: cursor });
+                        if (!r.ok) {
+                            report(r.finding);
+                            // A CONFIRMED erasure is terminal: report once and stop (no retry, no further wakes).
+                            // An unconfirmed `line-unreadable` keeps retrying: the key may come back to this node.
+                            if (r.finding.code === "line-erased") {
+                                terminate();
+                                return;
+                            }
+                            failed = true;
+                            return;
+                        }
+                        for (const e of r.events) {
+                            if (stopped)
+                                return;
+                            try {
+                                await handler(e);
+                            }
+                            catch (thrown) {
+                                report(thrown);
+                                if (await skipPoison(e)) {
+                                    cursor = e.sequence;
+                                    continue;
+                                }
+                                failed = true;
+                                return; // not advanced: redelivered by the retry timer or the next wake
+                            }
+                            cursor = e.sequence;
+                            failures = 0;
+                        }
+                        if (!r.more)
+                            break;
+                    }
+                } while (again && !stopped);
+            }
+            catch (thrown) {
+                report(thrown);
+                failed = true;
+            }
+            finally {
+                running = false;
+                if (failed)
+                    arm();
+                else
+                    failures = 0;
+            }
+        };
+        let unwatch;
+        const terminate = () => {
+            stopped = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+            unwatch?.();
+            unwatch = undefined;
+        };
+        unwatch = this.signal.watch(experienceId, () => void pump());
+        void pump();
+        return terminate;
+    }
+    async describe(event, opts = {}) {
+        // The caller's event is a CLAIM about the log, not the log: its experience and sequence are
+        // used only to find the recorded event, and `kind`/`base`/`versionHash` come from the fold.
+        // An event that does not match the record at its position is refused (a forged `base` would
+        // otherwise describe a different line's nodes: a confused deputy).
+        const seq = event?.sequence;
+        if (typeof event?.experienceId !== "string" || !Number.isSafeInteger(seq) || seq < 1)
+            return err("event-invalid", "the event has no readable line and sequence");
+        const at = await this.read(event.experienceId, { after: seq - 1, limit: 1 });
+        if (!at.ok)
+            return { ok: false, finding: at.finding };
+        const truth = at.events[0];
+        if (truth === undefined || truth.sequence !== seq)
+            return err("event-unknown", "the event is not in the line's log");
+        if (truth.versionHash !== event.versionHash ||
+            truth.kind !== event.kind ||
+            JSON.stringify(truth.base) !== JSON.stringify(event.base ?? null))
+            return err("event-mismatch", "the event does not match the log's record at its sequence");
+        const versions = await this.lineage.versions(truth.experienceId);
+        if (!versions.ok)
+            return refusal(versions.refusal);
+        const record = versions.value.find((v) => v.versionHash === truth.versionHash);
+        if (record === undefined)
+            return err("version-unknown", `"${truth.versionHash}" is not a version of the line`);
+        const next = await this.lineage.get(truth.experienceId, truth.versionHash);
+        if (!next.ok)
+            return refusal(next.refusal);
+        let prev = null;
+        if (truth.base !== null) {
+            const p = await this.lineage.get(truth.base.experienceId, truth.base.versionHash);
+            if (!p.ok)
+                return refusal(p.refusal);
+            prev = p.value;
+        }
+        // The ops and the summary belong to ONE version. They describe this event when it IS that
+        // version's creation, or when a promotion spans exactly that one step.
+        const own = truth.kind !== "promoted" || record.parents.includes(truth.base?.versionHash ?? "");
+        // The bound policy first: a per-call value can only ADD to it (a table is joined strictest-wins,
+        // `"deny"` sticks, a bound projection catalogue is not replaced), so `{}` or an explicit
+        // `undefined` per call cannot lower what the host bound at construction.
+        const policy = (0, ui_core_1.mergeReadPolicy)(this.policy, opts);
+        return {
+            ok: true,
+            description: (0, ui_core_1.describeChange)(prev, next.value, {
+                ...opts,
+                // AFTER `...opts`: the joined policy wins over every per-call spelling of these fields.
+                ...(policy.projections !== undefined && { projections: policy.projections }),
+                ...(policy.hydrationProjectionId !== undefined && {
+                    hydrationProjectionId: policy.hydrationProjectionId,
+                }),
+                ...(policy.declaredToolClasses !== undefined && {
+                    declaredToolClasses: policy.declaredToolClasses,
+                }),
+                ...(policy.undeclared !== undefined && { undeclared: policy.undeclared }),
+                ...(own && record.ops.length > 0 && { ops: record.ops }),
+                ...(own && record.summary !== undefined && { summary: record.summary }),
+                ...(own && record.summaryClass !== undefined && { summaryClass: record.summaryClass }),
+            }),
+        };
+    }
+}
+exports.LineageChangeFeed = LineageChangeFeed;
+const finite = (v, dflt) => typeof v === "number" && Number.isFinite(v) ? v : dflt;
+function refusal(r) {
+    return {
+        ok: false,
+        finding: r.finding ?? {
+            code: r.kind,
+            severity: "error",
+            message: `the lineage refused: ${r.kind}`,
+        },
+    };
+}
+//# sourceMappingURL=feed.js.map

package/dist/feed.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { LineageChangeFeed, DEFAULT_PAGE, MAX_PAGE } from "./feed";
+export type { ChangeEvent, ChangeEventKind, ChangeFeed, DescribeResult, LineageChangeFeedOptions, ReadResult, RetryOptions, SubscribeOptions, } from "./feed";
+export { InMemoryUnreadStore, markRead, unreadChanges } from "./cursor";
+export type { UnreadResult, UnreadStore } from "./cursor";
+export { eventStoreHeadSignal, pollingHeadSignal } from "./signal";
+export type { PollingOptions, PushOptions, SignalOptions } from "./signal";
+export { checkChangeFeedConformance, checkUnreadStoreConformance } from "./conformance";
+export type { FeedHarness } from "./conformance";
+export { summaryAsTainted } from "./untrusted";
+//# 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":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACnE,YAAY,EACV,WAAW,EACX,eAAe,EACf,UAAU,EACV,cAAc,EACd,wBAAwB,EACxB,UAAU,EACV,YAAY,EACZ,gBAAgB,GACjB,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACxE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACnE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC3E,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AACxF,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summaryAsTainted = exports.checkUnreadStoreConformance = exports.checkChangeFeedConformance = exports.pollingHeadSignal = exports.eventStoreHeadSignal = exports.unreadChanges = exports.markRead = exports.InMemoryUnreadStore = exports.MAX_PAGE = exports.DEFAULT_PAGE = exports.LineageChangeFeed = void 0;
+var feed_1 = require("./feed");
+Object.defineProperty(exports, "LineageChangeFeed", { enumerable: true, get: function () { return feed_1.LineageChangeFeed; } });
+Object.defineProperty(exports, "DEFAULT_PAGE", { enumerable: true, get: function () { return feed_1.DEFAULT_PAGE; } });
+Object.defineProperty(exports, "MAX_PAGE", { enumerable: true, get: function () { return feed_1.MAX_PAGE; } });
+var cursor_1 = require("./cursor");
+Object.defineProperty(exports, "InMemoryUnreadStore", { enumerable: true, get: function () { return cursor_1.InMemoryUnreadStore; } });
+Object.defineProperty(exports, "markRead", { enumerable: true, get: function () { return cursor_1.markRead; } });
+Object.defineProperty(exports, "unreadChanges", { enumerable: true, get: function () { return cursor_1.unreadChanges; } });
+var signal_1 = require("./signal");
+Object.defineProperty(exports, "eventStoreHeadSignal", { enumerable: true, get: function () { return signal_1.eventStoreHeadSignal; } });
+Object.defineProperty(exports, "pollingHeadSignal", { enumerable: true, get: function () { return signal_1.pollingHeadSignal; } });
+var conformance_1 = require("./conformance");
+Object.defineProperty(exports, "checkChangeFeedConformance", { enumerable: true, get: function () { return conformance_1.checkChangeFeedConformance; } });
+Object.defineProperty(exports, "checkUnreadStoreConformance", { enumerable: true, get: function () { return conformance_1.checkUnreadStoreConformance; } });
+var untrusted_1 = require("./untrusted");
+Object.defineProperty(exports, "summaryAsTainted", { enumerable: true, get: function () { return untrusted_1.summaryAsTainted; } });
+//# 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,+BAAmE;AAA1D,yGAAA,iBAAiB,OAAA;AAAE,oGAAA,YAAY,OAAA;AAAE,gGAAA,QAAQ,OAAA;AAWlD,mCAAwE;AAA/D,6GAAA,mBAAmB,OAAA;AAAE,kGAAA,QAAQ,OAAA;AAAE,uGAAA,aAAa,OAAA;AAErD,mCAAmE;AAA1D,8GAAA,oBAAoB,OAAA;AAAE,2GAAA,iBAAiB,OAAA;AAEhD,6CAAwF;AAA/E,yHAAA,0BAA0B,OAAA;AAAE,0HAAA,2BAA2B,OAAA;AAEhE,yCAA+C;AAAtC,6GAAA,gBAAgB,OAAA"}

package/dist/signal.d.ts

@@ -0,0 +1,33 @@
+import type { EventStore } from "@loomwork/event-runtime";
+import type { HeadSignal } from "@loomwork/ui-core";
+import { type LineageStore } from "@loomwork/ui-lineage";
+export interface SignalOptions {
+    /** A read or fold that failed. The watcher keeps going: the next trigger tries again. */
+    readonly onError?: (err: unknown) => void;
+    /**
+     * Has this line's erasure been confirmed? (The same host hook as `LineageOptions.confirmErased`;
+     * a signal is built over a store, not a lineage, so it takes its own.) A CONFIRMED erasure reports
+     * one `LineErasedError` and the watcher goes terminal (no more checks). An unconfirmed unreadable
+     * line reports `LineUnreadableError` on every check and keeps retrying.
+     */
+    readonly confirmErased?: (experienceId: string) => Promise<boolean>;
+}
+export interface PollingOptions extends SignalOptions {
+    /** Milliseconds between checks (default 2000; floor 10). */
+    readonly intervalMs?: number;
+    /** Injectable timer: run `fn` every `ms`, return a canceller. Default `setInterval` (unref'd). */
+    readonly schedule?: (fn: () => void, ms: number) => () => void;
+}
+export declare function pollingHeadSignal(store: LineageStore, opts?: PollingOptions): HeadSignal;
+export interface PushOptions extends SignalOptions {
+    /**
+     * A safety-net poll (ms; floor 10) beside the push subscription: a push can be missed (the
+     * subscription failed to attach, a notify was dropped), and the fallback bounds that to one
+     * interval. Absent = push only.
+     */
+    readonly fallbackIntervalMs?: number;
+    /** Injectable timer for the fallback; default `setInterval` (unref'd). */
+    readonly schedule?: (fn: () => void, ms: number) => () => void;
+}
+export declare function eventStoreHeadSignal(events: EventStore, store: LineageStore, opts?: PushOptions): HeadSignal;
+//# sourceMappingURL=signal.d.ts.map

package/dist/signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../src/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAEL,KAAK,YAAY,EAGlB,MAAM,sBAAsB,CAAC;AAmB9B,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACrE;AAwED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,IAAI,CAAC;CAChE;AAQD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,GAAE,cAAmB,GAAG,UAAU,CAsB5F;AAED,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,IAAI,CAAC;CAChE;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,YAAY,EACnB,IAAI,GAAE,WAAgB,GACrB,UAAU,CAuCZ"}

package/dist/signal.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollingHeadSignal = pollingHeadSignal;
+exports.eventStoreHeadSignal = eventStoreHeadSignal;
+const ui_lineage_1 = require("@loomwork/ui-lineage");
+const ui_lineage_2 = require("@loomwork/ui-lineage");
+/** One watcher's check: at most one read in flight, reports each new tip once. */
+function checker(store, experienceId, onChange, onError, confirmErased, onTerminal) {
+    let seen = 0;
+    let stopped = false;
+    let busy = false;
+    let rerun = false;
+    const fail = (e) => {
+        try {
+            onError?.(e);
+        }
+        catch {
+            // never break the signal
+        }
+    };
+    const check = async () => {
+        if (stopped)
+            return;
+        if (busy) {
+            rerun = true;
+            return;
+        }
+        busy = true;
+        try {
+            do {
+                rerun = false;
+                const records = await store.read(experienceId);
+                if (stopped || records.length <= seen)
+                    continue;
+                seen = records.length;
+                const fold = (0, ui_lineage_1.foldLineage)(experienceId, records);
+                if (!fold.ok) {
+                    fail(fold.finding);
+                    continue;
+                }
+                try {
+                    onChange({
+                        experienceId,
+                        sequence: fold.state.sequence,
+                        head: fold.state.head,
+                        promoted: fold.state.promoted,
+                    });
+                }
+                catch (e) {
+                    fail(e);
+                }
+            } while (rerun && !stopped);
+        }
+        catch (e) {
+            // an unreadable line reports a typed error; anything else is reported unchanged
+            const b = await (0, ui_lineage_1.classifyLineFailure)(experienceId, e, confirmErased);
+            fail(b ?? e);
+            if (b instanceof ui_lineage_1.LineErasedError) {
+                // confirmed erased: terminal, reported once
+                stopped = true;
+                onTerminal();
+            }
+        }
+        finally {
+            busy = false;
+        }
+    };
+    return {
+        check,
+        stop: () => {
+            stopped = true;
+        },
+    };
+}
+const defaultSchedule = (fn, ms) => {
+    const t = setInterval(fn, ms);
+    t.unref?.();
+    return () => clearInterval(t);
+};
+function pollingHeadSignal(store, opts = {}) {
+    const intervalMs = Math.max(10, Number.isFinite(opts.intervalMs) ? opts.intervalMs : 2000);
+    const schedule = opts.schedule ?? defaultSchedule;
+    return {
+        watch(experienceId, onChange) {
+            let cancel;
+            let ended = false;
+            const c = checker(store, experienceId, onChange, opts.onError, opts.confirmErased, () => {
+                ended = true;
+                cancel?.();
+            });
+            void c.check();
+            if (!ended)
+                cancel = schedule(() => void c.check(), intervalMs);
+            return () => {
+                c.stop();
+                cancel?.();
+            };
+        },
+    };
+}
+function eventStoreHeadSignal(events, store, opts = {}) {
+    const fallback = Number.isFinite(opts.fallbackIntervalMs)
+        ? Math.max(10, opts.fallbackIntervalMs)
+        : undefined;
+    const schedule = opts.schedule ?? defaultSchedule;
+    const report = (e) => {
+        try {
+            opts.onError?.(e);
+        }
+        catch {
+            // never break the signal
+        }
+    };
+    return {
+        watch(experienceId, onChange) {
+            let cancel;
+            let off;
+            let stopped = false;
+            const c = checker(store, experienceId, onChange, opts.onError, opts.confirmErased, () => {
+                stopped = true;
+                cancel?.();
+                off?.();
+            });
+            events
+                .subscribe(`${ui_lineage_2.LINEAGE_STREAM_PREFIX}${experienceId}`, () => void c.check())
+                .then((u) => {
+                if (stopped)
+                    u();
+                else
+                    off = u;
+            })
+                .catch(report);
+            void c.check();
+            if (!stopped && fallback !== undefined)
+                cancel = schedule(() => void c.check(), fallback);
+            return () => {
+                stopped = true;
+                c.stop();
+                cancel?.();
+                off?.();
+            };
+        },
+    };
+}
+//# sourceMappingURL=signal.js.map

package/dist/signal.js.map

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

package/dist/untrusted.d.ts

@@ -0,0 +1,5 @@
+import { type TaintedValue } from "@loomwork/classify";
+import type { UntrustedText } from "@loomwork/ui-core";
+/** The summary as an ADR 0085 tainted value, origin `loom-ui:change-summary`. */
+export declare function summaryAsTainted(summary: UntrustedText): TaintedValue<string>;
+//# sourceMappingURL=untrusted.d.ts.map

package/dist/untrusted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrusted.d.ts","sourceRoot":"","sources":["../src/untrusted.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAW,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAWvD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,YAAY,CAAC,MAAM,CAAC,CAE7E"}

package/dist/untrusted.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summaryAsTainted = summaryAsTainted;
+const classify_1 = require("@loomwork/classify");
+// ── The summary as loom's untrusted value ─────────────────────────────────────
+// A change summary is model text. `UntrustedText` marks it for DISPLAY; when a host feeds it to
+// another model (a digest, a notification writer) it must cross as loom's ADR 0085 taint
+// (`@loomwork/classify` `TaintedValue`), which `@loomwork/llm`'s `guardRequest` refuses in any instruction
+// position and fences in a data position. This is a server-side helper: the taint package is a
+// loom kernel-side dependency and must not enter a client bundle.
+//
+// NEVER put a summary in a prompt's instruction (system) position, tainted or not.
+/** The summary as an ADR 0085 tainted value, origin `loom-ui:change-summary`. */
+function summaryAsTainted(summary) {
+    return (0, classify_1.tainted)(summary.text, "loom-ui:change-summary");
+}
+//# sourceMappingURL=untrusted.js.map

package/dist/untrusted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrusted.js","sourceRoot":"","sources":["../src/untrusted.ts"],"names":[],"mappings":";;AAaA,4CAEC;AAfD,iDAAgE;AAGhE,iFAAiF;AACjF,gGAAgG;AAChG,yFAAyF;AACzF,2GAA2G;AAC3G,+FAA+F;AAC/F,kEAAkE;AAClE,EAAE;AACF,mFAAmF;AAEnF,iFAAiF;AACjF,SAAgB,gBAAgB,CAAC,OAAsB;IACrD,OAAO,IAAA,kBAAO,EAAC,OAAO,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;AACzD,CAAC"}