@loomwork/ui-lineage 0.0.0-stage → 0.1.1

package/dist/seen.js

@@ -0,0 +1,739 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seenStoreOptions = exports.SeenLog = exports.seenStreamKey = exports.UNREADABLE_EXAMPLES = exports.DEFAULT_MAX_SKEW_MS = exports.ViewRecordPayload = exports.MAX_SEEN_READ = exports.DEFAULT_MAX_SEEN_VIEWS = exports.SEEN_WORKFLOW_ID = exports.SEEN_STREAM_PREFIX = exports.VIEWER_ERASED = exports.VIEWS_RETAINED = exports.VIEW_RECORDED = void 0;
+exports.sizeClass = sizeClass;
+const plugin_content_1 = require("@loomwork/plugin-content");
+const ui_core_1 = require("@loomwork/ui-core");
+const zod_1 = require("zod");
+const seenCrypto_1 = require("./seenCrypto");
+const store_1 = require("./store");
+// ── The record of what a viewer SAW (U12) ─────────────────────────────────────
+// WHERE IT LIVES, and why not the two obvious places:
+//
+//  * NOT the lineage stream. A lineage line is the SHARED, append-only history of an experience: one
+//    compare-and-set tip per line, folded by every reader (the change feed fans it out to every
+//    viewer), and its fold is total and structural. A view is per-viewer, high-rate, and carries
+//    DATA. Appending views there would make every open of a surface contend with every writer of a
+//    version for the same tip, put one viewer's classified values in a log every reader of the line
+//    folds, and let a view record change what `verify` of the line has to explain.
+//  * NOT the hydration store. That is a latest-value cache for the surface being drawn: it holds
+//    the CURRENT value of a handle, evicts, is projected to a client, and keeps no history, so it
+//    cannot say what a viewer saw last Tuesday.
+//
+// So: a SEPARATE, per-(experience, viewer) log in a reserved namespace of the same `LineageStore`
+// seam (one stream per viewer: no cross-viewer contention, isolation by key) whose events are
+// MANIFESTS. A manifest names the version viewed and, per data source, a class stamp, a delivery
+// state and — for a value that fit the caps — a SEALED content reference. The VALUE BYTES live in the
+// ContentStore under their plain content address (identical values dedupe across viewers and with the
+// lineage). Nothing here is part of any artifact or content address.
+//
+// ERASURE (crypto-shredding). A plain SHA-256 in an append-only log confirms any low-entropy value
+// ("did this viewer see `42`?" is one hash away), and a log has no delete. So each entry's ref is
+// stored ENCRYPTED (AES-256-GCM) under a per-(experience, viewer) data key held in a host-supplied
+// `SeenKeyStore`, and the manifest digest is a keyed HMAC, not a hash. Erasing a viewer destroys the
+// key: nothing left in the stream is decryptable and no readable address remains. The ciphertext is
+// bound to (experience, viewer, record sequence, entry index) as associated data, so a ref cannot be
+// transplanted between records or viewers. What the sealed payload holds is `{ref, bytes}`, padded
+// to a constant length: the value's SIZE is inside the seal too, so neither a field nor the
+// ciphertext length distinguishes `true` from `false` from a short enum.
+//
+// WHAT AN ERASED STREAM STILL REVEALS (precisely): that the viewer opened the experience; the
+// sources each view named (handles / projection ids and paths); node ids; class stamps; delivery
+// statuses; the version hash; record times; and, for an `oversize` / `over-budget` entry only, a
+// power-of-two SIZE CLASS (never the exact byte count), because there the size class IS the recorded fact. It
+// reveals NO value, no content address, and no size of a value that was recorded as `seen`.
+//
+// VALUE BLOBS are reclaimed by a MARK-AND-SWEEP collector (`collectSeenGarbage`, seenGc.ts), never a
+// refcount: there is no transaction across the event log and the ContentStore, so a counter drifts,
+// and a crash between "append" and "increment" would delete a live value. Roots are re-derived from
+// the logs on every pass.
+//
+// RETENTION. A viewer's log is bounded by roll-off, not refusal: new views ALWAYS record, and the
+// oldest fall out of a `{ maxViews, maxAgeMs }` window. The log is append-only, so roll-off is a
+// watermark: every view record carries the `floor` in force when written, and a `VIEWS_RETAINED`
+// record raises it; records at or below the floor are not read and not marked by the collector.
+// The tip, floor and last digest come from the LAST record alone, and a read costs the size of the
+// window (`readAfter(floor)`), not the age of the log.
+//
+// Reads are viewer-safe: the entries are redacted against the recorded version's artifact with
+// core's `redactSeen` BEFORE any blob is fetched (a viewer is never even handed a restricted ref),
+// and a stamp that is missing or unknown is withheld.
+exports.VIEW_RECORDED = "VIEW_RECORDED";
+/** A retention watermark: every record at or below `floor` has rolled off. */
+exports.VIEWS_RETAINED = "VIEWS_RETAINED";
+/** The viewer was erased (written AFTER the key is destroyed; a rerun completes it). */
+exports.VIEWER_ERASED = "VIEWER_ERASED";
+/** The reserved-stream namespace a viewer's record lives under (distinct from the lineage's). */
+exports.SEEN_STREAM_PREFIX = "__loom_ui_seen__:";
+exports.SEEN_WORKFLOW_ID = "loom-ui.seen";
+/** Default most views a viewer's log keeps readable; older ones roll off (never a refusal). */
+exports.DEFAULT_MAX_SEEN_VIEWS = 10_000;
+/** Most records one read returns. */
+exports.MAX_SEEN_READ = 500;
+const MAX_APPEND_RETRIES = 16;
+const MAX_ID = 256;
+const MAX_VIEWS_CAP = 1_000_000;
+const SourceSchema = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z.object({ kind: zod_1.z.literal("handle"), handle: zod_1.z.string().min(1).max(512) }),
+    zod_1.z.object({
+        kind: zod_1.z.literal("projection"),
+        id: zod_1.z.string().min(1).max(512),
+        path: zod_1.z.string().min(1).max(1024),
+        version: zod_1.z.string().min(1).max(512),
+    }),
+]);
+// `class` is left a plain string here: an unknown stamp must reach `redactSeen` and be WITHHELD there
+// (the record is untrusted input), not make the whole record unparseable.
+const EntrySchema = zod_1.z.object({
+    source: SourceSchema,
+    nodeIds: zod_1.z.array(zod_1.z.string().min(1).max(512)).min(1).max(ui_core_1.MAX_SEEN_NODE_IDS),
+    class: zod_1.z.string().max(32),
+    state: zod_1.z.enum(["seen", "absent", "oversize", "over-budget", "unreadable"]),
+    status: zod_1.z.string().max(64).optional(),
+    /** Only for `oversize` / `over-budget` (where the size is the recorded fact). A `seen` entry's size lives inside `sealed`. */
+    bytes: zod_1.z.number().int().nonnegative().optional(),
+    /** `{ref, bytes}`, constant-length padded and AEAD-sealed under the viewer's data key (see the header). Never a plain address. */
+    sealed: zod_1.z.string().min(1).max(1024).optional(),
+});
+exports.ViewRecordPayload = zod_1.z.object({
+    experienceId: zod_1.z.string().min(1).max(MAX_ID),
+    versionHash: zod_1.z.string().min(1).max(256),
+    viewerId: zod_1.z.string().min(1).max(MAX_ID),
+    /** The clearance the viewer held when shown the surface (informational: reads use the READER's). */
+    clearance: zod_1.z.string().max(32).optional(),
+    entries: zod_1.z.array(EntrySchema).max(ui_core_1.MAX_SEEN_SOURCES),
+    omitted: zod_1.z.number().int().nonnegative(),
+    restricted: zod_1.z.boolean(),
+    /** Keyed digest (HMAC under the viewer's key) of the manifest's meaning: an identical consecutive view is not re-recorded. */
+    digest: zod_1.z.string().min(1).max(128),
+    /** The retention floor in force when this was written (see the header). */
+    floor: zod_1.z.number().int().nonnegative().optional(),
+});
+/** The smallest power of two >= `n` (0 stays 0): the only size an `oversize` / `over-budget` entry stores. */
+function sizeClass(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    return 2 ** Math.ceil(Math.log2(n));
+}
+/** Default tolerated clock skew between writers (5 minutes). */
+exports.DEFAULT_MAX_SKEW_MS = 300_000;
+/** Records read from the tail to find the floor in force (a malformed tip carries the last good one). */
+const FLOOR_SCAN = 8;
+/** Cap on the offenders named per kind in {@link SeenUnreadable.examples}. */
+exports.UNREADABLE_EXAMPLES = 16;
+const refused = (code, message) => ({
+    ok: false,
+    refusal: {
+        kind: "refused",
+        finding: { code, severity: "error", message },
+        code,
+        message,
+    },
+});
+/**
+ * Why a snapshot's version could not be loaded or re-cited, said accurately: it is not a version of
+ * the line (`seen-version-unknown`), its artifact was reclaimed (`seen-artifact-missing`), or anything
+ * else (`seen-version-unreadable`, with the underlying code). Nothing is recorded in any case.
+ */
+const versionRefusal = (refusal) => {
+    const finding = refusal.kind === "refused"
+        ? refusal.finding
+        : { code: refusal.kind, message: "the line moved while recording" };
+    if (finding.code === "version-unknown")
+        return refused("seen-version-unknown", "the snapshot's version is not a version of this line");
+    if (finding.code === "artifact-missing")
+        return refused("seen-artifact-missing", "the snapshot's version exists but its artifact is gone (already reclaimed); nothing is recorded");
+    return refused("seen-version-unreadable", `the snapshot's version could not be loaded (${finding.code}): ${finding.message}`);
+};
+const seenStreamKey = (experienceId, viewerId) => `${encodeURIComponent(experienceId)}/${encodeURIComponent(viewerId)}`;
+exports.seenStreamKey = seenStreamKey;
+const sourceKey = (s) => {
+    const o = s;
+    if (typeof o !== "object" || o === null)
+        return undefined;
+    return JSON.stringify(o.kind === "handle"
+        ? ["h", o.handle]
+        : o.kind === "projection"
+            ? ["p", o.id, o.path, o.version]
+            : null);
+};
+const validId = (v) => typeof v === "string" && v.length > 0 && v.length <= MAX_ID;
+/**
+ * The floor in force: the last well-formed floor among the tail records (a malformed record carries
+ * none, so the scan goes back past it rather than resetting to 0 and undoing retention). Beyond the
+ * scan there is nothing to go on: 0, which keeps more, never less.
+ */
+const floorOf = (tail) => {
+    for (let i = tail.length - 1; i >= 0; i--) {
+        const rec = tail[i];
+        if (rec.type !== exports.VIEW_RECORDED && rec.type !== exports.VIEWS_RETAINED)
+            continue;
+        const f = rec.payload?.floor;
+        if (Number.isSafeInteger(f) && f >= 0 && f < rec.sequence)
+            return f;
+    }
+    return 0;
+};
+/** The (experience, viewer) a stream key names, or `undefined` if it does not round-trip `seenStreamKey`. */
+const parseStreamKey = (key) => {
+    const slash = key.indexOf("/");
+    if (slash < 0)
+        return undefined;
+    try {
+        const experienceId = decodeURIComponent(key.slice(0, slash));
+        const viewerId = decodeURIComponent(key.slice(slash + 1));
+        return (0, exports.seenStreamKey)(experienceId, viewerId) === key ? { experienceId, viewerId } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+class SeenLog {
+    events;
+    content;
+    lineage;
+    keys;
+    maxViews;
+    maxAgeMs;
+    maxSkewMs;
+    slack;
+    now;
+    policy;
+    constructor(opts) {
+        this.policy = (0, ui_core_1.mergeReadPolicy)(opts.lineage.readPolicy, opts.readPolicy);
+        // A record is per-viewer data; it must never share streams with the lineage it describes (a
+        // shared prefix would put a viewer's manifests among the line's versions, and make an
+        // experienceId that spells a stream key read as one). An unreadable prefix cannot be proven
+        // disjoint, so it is refused too (see `Lineage.sharesStreamsWith`).
+        if (opts.lineage.sharesStreamsWith(opts.events) ||
+            opts.events.streamPrefix === store_1.LINEAGE_STREAM_PREFIX)
+            throw new Error("SeenLog: `events` must be a store of its own with a readable `streamPrefix` that does not overlap the lineage's: use seenStoreOptions");
+        const maxViews = opts.retention?.maxViews ?? exports.DEFAULT_MAX_SEEN_VIEWS;
+        const maxAgeMs = opts.retention?.maxAgeMs;
+        if (!Number.isSafeInteger(maxViews) || maxViews < 1 || maxViews > MAX_VIEWS_CAP)
+            throw new Error(`SeenLog: retention.maxViews must be an integer in 1..${MAX_VIEWS_CAP}`);
+        if (maxAgeMs !== undefined && (!Number.isFinite(maxAgeMs) || maxAgeMs <= 0))
+            throw new Error("SeenLog: retention.maxAgeMs must be a positive number of milliseconds");
+        const maxSkewMs = opts.retention?.maxSkewMs ?? exports.DEFAULT_MAX_SKEW_MS;
+        if (!Number.isFinite(maxSkewMs) || maxSkewMs < 0)
+            throw new Error("SeenLog: retention.maxSkewMs must be a non-negative number of milliseconds");
+        if (typeof opts.keys?.getOrCreate !== "function")
+            throw new Error("SeenLog: `keys` (a SeenKeyStore) is required");
+        this.events = opts.events;
+        this.content = opts.content;
+        this.lineage = opts.lineage;
+        this.keys = opts.keys;
+        this.maxViews = maxViews;
+        this.maxAgeMs = maxAgeMs;
+        this.maxSkewMs = maxSkewMs;
+        this.slack = Math.max(1, Math.ceil(maxViews / 10));
+        this.now = opts.now ?? (() => new Date().toISOString());
+    }
+    /** The content store value blobs live in (for the collector). */
+    get contentStore() {
+        return this.content;
+    }
+    /** The lineage the records name versions of (for the collector's roots). */
+    get lineageOf() {
+        return this.lineage;
+    }
+    // ── log windows (bounded by retention, not by the age of the log) ───────────
+    async lastRecords(key, n) {
+        if (this.events.readTail !== undefined)
+            return this.events.readTail(key, n);
+        const all = await this.events.read(key);
+        return all.slice(Math.max(0, all.length - n));
+    }
+    async after(key, floor) {
+        if (this.events.readAfter !== undefined)
+            return this.events.readAfter(key, floor);
+        return (await this.events.read(key)).filter((r) => r.sequence > floor);
+    }
+    /** The live views (oldest first) of a window: after the floor, inside the age limit, newest `maxViews`. */
+    liveViews(window, conservative = false) {
+        let views = window.filter((r) => r.type === exports.VIEW_RECORDED);
+        if (this.maxAgeMs !== undefined) {
+            // the collector (irreversible) keeps everything inside `maxAgeMs + maxSkewMs`; a read is exact
+            const cutoff = Date.parse(this.now()) - this.maxAgeMs - (conservative ? this.maxSkewMs : 0);
+            views = views.filter((r) => Date.parse(r.at) >= cutoff);
+        }
+        return views.length > this.maxViews ? views.slice(views.length - this.maxViews) : views;
+    }
+    /**
+     * Record that `viewerId` was shown `snapshot` (built with core's `snapshotSeen`). The snapshot is
+     * not trusted: its version must be a version of the line, its entries are re-validated, re-capped
+     * and RESTAMPED against that version's artifact (a stamp laxer than the artifact says is raised; an
+     * entry the recording viewer may not see is dropped), and values are measured again. An identical
+     * consecutive view records nothing (`recorded: false`). A new view ALWAYS records: when the
+     * viewer's window is full, the oldest views roll off (see the header). Refuses an erased viewer.
+     * Performs no authorization: `viewerId` and `viewer` are the host's claims.
+     */
+    async record(input) {
+        const { experienceId, viewerId, snapshot } = input;
+        if (!validId(experienceId) || !validId(viewerId))
+            return refused("seen-id-invalid", "experienceId and viewerId are 1-256 character strings");
+        if (typeof snapshot !== "object" || snapshot === null || !Array.isArray(snapshot.entries))
+            return refused("seen-snapshot-invalid", "the snapshot is not a snapshot");
+        if (!Number.isSafeInteger(snapshot.omitted) || snapshot.omitted < 0)
+            return refused("seen-snapshot-invalid", "`omitted` is not a non-negative integer");
+        if (snapshot.entries.length > ui_core_1.MAX_SEEN_SOURCES)
+            return refused("seen-too-many-sources", `a snapshot holds at most ${ui_core_1.MAX_SEEN_SOURCES} sources`);
+        const sourceKeys = new Set();
+        for (const e of snapshot.entries) {
+            const k = sourceKey(e?.source);
+            if (k !== undefined && sourceKeys.has(k))
+                return refused("seen-duplicate-source", "a snapshot names one source twice");
+            if (k !== undefined)
+                sourceKeys.add(k);
+        }
+        if (snapshot.experienceId !== experienceId)
+            return refused("seen-wrong-line", "the snapshot is of another experience");
+        const key = (0, exports.seenStreamKey)(experienceId, viewerId);
+        // Gate on erasure BEFORE any blob is written, and obtain the data key (fail closed: no key, no record).
+        const gate = await this.lastRecords(key, 1);
+        if (gate[0]?.type === exports.VIEWER_ERASED)
+            return refused("seen-viewer-erased", "this viewer was erased; nothing more is recorded for them");
+        let dataKey;
+        try {
+            dataKey = (0, seenCrypto_1.deriveSeenKeys)(await this.keys.getOrCreate((0, seenCrypto_1.seenKeySubject)(key)));
+        }
+        catch {
+            return refused("seen-key-unavailable", "the viewer's data key is unavailable (erased, or the key store failed): nothing is recorded");
+        }
+        const art = await this.lineage.get(experienceId, snapshot.versionHash);
+        if (!art.ok)
+            return versionRefusal(art.refusal);
+        // The record will cite this version for as long as the view is in retention: tell the store it
+        // was just re-cited (touch, no put) so a collector racing this write spares the artifact.
+        const cited = await this.lineage.cite(experienceId, [snapshot.versionHash]);
+        if (!cited.ok)
+            return versionRefusal(cited.refusal);
+        // Restamp + drop what the recording viewer may not see, with core's one redactor.
+        const checked = (0, ui_core_1.redactSeen)(snapshot.entries, art.value, {
+            ...(input.viewer !== undefined && { viewer: input.viewer }),
+            ...(input.audience !== undefined && { audience: input.audience }),
+            ...(0, ui_core_1.mergeReadPolicy)(this.policy, input),
+        });
+        let total = 0;
+        const shapes = [];
+        const refs = [];
+        for (const e of checked.entries) {
+            const shape = EntrySchema.omit({ sealed: true }).safeParse({
+                source: e.source,
+                nodeIds: e.nodeIds,
+                class: e.class,
+                state: e.state,
+                ...(e.status !== undefined && { status: e.status }),
+                // a `seen` entry's size is sealed with its ref, never stored in the clear
+                // `oversize` / `over-budget`: only a power-of-two size class survives, never the exact count
+                ...(e.bytes !== undefined && e.state !== "seen" && { bytes: sizeClass(e.bytes) }),
+            });
+            if (!shape.success)
+                return refused("seen-entry-invalid", "a snapshot entry is malformed");
+            let ref;
+            if (e.state === "seen") {
+                let bytes;
+                try {
+                    bytes = (0, plugin_content_1.encodeValue)(e.value);
+                }
+                catch {
+                    return refused("seen-value-unencodable", "a seen value is not encodable");
+                }
+                if (bytes.length > ui_core_1.MAX_SEEN_VALUE_BYTES)
+                    return refused("seen-value-too-large", `a value is over ${ui_core_1.MAX_SEEN_VALUE_BYTES} bytes`);
+                total += bytes.length;
+                if (total > ui_core_1.MAX_SEEN_TOTAL_BYTES)
+                    return refused("seen-over-budget", `the snapshot is over ${ui_core_1.MAX_SEEN_TOTAL_BYTES} bytes`);
+                // Blob BEFORE manifest: a crash between the two leaks a blob (reclaimed by the next sweep
+                // past its grace period) and never loses a live value. A re-put of a held blob bumps its
+                // touch time, which is what protects a value another record is about to cite.
+                const put = await this.content.put(bytes);
+                if (put.__loomContent.length > seenCrypto_1.MAX_SEALED_ADDRESS_CHARS)
+                    return refused("seen-address-invalid", "the content store returned an unexpectedly long address");
+                ref = { ref: put, bytes: bytes.length };
+            }
+            shapes.push(shape.data);
+            refs.push(ref);
+        }
+        const body = {
+            experienceId,
+            versionHash: snapshot.versionHash,
+            viewerId,
+            ...((0, ui_core_1.effectiveViewer)(input.viewer, input.audience)?.clearance !== undefined && {
+                clearance: String((0, ui_core_1.effectiveViewer)(input.viewer, input.audience)?.clearance),
+            }),
+            entries: shapes.map((s, i) => ({ ...s, ...(refs[i] !== undefined && { ref: refs[i] }) })),
+            omitted: snapshot.omitted,
+            restricted: snapshot.restricted === true || checked.restricted,
+        };
+        const digest = (0, seenCrypto_1.keyedDigest)(dataKey.mac, JSON.stringify(body));
+        for (let attempt = 0; attempt < MAX_APPEND_RETRIES; attempt++) {
+            const recent = await this.lastRecords(key, FLOOR_SCAN);
+            const last = recent[recent.length - 1];
+            if (last?.type === exports.VIEWER_ERASED)
+                return refused("seen-viewer-erased", "this viewer was erased; nothing more is recorded for them");
+            const tip = last?.sequence ?? 0;
+            const floor = floorOf(recent);
+            const lastView = [...recent].reverse().find((r) => r.type === exports.VIEW_RECORDED);
+            if (lastView !== undefined &&
+                lastView.sequence > floor &&
+                lastView.payload?.digest === digest)
+                return { ok: true, value: { recorded: false, sequence: lastView.sequence } };
+            const sequence = tip + 1;
+            const payload = {
+                ...body,
+                entries: shapes.map((s, i) => {
+                    const ref = refs[i];
+                    return {
+                        ...s,
+                        ...(ref !== undefined && {
+                            sealed: (0, seenCrypto_1.sealRef)(dataKey.enc, (0, seenCrypto_1.refAad)(experienceId, viewerId, sequence, i), ref.ref, ref.bytes),
+                        }),
+                    };
+                }),
+                digest,
+                floor,
+            };
+            // The record must parse as what a READ will parse: one that does not would be counted
+            // `malformed` forever (the log has no delete), so it is refused here.
+            if (!exports.ViewRecordPayload.safeParse(payload).success)
+                return refused("seen-record-invalid", "the record would not be readable (a field is out of bounds)");
+            // Re-read the key IMMEDIATELY before the append: an erasure that landed since `getOrCreate`
+            // (a destroyed key, or a tombstone not yet written) must not be followed by a sealed record.
+            let current;
+            try {
+                current = await this.keys.get((0, seenCrypto_1.seenKeySubject)(key));
+            }
+            catch {
+                return refused("seen-key-unavailable", "the viewer's data key is unavailable (erased, or the key store failed): nothing is recorded");
+            }
+            if (current === null)
+                return refused("seen-viewer-erased", "this viewer was erased; nothing more is recorded for them");
+            const out = await this.events.append(key, tip, {
+                type: exports.VIEW_RECORDED,
+                at: this.now(),
+                payload,
+            });
+            if (out.ok) {
+                await this.rollOff(key, out.sequence, floor);
+                return { ok: true, value: { recorded: true, sequence: out.sequence } };
+            }
+        }
+        return refused("seen-contended", "could not append after repeated lost races");
+    }
+    /**
+     * Retention: append a watermark when enough has aged out. Best effort (a lost race or a failure
+     * only defers it: reads and the collector apply the window themselves, so correctness never
+     * depends on a watermark having been written). `slack` batches the writes: one watermark per
+     * `slack` roll-offs, not one per view.
+     */
+    async rollOff(key, tip, floor) {
+        try {
+            const countTrigger = tip - floor > this.maxViews + this.slack;
+            // The persisted (irreversible) age watermark is conservative by `maxSkewMs`: a writer whose
+            // clock runs ahead cannot roll off views still inside the window by true time (see SeenRetention).
+            const cutoff = this.maxAgeMs === undefined
+                ? undefined
+                : Date.parse(this.now()) - this.maxAgeMs - this.maxSkewMs;
+            let ageTrigger = false;
+            if (cutoff !== undefined) {
+                const oldest = (this.events.readAfter !== undefined
+                    ? await this.events.readAfter(key, floor, 1)
+                    : await this.after(key, floor))[0];
+                ageTrigger = oldest !== undefined && Date.parse(oldest.at) < cutoff;
+            }
+            if (!countTrigger && !ageTrigger)
+                return;
+            // The window is read only when a watermark may be due (about once per `slack` views), so the
+            // amortized cost per record is O(window / slack), and the floor is exact: it leaves `maxViews`
+            // VIEWS (not records) readable.
+            const window = await this.after(key, floor);
+            const views = window.filter((r) => r.type === exports.VIEW_RECORDED);
+            let next = floor;
+            if (views.length > this.maxViews)
+                next = views[views.length - this.maxViews - 1].sequence;
+            let byAge = floor;
+            if (cutoff !== undefined)
+                for (const r of window)
+                    if (Date.parse(r.at) < cutoff)
+                        byAge = Math.max(byAge, r.sequence);
+                    else
+                        break;
+            // age-only roll-off is batched too (one watermark per `slack` expired views, not one per view)
+            if (byAge - floor >= this.slack || (countTrigger && byAge > floor))
+                next = Math.max(next, byAge);
+            if (next > floor)
+                await this.events.append(key, tip, {
+                    type: exports.VIEWS_RETAINED,
+                    at: this.now(),
+                    payload: { floor: Math.min(next, tip) },
+                });
+        }
+        catch {
+            /* deferred to the next record */
+        }
+    }
+    /**
+     * Erase a viewer: destroy their data key (the irreversible step), then write a tombstone. After
+     * it, the stream holds no decryptable ref, `read` reports `erased: true`, and `record` refuses.
+     * Idempotent and safe to rerun after a crash (a rerun completes whichever half is missing). The
+     * value BLOBS the viewer cited are reclaimed by the next `collectSeenGarbage` pass (unless another
+     * viewer or the lineage still cites them). The stream's structure stays (see the header).
+     * AUTHORIZATION IS THE HOST'S: erasing a (experience, viewer) pair that never existed still
+     * writes a tombstone stream (and permanently bars that viewer from recording there), so the host
+     * decides who may erase what; this method performs no check.
+     */
+    async eraseViewer(input) {
+        const { experienceId, viewerId } = input;
+        if (!validId(experienceId) || !validId(viewerId))
+            return refused("seen-id-invalid", "experienceId and viewerId are 1-256 character strings");
+        const key = (0, exports.seenStreamKey)(experienceId, viewerId);
+        try {
+            await this.keys.destroy((0, seenCrypto_1.seenKeySubject)(key));
+        }
+        catch {
+            return refused("seen-key-unavailable", "the key store failed to destroy the key: rerun the erasure");
+        }
+        for (let attempt = 0; attempt < MAX_APPEND_RETRIES; attempt++) {
+            const last = (await this.lastRecords(key, 1))[0];
+            if (last?.type === exports.VIEWER_ERASED)
+                return { ok: true, value: { erased: true } };
+            const out = await this.events.append(key, last?.sequence ?? 0, {
+                type: exports.VIEWER_ERASED,
+                at: this.now(),
+                payload: { experienceId, viewerId },
+            });
+            if (out.ok)
+                return { ok: true, value: { erased: true } };
+        }
+        return refused("seen-erase-incomplete", "the key is destroyed (the viewer is unreadable) but the tombstone was not written: rerun the erasure");
+    }
+    /**
+     * Erase ONE data subject across every experience: enumerate the seen streams (`listStreams`;
+     * refused with `seen-enumeration-unavailable` if the store cannot), and erase `viewerId`'s stream in
+     * each experience (see {@link eraseViewer}, including its authorization note). Idempotent and
+     * resumable: a rerun skips what is erased and completes what is not. A per-experience failure does
+     * not stop the others; `complete` is true only when every experience was erased.
+     *
+     * COVERAGE: only streams that EXIST when enumeration runs are erased. A stream created after
+     * that point (a new view by this viewer during the erase) is not covered: the host must serialize
+     * erasure against new views for the subject, or rerun. An orphan key with no stream (a crash
+     * between `getOrCreate` and the first append) is not destroyed by this enumeration; it holds no
+     * data (a key and nothing sealed under it).
+     */
+    async eraseViewerEverywhere(input) {
+        const { viewerId } = input;
+        if (!validId(viewerId))
+            return refused("seen-id-invalid", "viewerId is a 1-256 character string");
+        if (this.events.listStreams === undefined)
+            return refused("seen-enumeration-unavailable", "the store cannot enumerate its streams, so a viewer cannot be erased across experiences");
+        const experiences = [];
+        try {
+            for await (const key of this.events.listStreams()) {
+                const parsed = parseStreamKey(key);
+                if (parsed !== undefined && parsed.viewerId === viewerId)
+                    experiences.push(parsed.experienceId);
+            }
+        }
+        catch {
+            return refused("seen-enumeration-unavailable", "listing the seen streams failed: rerun");
+        }
+        const results = [];
+        for (const experienceId of experiences) {
+            const r = await this.eraseViewer({ experienceId, viewerId });
+            results.push(r.ok ? { experienceId, erased: true } : { experienceId, erased: false, refusal: r.refusal });
+        }
+        return { ok: true, value: { results, complete: results.every((r) => r.erased) } };
+    }
+    /**
+     * What `viewerId` was shown, newest first (at most `limit`, default 20, hard cap
+     * `MAX_SEEN_READ`), as seen by `reader`: entries the reader may not see are withheld (and
+     * `restricted` says only that something was), BEFORE any value blob is fetched. Only views inside
+     * the retention window are returned. A malformed record is counted in `malformed`, never thrown.
+     * `until` (ISO time) keeps records at or before it: the view as of then. An erased viewer (key
+     * destroyed or tombstoned) returns `{ erased: true, views: [] }`: nothing is decryptable, so
+     * nothing is shown.
+     */
+    async read(input) {
+        const { experienceId, viewerId } = input;
+        if (!validId(experienceId) || !validId(viewerId))
+            return refused("seen-id-invalid", "experienceId and viewerId are 1-256 character strings");
+        const limit = Math.max(1, Math.min(exports.MAX_SEEN_READ, Number.isInteger(input.limit) ? input.limit : 20));
+        const key = (0, exports.seenStreamKey)(experienceId, viewerId);
+        const tail = await this.lastRecords(key, FLOOR_SCAN);
+        const tipRec = tail[tail.length - 1];
+        if (tipRec === undefined)
+            return { ok: true, value: { views: [], malformed: 0, erased: false } };
+        let master;
+        try {
+            master = await this.keys.get((0, seenCrypto_1.seenKeySubject)(key));
+        }
+        catch {
+            return refused("seen-key-unavailable", "the key store failed: nothing is shown");
+        }
+        if (tipRec.type === exports.VIEWER_ERASED || master === null)
+            return { ok: true, value: { views: [], malformed: 0, erased: true } };
+        const dataKey = (0, seenCrypto_1.deriveSeenKeys)(master);
+        let malformed = 0;
+        const picked = [];
+        const live = this.liveViews(await this.after(key, floorOf(tail)));
+        for (let i = live.length - 1; i >= 0 && picked.length < limit; i--) {
+            const rec = live[i];
+            if (input.until !== undefined && rec.at > input.until)
+                continue;
+            const parsed = exports.ViewRecordPayload.safeParse(rec.payload);
+            if (!parsed.success ||
+                parsed.data.experienceId !== experienceId ||
+                parsed.data.viewerId !== viewerId) {
+                malformed += 1;
+                continue;
+            }
+            picked.push({ rec, p: parsed.data });
+        }
+        // The line is folded ONCE for the whole read (not once per distinct version).
+        const got = await this.lineage.getMany(experienceId, picked.map(({ p }) => p.versionHash));
+        const artifacts = got.ok ? got.value : new Map();
+        const views = [];
+        for (const { rec, p } of picked) {
+            const shown = (0, ui_core_1.redactSeen)(p.entries.map((e) => ({
+                source: e.source,
+                nodeIds: e.nodeIds,
+                class: e.class,
+                state: e.state,
+                ...(e.status !== undefined && { status: e.status }),
+                ...(e.bytes !== undefined && { bytes: e.bytes }),
+            })), artifacts.get(p.versionHash), {
+                ...(input.reader !== undefined && { viewer: input.reader }),
+                ...(input.audience !== undefined && { audience: input.audience }),
+                ...(0, ui_core_1.mergeReadPolicy)(this.policy, input),
+            });
+            // A ref belongs to the entry at its POSITION in the record (`indexes`), never to a source:
+            // two entries may not be told apart by what they name.
+            let restricted = p.restricted || shown.restricted;
+            const resolved = [];
+            for (const [k, e] of shown.entries.entries()) {
+                if (e.state !== "seen") {
+                    resolved.push(e);
+                    continue;
+                }
+                const idx = shown.indexes[k];
+                const sealed = p.entries[idx]?.sealed;
+                if (sealed === undefined) {
+                    resolved.push({ ...e, state: "absent" });
+                    continue;
+                }
+                const opened = this.openRef(dataKey.enc, experienceId, viewerId, rec.sequence, idx, sealed);
+                if (opened === undefined) {
+                    // tampered, transplanted, or sealed under another key: withheld, never a plaintext fallback
+                    restricted = true;
+                    continue;
+                }
+                const { ref, bytes: size } = opened;
+                const bytes = await this.content.get(ref);
+                if (bytes === undefined || bytes === null) {
+                    // erased or lost: the value is gone, the fact that it was seen is not
+                    resolved.push({ ...e, state: "absent" });
+                    continue;
+                }
+                if ((0, plugin_content_1.contentAddress)(bytes) !== ref.__loomContent) {
+                    // the store handed back bytes that are not what the manifest named
+                    resolved.push({ ...e, state: "corrupt" });
+                    continue;
+                }
+                try {
+                    resolved.push({ ...e, value: (0, plugin_content_1.decodeValue)(bytes), bytes: size });
+                }
+                catch {
+                    restricted = true;
+                }
+            }
+            views.push({
+                sequence: rec.sequence,
+                at: rec.at,
+                versionHash: p.versionHash,
+                entries: resolved,
+                restricted,
+                omitted: p.omitted,
+            });
+        }
+        return { ok: true, value: { views, malformed, erased: false } };
+    }
+    openRef(enc, experienceId, viewerId, sequence, index, sealed) {
+        return (0, seenCrypto_1.openRef)(enc, (0, seenCrypto_1.refAad)(experienceId, viewerId, sequence, index), sealed);
+    }
+    /**
+     * Call `visit` with the content address of every DECRYPTABLE ref inside every viewer's retention
+     * window (kept conservatively: views inside `maxAgeMs + maxSkewMs`; with out-of-order timestamps within `maxSkewMs` at the `maxViews` cap this window can differ from the exact read window's newest-N, in the direction of keeping MORE): the seen log's half of the
+     * collector's root set. Erased viewers (key ABSENT: the shred path) and rolled-off views
+     * contribute nothing, which is exactly what lets their unique blobs be swept. THROWS if the store
+     * cannot enumerate its streams or the key store fails (an unreadable root is not an absent one).
+     *
+     * Returns what it could NOT read inside the live window (a stream key that does not round-trip, a
+     * record that fails to parse, a sealed ref that fails to open under a PRESENT key). Those are not
+     * absent either: whatever they cite is unrooted here, so a collector must refuse to sweep on a
+     * non-zero count (see `collectSeenGarbage`).
+     *
+     * `visitVersion` (optional) is called with the (experience, version) of every live view: the seen log
+     * READS that version's artifact from the lineage, so a collector that reclaims old versions must
+     * keep it (see `collectSeenRoots`).
+     */
+    async forEachLiveRef(visit, visitVersion) {
+        if (this.events.listStreams === undefined)
+            throw new Error("SeenLog.forEachLiveRef: the store cannot enumerate its streams");
+        let streams = 0;
+        let records = 0;
+        let refs = 0;
+        const ex = { streams: [], records: [], refs: [] };
+        const note = (list, what) => {
+            if (list.length < exports.UNREADABLE_EXAMPLES)
+                list.push(what);
+        };
+        for await (const key of this.events.listStreams()) {
+            const id = parseStreamKey(key);
+            if (id === undefined) {
+                streams += 1;
+                note(ex.streams, key);
+                continue;
+            }
+            const { experienceId, viewerId } = id;
+            const tail = await this.lastRecords(key, FLOOR_SCAN);
+            const tipRec = tail[tail.length - 1];
+            if (tipRec === undefined || tipRec.type === exports.VIEWER_ERASED)
+                continue;
+            const master = await this.keys.get((0, seenCrypto_1.seenKeySubject)(key)); // a throw propagates: abort the pass
+            if (master === null)
+                continue; // erased (key absent): nothing here is a root, by design
+            const { enc } = (0, seenCrypto_1.deriveSeenKeys)(master);
+            for (const rec of this.liveViews(await this.after(key, floorOf(tail)), true)) {
+                const parsed = exports.ViewRecordPayload.safeParse(rec.payload);
+                if (!parsed.success ||
+                    parsed.data.experienceId !== experienceId ||
+                    parsed.data.viewerId !== viewerId) {
+                    records += 1;
+                    note(ex.records, `${key}@${rec.sequence}`);
+                    continue;
+                }
+                visitVersion?.(experienceId, parsed.data.versionHash);
+                for (const [i, e] of parsed.data.entries.entries()) {
+                    if (e.sealed === undefined)
+                        continue;
+                    const opened = this.openRef(enc, experienceId, viewerId, rec.sequence, i, e.sealed);
+                    if (opened === undefined) {
+                        refs += 1;
+                        note(ex.refs, `${key}@${rec.sequence}#${i}`);
+                    }
+                    else
+                        visit(opened.ref.__loomContent);
+                }
+            }
+        }
+        return { streams, records, refs, examples: ex };
+    }
+}
+exports.SeenLog = SeenLog;
+/** Convenience: the manifest stream a `SeenLog` over an `EventStore` should use. */
+exports.seenStoreOptions = {
+    streamPrefix: exports.SEEN_STREAM_PREFIX,
+    workflowId: exports.SEEN_WORKFLOW_ID,
+};
+//# sourceMappingURL=seen.js.map