@loomwork/ui-changes 0.0.0-stage → 0.1.0

package/dist/esm/feed.js

@@ -0,0 +1,301 @@
+import { describeChange, mergeReadPolicy, } from "@loomwork/ui-core";
+import { EXPERIENCE_BRANCHED, EXPERIENCE_PROMOTED, EXPERIENCE_REVERTED, LineErasedError, foldLineage, } from "@loomwork/ui-lineage";
+export const DEFAULT_PAGE = 100;
+export const 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.
+ */
+export class LineageChangeFeed {
+    lineage;
+    events;
+    signal;
+    policy;
+    constructor(opts) {
+        this.policy = 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
+            ? DEFAULT_PAGE
+            : Number.isSafeInteger(opts.limit) && opts.limit >= 1
+                ? Math.min(opts.limit, 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 LineErasedError ? "line-erased" : b.reason, b instanceof 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 = 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 === EXPERIENCE_PROMOTED) {
+                kind = "promoted";
+                base = promoted === null ? null : { experienceId, versionHash: promoted };
+                promoted = p.versionHash;
+            }
+            else {
+                kind =
+                    rec.type === EXPERIENCE_REVERTED
+                        ? "reverted"
+                        : rec.type === 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 = mergeReadPolicy(this.policy, opts);
+        return {
+            ok: true,
+            description: 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 }),
+            }),
+        };
+    }
+}
+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/esm/feed.js.map

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

package/dist/esm/index.js

@@ -0,0 +1,6 @@
+export { LineageChangeFeed, DEFAULT_PAGE, MAX_PAGE } from "./feed";
+export { InMemoryUnreadStore, markRead, unreadChanges } from "./cursor";
+export { eventStoreHeadSignal, pollingHeadSignal } from "./signal";
+export { checkChangeFeedConformance, checkUnreadStoreConformance } from "./conformance";
+export { summaryAsTainted } from "./untrusted";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAWnE,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAExE,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAEnE,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAExF,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/esm/signal.js

@@ -0,0 +1,141 @@
+import { LineErasedError, classifyLineFailure, foldLineage, } from "@loomwork/ui-lineage";
+import { LINEAGE_STREAM_PREFIX } from "@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 = 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 classifyLineFailure(experienceId, e, confirmErased);
+            fail(b ?? e);
+            if (b instanceof 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);
+};
+export 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?.();
+            };
+        },
+    };
+}
+export 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(`${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/esm/signal.js.map

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

package/dist/esm/untrusted.js

@@ -0,0 +1,14 @@
+import { tainted } from "@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`. */
+export function summaryAsTainted(summary) {
+    return tainted(summary.text, "loom-ui:change-summary");
+}
+//# sourceMappingURL=untrusted.js.map

package/dist/esm/untrusted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrusted.js","sourceRoot":"","sources":["../../src/untrusted.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGhE,iFAAiF;AACjF,gGAAgG;AAChG,yFAAyF;AACzF,2GAA2G;AAC3G,+FAA+F;AAC/F,kEAAkE;AAClE,EAAE;AACF,mFAAmF;AAEnF,iFAAiF;AACjF,MAAM,UAAU,gBAAgB,CAAC,OAAsB;IACrD,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;AACzD,CAAC"}

package/dist/feed.d.ts

@@ -0,0 +1,125 @@
+import { type ChangeDescription, type DeclaredToolClasses, type DescribeOptions, type Finding, type HeadSignal, type ProjectionCatalog, type ReadPolicy, type UndeclaredToolPolicy } from "@loomwork/ui-core";
+import { type Lineage, type LineageStore } from "@loomwork/ui-lineage";
+export type ChangeEventKind = "composed" | "reverted" | "branched" | "promoted";
+export interface ChangeEvent {
+    /** Stable, unique per log position: `<experienceId>#<sequence>`. The idempotency key. */
+    readonly id: string;
+    readonly experienceId: string;
+    /** 1-based position in the line's log; also the cursor value that means "handled through here". */
+    readonly sequence: number;
+    readonly at: string;
+    readonly kind: ChangeEventKind;
+    /** The version this event is about (the new head, or the version now shown). */
+    readonly versionHash: string;
+    /** What it replaced: the parent (composed/reverted), the forked version (branched), the version shown before (promoted); null = nothing. */
+    readonly base: {
+        readonly experienceId: string;
+        readonly versionHash: string;
+    } | null;
+}
+export type ReadResult = {
+    readonly ok: true;
+    readonly events: readonly ChangeEvent[];
+    /** The sequence of the last event returned, or `after` when none was: pass it back as `after`. */
+    readonly cursor: number;
+    /** More events remain past `cursor` (the page was full). */
+    readonly more: boolean;
+    /** The log's tip at read time (0 = empty). */
+    readonly tip: number;
+} | {
+    readonly ok: false;
+    readonly finding: Finding;
+};
+export type DescribeResult = {
+    readonly ok: true;
+    readonly description: ChangeDescription;
+} | {
+    readonly ok: false;
+    readonly finding: Finding;
+};
+export interface RetryOptions {
+    /** First retry delay in ms (default 250). Doubles per consecutive failure. */
+    readonly baseMs?: number;
+    /** Delay ceiling in ms (default 30000). */
+    readonly maxMs?: number;
+}
+export interface SubscribeOptions {
+    /** Deliver events after this sequence (default 0 = from the start). */
+    readonly after?: number;
+    /** A failed read, or a handler that threw. Never throws itself. */
+    readonly onError?: (err: unknown) => void;
+    /** Backoff for re-trying a failed delivery or read with no new append. See `subscribe`. */
+    readonly retry?: RetryOptions;
+    /**
+     * Called after each failed delivery of the SAME event, with the count of consecutive failures.
+     * Return `true` to SKIP the event (the cursor moves past it, it is never redelivered to this
+     * subscription); anything else (or a throw) keeps retrying. Absent = retry forever with capped
+     * backoff: a poison event then stalls this subscription (and only it); a host that wants out
+     * resubscribes with `after: <poison sequence>`.
+     */
+    readonly onPoison?: (event: ChangeEvent, attempts: number) => boolean | Promise<boolean>;
+}
+export interface ChangeFeed {
+    read(experienceId: string, opts?: {
+        after?: number;
+        limit?: number;
+    }): Promise<ReadResult>;
+    /**
+     * Catch up from `after`, then follow the line, until the returned function is called. Events
+     * arrive in sequence order, one at a time (the next waits for the handler's promise). A handler
+     * that throws stops this pass at that event WITHOUT advancing: it is delivered again (at-least-
+     * once), and `onError` hears of it. The retry does NOT wait for a new append: while the cursor is
+     * behind the tip (a handler threw, or a read failed) a bounded exponential backoff timer
+     * (jittered, `unref`'d, cleared on unsubscribe) re-runs the pass, so a quiet line is never stuck.
+     * A permanently failing event is a poison event: see `SubscribeOptions.onPoison`. Resubscribing
+     * from an older cursor redelivers the same ids.
+     */
+    subscribe(experienceId: string, handler: (event: ChangeEvent) => void | Promise<void>, opts?: SubscribeOptions): () => void;
+    /** What `event` changed, for one viewer. See `describeChange`: restricted content is never named. */
+    describe(event: ChangeEvent, opts?: Omit<DescribeOptions, "ops" | "summary" | "summaryClass">): Promise<DescribeResult>;
+}
+export declare const DEFAULT_PAGE = 100;
+export declare const MAX_PAGE = 1000;
+export interface LineageChangeFeedOptions {
+    readonly lineage: Lineage;
+    /** The same `LineageStore` the `Lineage` writes to. */
+    readonly events: LineageStore;
+    /** What wakes a subscription; see `pollingHeadSignal` / `eventStoreHeadSignal`. */
+    readonly signal: HeadSignal;
+    /**
+     * The projections the host offers (the same `ProjectionCatalog` `compile` takes). ABSENT = none:
+     * every projection-bound node is hidden from every viewer in `describe`, and a change to one is
+     * a `restricted-changed`. An id the catalogue lacks, or a version pin that drifted, hides too.
+     */
+    readonly projections?: ProjectionCatalog;
+    /** The host's hydration projection id (reserved; see `DescribeOptions`). */
+    readonly hydrationProjectionId?: string;
+    /** The host's declared class per tool: a read-time floor (core `DeclaredToolClasses`). */
+    readonly declaredToolClasses?: DeclaredToolClasses;
+    /** What a tool the declared table does not list reads as (`"allow"` default, or `"deny"`). */
+    readonly undeclared?: UndeclaredToolPolicy;
+    /**
+     * The read policy bound ONCE (the same shape every reader takes). Joined, raise-only, with the
+     * `lineage`'s own bound policy, the individual options above and any per-call `describe` options.
+     */
+    readonly readPolicy?: ReadPolicy;
+}
+/**
+ * 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.
+ */
+export declare class LineageChangeFeed implements ChangeFeed {
+    private readonly lineage;
+    private readonly events;
+    private readonly signal;
+    private readonly policy;
+    constructor(opts: LineageChangeFeedOptions);
+    read(experienceId: string, opts?: {
+        after?: number;
+        limit?: number;
+    }): Promise<ReadResult>;
+    subscribe(experienceId: string, handler: (event: ChangeEvent) => void | Promise<void>, opts?: SubscribeOptions): () => void;
+    describe(event: ChangeEvent, opts?: Omit<DescribeOptions, "ops" | "summary" | "summaryClass">): Promise<DescribeResult>;
+}
+//# sourceMappingURL=feed.d.ts.map

package/dist/feed.d.ts.map

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