@loomwork/ui-lineage 0.0.0-stage → 0.1.0

package/dist/esm/lineage.js

@@ -0,0 +1,1376 @@
+import { isKeyUnavailable, isPayloadShredded } from "@loomwork/event-runtime";
+import { Provenance as ProvenanceSchema, Sensitivity, apply, applyAt, boundSummary, emptyLedger, experienceClassFloor, explainNode, foldProvenance, mergeReadPolicy, replay, } from "@loomwork/ui-core";
+import { getExperience, putExperience, seal } from "@loomwork/ui-core/log";
+import { authorOf, branchArtifact, revertArtifact } from "./derive";
+import { EXPERIENCE_BRANCHED, EXPERIENCE_COMPOSED, EXPERIENCE_PROMOTED, EXPERIENCE_REVERTED, } from "./events";
+import { retainedVersions, validateRetentionPolicy } from "./retention";
+import { foldLineage, payloadRefusal } from "./state";
+import { InMemoryLineageStore, LINEAGE_STREAM_PREFIX, LINEAGE_WORKFLOW_ID, } from "./store";
+/**
+ * Thrown by the reads that return plain values (`forEachContentRef`, `pins` and so `rootsFor`) when
+ * a line's key is gone AND the host confirmed the erasure (`LineageOptions.confirmErased`). Those
+ * reads SKIP a confirmed-erased line (it contributes no roots), so this reaches a caller only from a
+ * single-line read; every method that returns a `LineageResult` (or `verify`'s findings) reports the
+ * same condition as a `refused` result with code `line-erased` instead of throwing.
+ */
+export class LineErasedError extends Error {
+    experienceId;
+    name = "LineErasedError";
+    code = "line-erased";
+    confirmed = true;
+    constructor(experienceId, options) {
+        super(`lineage "${experienceId}" is erased: its key is destroyed (confirmed by the host)`, options);
+        this.experienceId = experienceId;
+        Object.setPrototypeOf(this, LineErasedError.prototype);
+    }
+}
+/**
+ * The line's key is unavailable on this node, or its ciphertext / artifact does not open, and the
+ * erasure is NOT confirmed (no `confirmErased` hook, or it said no). Could be a destroyed key, a key
+ * this node does not hold, a tampered event, a drifted `subjectOf`, or an artifact written before an
+ * `EncryptingContentStore` was composed (`reason: "artifact-unsealed"`). Fail closed, but not an
+ * erasure: GC refuses rather than guess, and a read says so. `reason` is also the refusal's finding code.
+ */
+export class LineUnreadableError extends Error {
+    experienceId;
+    name = "LineUnreadableError";
+    code = "line-unreadable";
+    confirmed = false;
+    reason;
+    constructor(experienceId, options) {
+        super(`lineage "${experienceId}" is unreadable: its key is unavailable on this node or its ciphertext does not open; not confirmed erased`, options?.cause === undefined ? undefined : { cause: options.cause });
+        this.experienceId = experienceId;
+        this.reason = options?.reason ?? "line-unreadable";
+        Object.setPrototypeOf(this, LineUnreadableError.prototype);
+    }
+}
+/** Is `err` a read failure that makes a line unreadable? The kernel's stable predicates, never message text. */
+const isUnreadableCause = (err) => isKeyUnavailable(err) || isPayloadShredded(err);
+/** loom's "the blob exists but does not open although the key exists" (plaintext or damaged bytes). */
+const isUndecryptable = (err) => err instanceof Error && err.name === "ContentUndecryptableError";
+/**
+ * Classify a read failure of one line: `undefined` when it is not an unreadable-line failure
+ * (rethrow it), else a typed error. ONE rule: `line-erased` iff the host's `confirmErased` says so;
+ * `isPayloadShredded` alone is not confirmation. An undecryptable blob is never an erasure.
+ */
+export async function classifyLineFailure(experienceId, err, confirmErased) {
+    if (isUndecryptable(err))
+        return new LineUnreadableError(experienceId, { cause: err, reason: "artifact-unsealed" });
+    if (!isUnreadableCause(err))
+        return undefined;
+    let confirmed = false;
+    if (confirmErased !== undefined) {
+        try {
+            confirmed = (await confirmErased(experienceId)) === true;
+        }
+        catch {
+            confirmed = false;
+        }
+    }
+    return confirmed
+        ? new LineErasedError(experienceId, { cause: err })
+        : new LineUnreadableError(experienceId, { cause: err });
+}
+const blockedFinding = (e) => e instanceof LineErasedError
+    ? {
+        code: "line-erased",
+        severity: "error",
+        message: `lineage "${e.experienceId}" is erased: its key is destroyed (confirmed); nothing readable or writable`,
+    }
+    : {
+        code: e.reason,
+        severity: "error",
+        message: e.reason === "artifact-unsealed"
+            ? `lineage "${e.experienceId}" is unreadable: an artifact blob did not open under the line's key (written before sealing was composed, or damaged); not an erasure`
+            : `lineage "${e.experienceId}" is unreadable: its key is unavailable on this node or its ciphertext does not open; not confirmed erased`,
+    };
+const blocked = (e) => fromFinding(blockedFinding(e));
+const BLOCKED_CODES = new Set([
+    "line-erased",
+    "line-unreadable",
+    "artifact-unsealed",
+]);
+const isBlockedRefusal = (r) => r.refusal.kind === "refused" && BLOCKED_CODES.has(r.refusal.finding.code);
+const isErasedRefusal = (r) => r.refusal.kind === "refused" && r.refusal.finding.code === "line-erased";
+const refused = (code, message) => ({
+    ok: false,
+    refusal: { kind: "refused", finding: { code, severity: "error", message } },
+});
+const fromFinding = (finding) => ({
+    ok: false,
+    refusal: { kind: "refused", finding },
+});
+/** Bound on re-reading after a lost append whose head did not move (a promotion slipped in). */
+const MAX_TIP_RETRIES = 16;
+/** Bound on how many source lines `verify` follows through branches (a branch of a branch of ...). */
+const MAX_VERIFY_DEPTH = 32;
+/** Whether `hash` is `ancestor` or reaches it through `parents` within the line (iterative, cycle-safe). */
+function descendsFrom(state, hash, ancestor) {
+    const seen = new Set();
+    const stack = [hash];
+    for (let h = stack.pop(); h !== undefined; h = stack.pop()) {
+        if (h === ancestor)
+            return true;
+        if (seen.has(h))
+            continue;
+        seen.add(h);
+        for (const p of state.versions.get(h)?.parents ?? [])
+            stack.push(p);
+    }
+    return false;
+}
+/**
+ * Every `by` a write would record (the write's own and each op's) must satisfy core's `Provenance`,
+ * the schema the fold enforces on read. The fold stays strict; the REFUSAL is here, because the log
+ * has no delete and one event that does not fold bricks the line for every reader.
+ */
+function provenanceRefusal(by, ops) {
+    const bad = (what) => refused("provenance-invalid", `${what} is not a valid provenance (nothing was written)`);
+    if (!ProvenanceSchema.safeParse(by).success)
+        return bad("`by`");
+    if (ops !== undefined) {
+        if (!Array.isArray(ops))
+            return refused("ops-invalid", "ops must be an array");
+        for (const [i, r] of ops.entries())
+            if (typeof r !== "object" || r === null || !ProvenanceSchema.safeParse(r.by).success)
+                return bad(`op #${i}'s \`by\``);
+    }
+    return undefined;
+}
+/** Iterative (no recursion limit) walk for `{ __loomContent: string }` leaves. */
+function walkContentRefs(root, visit) {
+    const stack = [root];
+    const seen = new Set();
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        if (typeof cur !== "object" || cur === null || seen.has(cur))
+            continue;
+        seen.add(cur);
+        const a = cur.__loomContent;
+        if (typeof a === "string")
+            visit(a);
+        for (const v of Array.isArray(cur) ? cur : Object.values(cur))
+            stack.push(v);
+    }
+}
+/** Run `fn` over `items` with at most `limit` in flight; rejects on the first failure (nothing after it starts). */
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    let failed = false;
+    const worker = async () => {
+        while (!failed && next < items.length) {
+            const i = next++;
+            try {
+                out[i] = await fn(items[i]);
+            }
+            catch (e) {
+                failed = true;
+                throw e;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
+const sameSet = (a, b) => a.length === b.length && [...a].sort().every((x, i) => x === [...b].sort()[i]);
+export class Lineage {
+    events;
+    content;
+    now;
+    policy;
+    streamPrefix;
+    workflowId;
+    confirmErased;
+    constructor(opts) {
+        this.policy = mergeReadPolicy(opts.readPolicy);
+        this.events = opts.events;
+        this.content = opts.content;
+        this.now = opts.now ?? (() => new Date().toISOString());
+        this.confirmErased = opts.confirmErased;
+        const p = opts.events.streamPrefix;
+        if (opts.content.sealsContent === true &&
+            !(typeof p === "string" && p.length > 0))
+            throw new Error("Lineage: the content store seals per subject (sealsContent: true) but the events store does not expose a streamPrefix (use eventStoreLineageStore): the blobs could be sealed under a different subject than the line's events");
+        this.streamPrefix = typeof p === "string" && p.length > 0 ? p : LINEAGE_STREAM_PREFIX;
+        const w = opts.events.workflowId;
+        this.workflowId = typeof w === "string" && w.length > 0 ? w : LINEAGE_WORKFLOW_ID;
+    }
+    /**
+     * The `ContentAccess` of one line's artifact blobs: the line's STREAM id (the id its events live
+     * under) and the lineage workflow id. A content store that seals by owner (`EncryptingContentStore`)
+     * resolves it through the host's `subjectOf`, the same mapping its event store applies to the
+     * stream, so one mapping covers a line's events and blobs. A plain store ignores it.
+     */
+    accessFor(experienceId) {
+        return { executionId: `${this.streamPrefix}${experienceId}`, workflowId: this.workflowId };
+    }
+    /**
+     * Classify a read failure of `experienceId` with this lineage's `confirmErased` hook: a typed
+     * {@link LineErasedError} (confirmed) or {@link LineUnreadableError}, or `undefined` when `err` is
+     * not an unreadable-line failure. Readers built over this lineage (the change feed) use it.
+     */
+    block(experienceId, err) {
+        return classifyLineFailure(experienceId, err, this.confirmErased);
+    }
+    /** Every record of a line; an unreadable line THROWS a {@link LineBlockedError}, anything else propagates. */
+    async readLine(experienceId) {
+        try {
+            return await this.events.read(experienceId);
+        }
+        catch (err) {
+            throw (await this.block(experienceId, err)) ?? err;
+        }
+    }
+    async confirms(experienceId) {
+        if (this.confirmErased === undefined)
+            return false;
+        try {
+            return (await this.confirmErased(experienceId)) === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * A write step failed with `err`: a typed refusal when the line is (now) unreadable, else rethrow.
+     * The re-read catches a key destroyed between `state()` and the append, whose own error is untyped.
+     */
+    async failedWrite(experienceId, err) {
+        const b = await this.block(experienceId, err);
+        if (b !== undefined)
+            return blocked(b);
+        const after = await this.state(experienceId).catch(() => undefined);
+        if (after !== undefined && !after.ok && isBlockedRefusal(after))
+            return after;
+        throw err;
+    }
+    /** The read policy bound at construction (empty when none); readers built over this lineage inherit it. */
+    get readPolicy() {
+        return this.policy;
+    }
+    /**
+     * Whether `other` is this lineage's own store, or may write under a stream prefix that overlaps its
+     * own (`a.startsWith(b) || b.startsWith(a)`: `x:` and `x:y:` collide). A `SeenLog` refuses such a
+     * store: a viewer's record must never share streams with the line it describes.
+     *
+     * FAIL-CLOSED: the vetted store's `streamPrefix` must be readable (the package's prefixed stores
+     * and `InMemoryLineageStore` are). A decorator that HIDES `streamPrefix` cannot be told apart from a
+     * colliding store, so it is refused: re-expose `streamPrefix` on the wrapper (copied from the inner
+     * store) if it is legitimate. The reverse is a documented limit: if THIS lineage's store is such a
+     * wrapper its prefix is assumed to be the default (`LINEAGE_STREAM_PREFIX`).
+     */
+    sharesStreamsWith(other) {
+        if (other === this.events)
+            return true;
+        const prefixOf = (s) => {
+            const p = s.streamPrefix;
+            if (typeof p === "string" && p.length > 0)
+                return p;
+            return s instanceof InMemoryLineageStore ? null : undefined; // null: isolated by identity
+        };
+        // `other` is the store being vetted: with no readable prefix it cannot be proven disjoint, so it
+        // is refused. This lineage's OWN store may be a wrapper that hides its prefix (a counting or
+        // tracing decorator): it is assumed to use the package default.
+        const b = prefixOf(other);
+        if (b === undefined)
+            return true;
+        const a = prefixOf(this.events) ?? LINEAGE_STREAM_PREFIX;
+        if (a === null || b === null)
+            return false; // a distinct in-memory object shares nothing
+        return a.startsWith(b) || b.startsWith(a);
+    }
+    /**
+     * Call `visit` with every content address any version of any line cites (artifacts, op payloads,
+     * anything stored as a content ref in an event), CONSERVATIVELY: any `__loomContent` string found
+     * anywhere in a payload counts, claim-check envelopes included. This is the lineage's half of the
+     * root set a content collector marks. One line is held in memory at a time. Throws if the store
+     * cannot enumerate its lines (`listStreams`): a collector must refuse then, never guess.
+     */
+    async forEachContentRef(visit) {
+        if (this.events.listStreams === undefined)
+            throw new Error("Lineage.forEachContentRef: the LineageStore cannot enumerate its lines");
+        for await (const id of this.events.listStreams()) {
+            let records;
+            try {
+                records = await this.readLine(id);
+            }
+            catch (err) {
+                if (err instanceof LineErasedError)
+                    continue; // confirmed erased: no roots, its blobs are reclaimable
+                throw err; // unconfirmed: refuse rather than guess
+            }
+            for (const rec of records)
+                walkContentRefs(rec.payload, visit);
+        }
+    }
+    /**
+     * U17 — the content addresses a collector must KEEP, as the `roots` of loom's `sweepUnpinnedContent`:
+     * for every line, the artifact of each version `policy` retains (`retainedVersions`: the newest N,
+     * the head, the promoted version, the genesis, every fork's source) plus every OTHER content ref the
+     * line's events cite (anything an op carries) plus every content ref found INSIDE a retained
+     * artifact's own bytes (a node whose props hold a media ref: the sweep does not read blobs, so
+     * nothing else would root it). The artifact ref of a version the policy does not keep is
+     * deliberately absent, so that blob becomes reclaimable.
+     *
+     * USE IT INSTEAD OF scanning the lineage's streams, never as well: a scanned stream pins every
+     * version's artifact for ever (a bare ref is load-bearing to loom's sweep), so pass the lineage's
+     * `LineageStore` to neither `eventStores` nor `snapshotStores`. Mind the consequence: a reclaimed
+     * version's event stays in the log, `get` of it reports the missing artifact, and `verify` of a line
+     * that has had versions reclaimed reports them (and the versions derived from them) until the line
+     * is verified from a retained checkpoint. Reclaim only versions nobody needs to re-open.
+     *
+     * THE ROOT SET MUST BE COMPLETE. With `reclaimOrphans: { completeScan: true }` loom erases every
+     * blob in the store that no root names. The lineage is only ONE user of its content store: pass
+     * the others through `extra` (a {@link SeenLog} sharing the store: `collectSeenRoots(log)`), and
+     * add any other lineage's `pins()` and loom's own execution scan to the same `roots`. A
+     * version a viewer's recorded view still names is kept via `extra.keepVersions`.
+     *
+     * RACES. A promote, a branch (and a seen-log record) TOUCH the artifact they newly cite
+     * (`ContentStore.touch`, SPI 1.4.0, ADR 0055 D6 amendment 2), so a sweep whose roots were computed
+     * a moment earlier still refuses to delete it. That also covers a fork made between this method's
+     * two passes. It needs a store with `touch`; loom's sweep refuses to erase through one without it.
+     *
+     * COST. Linear in the number of RETAINED, DISTINCT artifacts, and each one is read in full: the
+     * refs a version cites (media, blobs) live only inside its artifact's bytes, and neither the version
+     * event nor the store records which artifacts hold any, so there is nothing to skip on without
+     * reading. The reads are bounded, not avoided: a retention policy that keeps fewer versions reads
+     * fewer artifacts, artifacts shared by versions or forks are read once per call, and `extra.concurrency`
+     * sets how many of a line are in flight. Run it from the collector, not on a request path. (Skipping
+     * ref-free artifacts would need a "cites refs" flag stamped on the version event at write time: a
+     * lineage event-schema change, not done here.)
+     *
+     * Two passes, one line in memory at a time. Throws if the store cannot enumerate its lines, if
+     * any line fails to fold, if a retained artifact cannot be read for a reason other than being
+     * already gone, or on a malformed policy (a collector must refuse, never guess).
+     */
+    async *pins(policy = {}, extra = {}) {
+        validateRetentionPolicy(policy);
+        const concurrency = extra.concurrency ?? 8;
+        if (!Number.isInteger(concurrency) || concurrency < 1)
+            throw new Error("Lineage.pins: concurrency must be a positive integer");
+        if (this.events.listStreams === undefined)
+            throw new Error("Lineage.pins: the LineageStore cannot enumerate its lines");
+        // Pass 1: the versions that must outlive their referrers: other lines' forks, and `extra`.
+        const kept = new Map();
+        const addKept = (experienceId, versionHash) => {
+            const set = kept.get(experienceId) ?? new Set();
+            kept.set(experienceId, set);
+            set.add(versionHash);
+        };
+        for (const v of extra.keepVersions ?? [])
+            addKept(v.experienceId, v.versionHash);
+        for await (const id of this.events.listStreams()) {
+            let records1;
+            try {
+                records1 = await this.readLine(id);
+            }
+            catch (err) {
+                if (err instanceof LineErasedError)
+                    continue; // confirmed erased: contributes nothing
+                throw err; // unconfirmed: refuse rather than guess
+            }
+            const fold = foldLineage(id, records1);
+            if (!fold.ok)
+                throw new Error(`Lineage.pins: "${id}" does not fold: ${fold.finding.message}`);
+            for (const v of fold.state.versions.values())
+                if (v.from !== undefined)
+                    addKept(v.from.experienceId, v.from.versionHash);
+        }
+        // Pass 2: the roots.
+        const yielded = new Set();
+        const walked = new Set();
+        const pending = [];
+        const emit = (a) => {
+            if (yielded.has(a))
+                return;
+            yielded.add(a);
+            pending.push(a);
+        };
+        for await (const id of this.events.listStreams()) {
+            let records;
+            try {
+                records = await this.readLine(id);
+            }
+            catch (err) {
+                if (err instanceof LineErasedError)
+                    continue;
+                throw err;
+            }
+            const fold = foldLineage(id, records);
+            if (!fold.ok)
+                throw new Error(`Lineage.pins: "${id}" does not fold: ${fold.finding.message}`);
+            const { keep } = retainedVersions(fold.state, policy, kept.get(id));
+            // This line's roots are gathered locally and emitted once its artifacts read. If its blobs turn
+            // out to be confirmed erased (events readable, blobs gone), only its OWN version artifacts are
+            // dropped (they are the erased ciphertext, reclaimable by design); every other address its
+            // plain events cite (a shared blob an op points at) stays rooted, which is the conservative side.
+            const lineRoots = [];
+            const ownArtifacts = new Set();
+            for (const rec of records) {
+                const p = rec.payload;
+                // The artifact ref of a version event is pinned only if its version is retained.
+                const artifact = typeof p?.ref?.__loomContent === "string" ? p.ref.__loomContent : undefined;
+                if (artifact !== undefined)
+                    ownArtifacts.add(artifact);
+                // (a PROMOTED event cites the same artifact; it counts as a citation of that version too)
+                const droppedVersion = typeof p?.versionHash === "string" && !keep.has(p.versionHash);
+                walkContentRefs(rec.payload, (a) => {
+                    if (a === artifact && droppedVersion)
+                        return;
+                    lineRoots.push(a);
+                });
+            }
+            // Refs that live only inside a retained artifact's bytes. Artifacts are content-addressed, so
+            // versions (and forks) that share an artifact are read ONCE per call; a line's reads run with
+            // bounded concurrency and any failure but "missing" throws before this line yields anything.
+            const toWalk = [];
+            for (const h of keep) {
+                const v = fold.state.versions.get(h);
+                if (v === undefined)
+                    continue;
+                const ref = v.ref;
+                // Marked walked only once this line's reads succeed (below): a line skipped as erased must not
+                // stop a later line that cites the same address from walking it.
+                if (walked.has(ref.__loomContent) ||
+                    toWalk.some((r) => r.__loomContent === ref.__loomContent))
+                    continue;
+                toWalk.push(ref);
+            }
+            let arts;
+            try {
+                arts = await mapLimit(toWalk, concurrency, async (ref) => {
+                    let art;
+                    try {
+                        art = await getExperience(this.content, ref, this.accessFor(id));
+                    }
+                    catch (err) {
+                        throw (await this.block(id, err)) ?? err;
+                    }
+                    if (art.ok)
+                        return art.experience;
+                    if (art.finding.code === "artifact-missing")
+                        return undefined; // already gone: nothing inside to root
+                    throw new Error(`Lineage.pins: "${id}" artifact ${ref.__loomContent}: ${art.finding.message}`);
+                });
+            }
+            catch (err) {
+                if (!(err instanceof LineErasedError))
+                    throw err;
+                // Confirmed erased: drop this line's own artifacts, keep what its events cite elsewhere.
+                for (const a of lineRoots)
+                    if (!ownArtifacts.has(a))
+                        emit(a);
+                while (pending.length > 0)
+                    yield pending.shift();
+                continue;
+            }
+            for (const ref of toWalk)
+                walked.add(ref.__loomContent);
+            for (const a of lineRoots)
+                emit(a);
+            for (const exp of arts)
+                if (exp !== undefined)
+                    walkContentRefs(exp, emit);
+            while (pending.length > 0)
+                yield pending.shift();
+        }
+        if (extra.keepAddresses !== undefined)
+            for await (const a of extra.keepAddresses) {
+                emit(a);
+                while (pending.length > 0)
+                    yield pending.shift();
+            }
+    }
+    /**
+     * Tell the content store that `versionHashes` of `experienceId` were JUST re-cited (by a promote,
+     * a branch, a recorded view): `ContentStore.touch` on their artifacts, so a collector's
+     * conditional delete spares them (loom ADR 0055 D6 amendment 2). A store without `touch` is
+     * left alone (loom's sweep will not erase through one). Refuses when an artifact is already gone.
+     */
+    async cite(experienceId, versionHashes) {
+        const touch = this.content.touch;
+        if (touch === undefined)
+            return { ok: true, value: undefined };
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        const refs = [];
+        for (const h of versionHashes) {
+            const v = s.value.versions.get(h);
+            if (v === undefined)
+                return refused("version-unknown", `"${h}" is not a version of "${experienceId}"`);
+            refs.push(v.ref.__loomContent);
+        }
+        const missing = await touch.call(this.content, refs);
+        if (missing.length > 0)
+            return refused("artifact-missing", `no content at ${missing[0]} (already reclaimed)`);
+        return { ok: true, value: undefined };
+    }
+    // ── reads ───────────────────────────────────────────────────────────────────
+    /** The folded state of a line (empty state for an unknown one). A malformed log is a finding. */
+    async state(experienceId) {
+        let records;
+        try {
+            records = await this.readLine(experienceId);
+        }
+        catch (err) {
+            if (err instanceof LineErasedError || err instanceof LineUnreadableError)
+                return blocked(err);
+            throw err;
+        }
+        const fold = foldLineage(experienceId, records);
+        return fold.ok ? { ok: true, value: fold.state } : fromFinding(fold.finding);
+    }
+    /** The latest version's hash, or null for a line with no version. */
+    async head(experienceId) {
+        const s = await this.state(experienceId);
+        return s.ok ? { ok: true, value: s.value.head } : s;
+    }
+    /** Every version, oldest first. */
+    async versions(experienceId) {
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        return {
+            ok: true,
+            value: s.value.order.map((h) => s.value.versions.get(h)),
+        };
+    }
+    /**
+     * `from` (default the head) and its ancestors WITHIN this line, newest first, following
+     * `parents`. A branch's first version stops the walk (its parent is in another line; see
+     * `VersionRecord.from`). Iterative with a visited set: a forged cycle cannot loop it.
+     */
+    async walk(experienceId, from) {
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        const start = from ?? s.value.head;
+        if (start === null)
+            return { ok: true, value: [] };
+        if (!s.value.versions.has(start))
+            return refused("version-unknown", `"${start}" is not a version of "${experienceId}"`);
+        const out = [];
+        const seen = new Set();
+        const stack = [start];
+        for (let h = stack.pop(); h !== undefined; h = stack.pop()) {
+            const v = s.value.versions.get(h);
+            if (v === undefined || seen.has(h))
+                continue;
+            seen.add(h);
+            out.push(v);
+            for (let i = v.parents.length - 1; i >= 0; i--)
+                stack.push(v.parents[i]);
+        }
+        return { ok: true, value: out };
+    }
+    /** One version's artifact, hash-verified (`getExperience`). */
+    async get(experienceId, versionHash) {
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        return this.load(s.value, versionHash);
+    }
+    /** The latest version's artifact. */
+    async resolveLatest(experienceId) {
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        if (s.value.head === null)
+            return refused("lineage-empty", `"${experienceId}" has no versions`);
+        return this.load(s.value, s.value.head);
+    }
+    /** The promoted (shown) version's artifact, or refused when nothing is promoted. */
+    async resolvePromoted(experienceId) {
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        if (s.value.promoted === null)
+            return refused("nothing-promoted", `"${experienceId}" has no promoted version`);
+        return this.load(s.value, s.value.promoted);
+    }
+    async load(state, versionHash) {
+        const v = state.versions.get(versionHash);
+        if (v === undefined)
+            return refused("version-unknown", `"${versionHash}" is not a version of "${state.experienceId}"`);
+        let r;
+        try {
+            r = await getExperience(this.content, v.ref, this.accessFor(state.experienceId));
+        }
+        catch (err) {
+            const b = await this.block(state.experienceId, err);
+            if (b !== undefined)
+                return blocked(b);
+            throw err;
+        }
+        if (!r.ok)
+            return fromFinding(r.finding);
+        if (r.experience.versionHash !== versionHash ||
+            r.experience.experienceId !== state.experienceId)
+            return refused("artifact-mismatch", `the content at ${v.ref.__loomContent} is not version ${versionHash} of "${state.experienceId}"`);
+        return { ok: true, value: r.experience };
+    }
+    // ── provenance (U12) ────────────────────────────────────────────────────────
+    /**
+     * The per-node ledger of version `versionHash` (default the head): which recorded op created and
+     * last changed each node, derived from the log alone (no artifact is read, nothing is stored).
+     * A revert has the ledger of the version it restores; a branch starts from its source version's.
+     * Bounded: a chain of reverts or branches deeper than `MAX_VERIFY_DEPTH` ends in an unknown
+     * origin rather than recursing without limit.
+     */
+    async provenance(experienceId, versionHash) {
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        const target = versionHash ?? s.value.head;
+        if (target === null)
+            return refused("lineage-empty", `"${experienceId}" has no versions`);
+        if (!s.value.versions.has(target))
+            return refused("version-unknown", `"${target}" is not a version of "${experienceId}"`);
+        return { ok: true, value: await this.ledgerAt(s.value, target, 0) };
+    }
+    async ledgerAt(state, target, depth) {
+        const unknown = { ...emptyLedger(null), truncated: true };
+        if (depth > MAX_VERIFY_DEPTH)
+            return unknown;
+        const chain = [];
+        const seen = new Set();
+        let base = unknown;
+        for (let h = target; h !== undefined;) {
+            const v = state.versions.get(h);
+            if (v === undefined || seen.has(h))
+                break;
+            seen.add(h);
+            if (v.kind === "reverted" && v.revertedTo !== undefined) {
+                base = await this.ledgerAt(state, v.revertedTo, depth + 1);
+                break;
+            }
+            if (v.kind === "branched" && v.from !== undefined) {
+                const src = await this.state(v.from.experienceId);
+                base =
+                    src.ok && src.value.versions.has(v.from.versionHash)
+                        ? await this.ledgerAt(src.value, v.from.versionHash, depth + 1)
+                        : unknown;
+                break;
+            }
+            if (v.parents.length === 0) {
+                base = emptyLedger({ versionHash: v.versionHash, at: v.at, by: v.by });
+                chain.push(v);
+                break;
+            }
+            chain.push(v);
+            h = v.parents[0];
+        }
+        return foldProvenance(base, chain.reverse());
+    }
+    /**
+     * Why is `nodeId` in version `versionHash` (default the head), FOR `viewer`? The ledger of that
+     * version read through core's `explainNode`: unknown, restricted and unreadable all answer the
+     * same bare `{ available: false }`. The creating version's summary and the request that prompted
+     * it are shown only when the viewer may see the strictest class of the viewed version, of the
+     * version that wrote them, and of what the planner read (`summaryClass`); a version that cannot be
+     * read counts as `secret`. Performs no authorization: `viewer` is the host's claim.
+     */
+    async explain(experienceId, nodeId, opts = {}) {
+        // The bound policy applies; a per-call value can only add to it.
+        const policy = mergeReadPolicy(this.policy, opts);
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        const target = opts.versionHash ?? s.value.head;
+        if (target === null)
+            return refused("lineage-empty", `"${experienceId}" has no versions`);
+        const exp = await this.load(s.value, target);
+        if (!exp.ok)
+            return exp;
+        const ledger = await this.ledgerAt(s.value, target, 0);
+        const viewOpts = {
+            ledger,
+            ...(opts.viewer !== undefined && { viewer: opts.viewer }),
+            ...(opts.audience !== undefined && { audience: opts.audience }),
+            ...(policy.projections !== undefined && { projections: policy.projections }),
+            ...(policy.hydrationProjectionId !== undefined && {
+                hydrationProjectionId: policy.hydrationProjectionId,
+            }),
+            ...(policy.declaredToolClasses !== undefined && {
+                declaredToolClasses: policy.declaredToolClasses,
+            }),
+            ...(policy.undeclared !== undefined && { undeclared: policy.undeclared }),
+        };
+        // Ask first with no notes: an unknown, hidden or unreadable node answers `{ available: false }`
+        // HERE, before the writer is loaded, so the I/O a probe costs is the same for all three (a
+        // hidden node must not be told apart from an unknown id by how many blobs a call fetched).
+        const first = explainNode(exp.value, nodeId, viewOpts);
+        if (!first.available)
+            return { ok: true, value: first };
+        const entry = ledger.nodes.get(nodeId)?.created;
+        const wrote = entry?.versionHash ?? ledger.origin?.versionHash;
+        if (wrote === undefined)
+            return { ok: true, value: first };
+        const notes = new Map();
+        let extraFloor;
+        // The writer may live on ANOTHER line (a branch's ledger starts from its source's): resolve it
+        // across lines, bounded. Unresolvable = fail closed (the text it wrote cannot be classed).
+        const found = await this.findVersion(s.value, wrote);
+        if (found === undefined)
+            extraFloor = "secret";
+        else {
+            notes.set(wrote, {
+                ...(found.record.summary !== undefined && { summary: found.record.summary }),
+                ...(found.record.summaryClass !== undefined && {
+                    summaryClass: found.record.summaryClass,
+                }),
+            });
+            if (found.record.summary !== undefined || entry?.prompt !== undefined) {
+                const art = await this.load(found.state, wrote);
+                extraFloor = art.ok
+                    ? experienceClassFloor(art.value, policy.projections, policy.declaredToolClasses, policy.undeclared)
+                    : "secret";
+            }
+        }
+        return {
+            ok: true,
+            value: explainNode(exp.value, nodeId, {
+                ...viewOpts,
+                notes,
+                ...(extraFloor !== undefined && { extraFloor }),
+            }),
+        };
+    }
+    /**
+     * The line state and record of version `hash`, on this line or on a line it was branched from
+     * (breadth-first through `branched` versions, at most `MAX_VERIFY_DEPTH` lines, each visited once).
+     */
+    async findVersion(state, hash) {
+        const visited = new Set([state.experienceId]);
+        const queue = [state];
+        for (let i = 0; i < queue.length; i++) {
+            const st = queue[i];
+            const record = st.versions.get(hash);
+            if (record !== undefined)
+                return { state: st, record };
+            for (const v of st.versions.values()) {
+                const from = v.kind === "branched" ? v.from : undefined;
+                if (from === undefined || visited.has(from.experienceId))
+                    continue;
+                if (visited.size >= MAX_VERIFY_DEPTH)
+                    return undefined;
+                visited.add(from.experienceId);
+                const src = await this.state(from.experienceId);
+                if (src.ok)
+                    queue.push(src.value);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Several versions' artifacts from ONE fold of the line (`get` refolds the whole log per call).
+     * A version that is unknown or cannot be read maps to `undefined`.
+     */
+    async getMany(experienceId, versionHashes) {
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        const out = new Map();
+        for (const h of new Set(versionHashes)) {
+            const r = await this.load(s.value, h);
+            if (!r.ok && isBlockedRefusal(r))
+                return r;
+            out.set(h, r.ok ? r.value : undefined);
+        }
+        return { ok: true, value: out };
+    }
+    // ── writes ──────────────────────────────────────────────────────────────────
+    /** Begin a line: the genesis artifact becomes its first version. Refused when the line exists. */
+    async start(genesis, by) {
+        if (genesis.parents.length > 0)
+            return refused("genesis-has-parents", "a lineage starts from a parentless artifact");
+        return this.advance({
+            experienceId: genesis.experienceId,
+            expectedHead: null,
+            artifact: genesis,
+            ops: [],
+            by,
+        });
+    }
+    /**
+     * Advance the head to `artifact`, which `ops` produce from the version `expectedHead`.
+     *
+     * REFUSES, writing nothing, when: `expectedHead` is not the head (`head-moved`, carrying the real
+     * one — the caller re-reads and re-authors; nothing is ever silently overwritten); the artifact
+     * does not name `expectedHead` as its only parent; or replaying `ops` from the parent does not
+     * reproduce the artifact's content address (`ops-artifact-mismatch`), including an op the host
+     * will not allow or one declared against a different base. `ops` is empty only for the first
+     * version of a line. The artifact may arrive unsealed.
+     */
+    async advance(input) {
+        const { experienceId, expectedHead, artifact, ops, by } = input;
+        const badBy = provenanceRefusal(by, ops);
+        if (badBy !== undefined)
+            return badBy;
+        const summary = boundSummary(input.summary);
+        if (input.summaryClass !== undefined && !Sensitivity.safeParse(input.summaryClass).success)
+            return refused("summary-class-invalid", "summaryClass is not a known data class");
+        const applyOpts = { allowDeclassify: input.allowDeclassify === true };
+        return this.commit(experienceId, expectedHead, async (_state, parent) => {
+            if (artifact.experienceId !== experienceId)
+                return refused("artifact-wrong-line", `the artifact is "${artifact.experienceId}", not "${experienceId}"`);
+            const want = expectedHead === null ? [] : [expectedHead];
+            if (!sameSet(artifact.parents, want))
+                return refused("artifact-parent-mismatch", `the artifact's parents ${JSON.stringify(artifact.parents)} are not ${JSON.stringify(want)}`);
+            let sealed;
+            try {
+                sealed = seal(artifact);
+            }
+            catch (err) {
+                return refused("artifact-unhashable", `the artifact cannot be hashed: ${msg(err)}`);
+            }
+            if (artifact.versionHash !== "" && artifact.versionHash !== sealed.versionHash)
+                return refused("artifact-tampered", `versionHash ${artifact.versionHash} does not match the artifact (${sealed.versionHash})`);
+            const check = parent === null ? checkGenesis(ops) : checkOps(parent, ops, sealed.versionHash, applyOpts);
+            if (check !== undefined)
+                return fromFinding(check);
+            // `meta` is not part of the address and the caller's claim about it is unverified, so the
+            // stored artifact's authorship is derived from the recorded provenance and the clock (as a
+            // revert's is), never taken from the argument.
+            const stored = {
+                ...sealed,
+                meta: { author: authorOf(by), createdAt: this.now(), sourceKind: "compose" },
+            };
+            return {
+                ok: true,
+                value: {
+                    artifact: stored,
+                    type: EXPERIENCE_COMPOSED,
+                    payload: (ref) => ({
+                        experienceId,
+                        versionHash: sealed.versionHash,
+                        ref,
+                        parents: sealed.parents,
+                        ops,
+                        by,
+                        ...(summary !== undefined && { summary }),
+                        ...(input.summaryClass !== undefined && { summaryClass: input.summaryClass }),
+                    }),
+                },
+            };
+        });
+    }
+    /**
+     * The concurrent-author path: fold `ops` onto the head yourself. The first op is applied with
+     * `applyAt`, so one that declares a `baseVersion` other than the head is refused
+     * (`stale-base-version`) instead of landing on a surface its author never saw; then the result is
+     * committed through {@link advance}'s verification, so what is recorded is exactly what replays.
+     */
+    async compose(input) {
+        const { experienceId, expectedHead, ops, by } = input;
+        const badBy = provenanceRefusal(by, ops);
+        if (badBy !== undefined)
+            return badBy;
+        const applyOpts = { allowDeclassify: input.allowDeclassify === true };
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        if (s.value.head !== expectedHead)
+            return { ok: false, refusal: { kind: "head-moved", expectedHead, actualHead: s.value.head } };
+        const parent = await this.load(s.value, expectedHead);
+        if (!parent.ok)
+            return parent;
+        if (ops.length === 0)
+            return refused("empty-ops", "a composition needs at least one op");
+        const first = ops[0];
+        let cur = applyAt(parent.value, first.op, {
+            ...applyOpts,
+            ...(first.baseVersion !== undefined && { baseVersion: first.baseVersion }),
+        });
+        for (let i = 1; cur.ok && i < ops.length; i++)
+            cur = apply(cur.value, ops[i].op, applyOpts);
+        if (!cur.ok)
+            return fromFinding(cur.finding);
+        return this.advance({
+            experienceId,
+            expectedHead,
+            artifact: cur.value,
+            ops,
+            by,
+            allowDeclassify: input.allowDeclassify === true,
+            ...(input.summary !== undefined && { summary: input.summary }),
+            ...(input.summaryClass !== undefined && { summaryClass: input.summaryClass }),
+        });
+    }
+    /**
+     * Restore the content of version `to` as a NEW version on top of `expectedHead` — history is
+     * never rewritten, and the revert itself can be reverted. Sticky classes the line learned since
+     * `to` are carried forward (never lowered; see derive.ts). `to` may be any version of the line
+     * except the head (which would restore nothing).
+     */
+    async revert(input) {
+        const { experienceId, expectedHead, to, by } = input;
+        const badBy = provenanceRefusal(by);
+        if (badBy !== undefined)
+            return badBy;
+        return this.commit(experienceId, expectedHead, async (state, head) => {
+            if (head === null)
+                return refused("lineage-empty", `"${experienceId}" has no versions`);
+            if (to === expectedHead)
+                return refused("revert-to-head", "the head is already that version");
+            const target = await this.load(state, to);
+            if (!target.ok)
+                return target;
+            const sealed = sealed_(revertArtifact(head, target.value, { by, at: this.now() }));
+            if (!sealed.ok)
+                return sealed;
+            return {
+                ok: true,
+                value: {
+                    artifact: sealed.value,
+                    type: EXPERIENCE_REVERTED,
+                    payload: (ref) => ({
+                        experienceId,
+                        versionHash: sealed.value.versionHash,
+                        ref,
+                        parents: sealed.value.parents,
+                        revertedTo: to,
+                        by,
+                    }),
+                },
+            };
+        });
+    }
+    /** Undo: revert to the head's parent, as a new version. Redo is `revert` to the hash you left. */
+    async undo(input) {
+        const s = await this.state(input.experienceId);
+        if (!s.ok)
+            return s;
+        const headRec = s.value.head === null ? undefined : s.value.versions.get(s.value.head);
+        if (s.value.head !== input.expectedHead)
+            return {
+                ok: false,
+                refusal: { kind: "head-moved", expectedHead: input.expectedHead, actualHead: s.value.head },
+            };
+        const parent = headRec?.parents[0];
+        if (headRec === undefined || parent === undefined || !s.value.versions.has(parent))
+            return refused("nothing-to-undo", "the head has no earlier version in this line");
+        return this.revert({ ...input, to: parent });
+    }
+    /**
+     * Fork version `from` of one line into a NEW line `experienceId`. The new line's first version
+     * has `from` as its (cross-line) parent and carries the sticky classes of the source line's head
+     * at the fork, so branching an old version never launders a class the source learned later.
+     * Refused when the new line already exists.
+     */
+    async branch(input) {
+        const { from, experienceId, by } = input;
+        const badBy = provenanceRefusal(by);
+        if (badBy !== undefined)
+            return badBy;
+        if (experienceId === from.experienceId)
+            return refused("branch-same-line", "a branch is a NEW line; use revert within one");
+        const src = await this.state(from.experienceId);
+        if (!src.ok)
+            return src;
+        if (src.value.head === null)
+            return refused("lineage-empty", `"${from.experienceId}" has no versions`);
+        const carriedFrom = src.value.head;
+        const [source, carried] = await Promise.all([
+            this.load(src.value, from.versionHash),
+            this.load(src.value, carriedFrom),
+        ]);
+        if (!source.ok)
+            return source;
+        if (!carried.ok)
+            return carried;
+        // The fork records its source by hash with no `put` of that artifact: touch the source (and the
+        // head whose classes it carries) BEFORE the append, so a concurrent sweep spares them.
+        const cited = await this.cite(from.experienceId, [from.versionHash, carriedFrom]);
+        if (!cited.ok)
+            return cited;
+        const committed = await this.commit(experienceId, null, async () => {
+            const sealed = sealed_(branchArtifact(source.value, carried.value, experienceId, { by, at: this.now() }));
+            if (!sealed.ok)
+                return sealed;
+            return {
+                ok: true,
+                value: {
+                    artifact: sealed.value,
+                    type: EXPERIENCE_BRANCHED,
+                    payload: (ref) => ({
+                        experienceId,
+                        versionHash: sealed.value.versionHash,
+                        ref,
+                        parents: sealed.value.parents,
+                        from,
+                        carriedFrom,
+                        by,
+                    }),
+                },
+            };
+        });
+        if (committed.ok)
+            await this.cite(from.experienceId, [from.versionHash, carriedFrom]).catch(() => undefined);
+        return committed;
+    }
+    /**
+     * Mark version `versionHash` as the one the app SHOWS (an agent's ops yield a new version; showing
+     * it is this separate act). Compare-and-set on the promoted pointer: `expectedPromoted` is what
+     * the caller saw (null = nothing promoted yet).
+     */
+    async promote(input) {
+        const { experienceId, versionHash, expectedPromoted, by } = input;
+        const badBy = provenanceRefusal(by);
+        if (badBy !== undefined)
+            return badBy;
+        for (let attempt = 0; attempt < MAX_TIP_RETRIES; attempt++) {
+            const s = await this.state(experienceId);
+            if (!s.ok)
+                return s;
+            if (s.value.promoted !== expectedPromoted)
+                return {
+                    ok: false,
+                    refusal: { kind: "promoted-moved", expectedPromoted, actualPromoted: s.value.promoted },
+                };
+            const art = await this.load(s.value, versionHash);
+            if (!art.ok)
+                return art;
+            const v = s.value.versions.get(versionHash);
+            const promotedPayload = { ref: v.ref, experienceId, versionHash, by };
+            const badPayload = payloadRefusal(EXPERIENCE_PROMOTED, promotedPayload);
+            if (badPayload !== undefined)
+                return refused(badPayload.code, badPayload.message);
+            // The promotion cites an artifact that already exists, with no `put`: touch it BEFORE the
+            // append so a sweep that marked earlier cannot delete it, and AFTER to extend the window.
+            const cited = await this.cite(experienceId, [versionHash]);
+            if (!cited.ok)
+                return cited;
+            let out;
+            try {
+                out = await this.events.append(experienceId, s.value.sequence, {
+                    type: EXPERIENCE_PROMOTED,
+                    at: this.now(),
+                    payload: promotedPayload,
+                });
+            }
+            catch (err) {
+                return this.failedWrite(experienceId, err);
+            }
+            if (out.ok) {
+                await this.cite(experienceId, [versionHash]).catch(() => undefined); // best effort: the write is durable
+                return { ok: true, value: { promoted: versionHash, sequence: out.sequence } };
+            }
+        }
+        return refused("lineage-contended", `could not append to "${experienceId}" after ${MAX_TIP_RETRIES} attempts`);
+    }
+    // ── verification ────────────────────────────────────────────────────────────
+    /**
+     * Rebuild a whole line from its log and compare it to what is stored — the consumer of
+     * `EXPERIENCE_COMPOSED`. Starting from the genesis artifact (attested by its address alone: there
+     * is nothing before it to replay from), each version is REBUILT, never read back from its blob:
+     * a composed version by replaying its ops on the rebuilt parent, a revert or branch by recomputing
+     * it from the rebuilt artifacts it names. The rebuilt content address must equal the logged one
+     * and the stored blob must hash to it. Returns every finding; `[]` = the line is consistent.
+     *
+     * A branch is only as sound as its source: `verify` also verifies the source line up to the
+     * version the fork carried classes from (`carriedFrom`), recursively (a visited set and a depth
+     * bound stop a forged cycle), and reports what it finds on the branch, prefixed with the source
+     * line; `carriedFrom` must be the forked version or a descendant of it on the source line. A
+     * version whose parent could not be rebuilt is reported, not skipped silently. Ops replay with
+     * `declassify*` ALLOWED: this checks that addresses reproduce, and the write path is the gate.
+     */
+    async verify(experienceId) {
+        return this.verifyLine(experienceId, null, new Set(), 0);
+    }
+    /** Verify `experienceId` from its start through version `upTo` (null = the whole line). */
+    async verifyLine(experienceId, upTo, visited, depth) {
+        const key = `${experienceId}@${upTo ?? ""}`;
+        if (visited.has(key))
+            return [];
+        visited.add(key);
+        const s = await this.state(experienceId);
+        if (!s.ok)
+            return [s.refusal.kind === "refused" ? s.refusal.finding : unreachable()];
+        const findings = [];
+        const rebuilt = new Map();
+        const err = (code, message) => findings.push({ code, severity: "error", message });
+        let order = s.value.order;
+        if (upTo !== null) {
+            const at = order.indexOf(upTo);
+            if (at < 0)
+                return [
+                    {
+                        code: "version-unknown",
+                        severity: "error",
+                        message: `"${upTo}" is not a version of "${experienceId}"`,
+                    },
+                ];
+            order = order.slice(0, at + 1);
+        }
+        for (const hash of order) {
+            const v = s.value.versions.get(hash);
+            const stored = await this.load(s.value, hash);
+            if (!stored.ok) {
+                findings.push(stored.refusal.kind === "refused" ? stored.refusal.finding : unreachable());
+                continue;
+            }
+            if (!sameSet(stored.value.parents, v.parents))
+                err("artifact-parent-mismatch", `version ${hash}: the stored artifact's parents differ from the log's`);
+            let derived;
+            if (v.kind === "composed") {
+                const parent = v.parents[0] === undefined ? undefined : rebuilt.get(v.parents[0]);
+                if (v.parents.length === 0) {
+                    if (v.ops.length > 0)
+                        err("ops-on-genesis", `version ${hash}: a genesis records ${v.ops.length} ops`);
+                    derived = stored.value;
+                }
+                else if (parent === undefined) {
+                    err("lineage-parent-unverified", `version ${hash}: its parent could not be rebuilt`);
+                    continue;
+                }
+                else {
+                    // verify replays with declassify allowed (it checks addresses; the write path is the gate),
+                    // so a declassify that reached the log is SURFACED (warn) — a raw append bypasses that gate.
+                    if (recordsDeclassify(v.ops))
+                        findings.push({
+                            code: "declassify-op-present",
+                            severity: "warn",
+                            message: `version ${hash}: records a declassify op — confirm it was authorized when written`,
+                        });
+                    const f = checkOps(parent, v.ops, hash, VERIFY_APPLY);
+                    if (f !== undefined)
+                        err(f.code, `version ${hash}: ${f.message}`);
+                    derived = replayed(parent, v.ops, VERIFY_APPLY);
+                }
+            }
+            else if (v.kind === "reverted") {
+                const head = v.parents[0] === undefined ? undefined : rebuilt.get(v.parents[0]);
+                const target = v.revertedTo === undefined ? undefined : rebuilt.get(v.revertedTo);
+                if (head === undefined || target === undefined) {
+                    err("lineage-parent-unverified", `version ${hash}: the revert's head or target could not be rebuilt`);
+                    continue;
+                }
+                const d = sealed_(revertArtifact(head, target, { by: v.by, at: v.at }));
+                if (!d.ok) {
+                    err("artifact-unhashable", `version ${hash}: cannot recompute the revert`);
+                    continue;
+                }
+                derived = d.value;
+                if (derived.versionHash !== hash)
+                    err("revert-artifact-mismatch", `version ${hash}: recomputing the revert gives ${derived.versionHash}`);
+            }
+            else {
+                const srcState = v.from === undefined ? undefined : await this.state(v.from.experienceId);
+                // The source line's erasure is CONFIRMED (the host's hook), either because it refuses
+                // `line-erased` or because its events were deleted too (the version is simply absent) and the
+                // hook still confirms: the fork cannot be recomputed. Like a genesis it is attested by its
+                // address alone (the stored blob hashed to `hash` when it was loaded above), and the gap is
+                // surfaced as a warning. An UNCONFIRMED unreadable source is an error (below).
+                const srcErased = v.from !== undefined &&
+                    srcState !== undefined &&
+                    (srcState.ok
+                        ? !srcState.value.versions.has(v.from.versionHash) &&
+                            (await this.confirms(v.from.experienceId))
+                        : isErasedRefusal(srcState));
+                if (srcErased) {
+                    findings.push({
+                        code: "branch-source-erased",
+                        severity: "warn",
+                        message: `version ${hash}: the source line "${v.from?.experienceId}" is erased, so this branch is attested by its content address only`,
+                    });
+                    rebuilt.set(hash, stored.value);
+                    continue;
+                }
+                if (srcState !== undefined && !srcState.ok && isBlockedRefusal(srcState)) {
+                    const f = srcState.refusal.kind === "refused" ? srcState.refusal.finding : unreachable();
+                    err(f.code, `version ${hash}: source line "${v.from?.experienceId}" cannot be read and its erasure is not confirmed: ${f.message}`);
+                    continue;
+                }
+                if (v.from === undefined ||
+                    v.carriedFrom === undefined ||
+                    srcState === undefined ||
+                    !srcState.ok) {
+                    err("lineage-parent-unverified", `version ${hash}: the branch's source line could not be read`);
+                    continue;
+                }
+                if (depth >= MAX_VERIFY_DEPTH) {
+                    err("lineage-verify-depth", `version ${hash}: branches nest over ${MAX_VERIFY_DEPTH} lines deep`);
+                    continue;
+                }
+                if (!descendsFrom(srcState.value, v.carriedFrom, v.from.versionHash)) {
+                    err("branch-carried-from-invalid", `version ${hash}: carriedFrom ${v.carriedFrom} is neither ${v.from.versionHash} nor a descendant of it on "${v.from.experienceId}"`);
+                    continue;
+                }
+                for (const f of await this.verifyLine(v.from.experienceId, v.carriedFrom, visited, depth + 1))
+                    err(f.code, `version ${hash}: source line "${v.from.experienceId}": ${f.message}`);
+                const [src, carried] = await Promise.all([
+                    this.load(srcState.value, v.from.versionHash),
+                    this.load(srcState.value, v.carriedFrom),
+                ]);
+                if (!src.ok || !carried.ok) {
+                    err("lineage-parent-unverified", `version ${hash}: the branch's source versions could not be loaded`);
+                    continue;
+                }
+                const d = sealed_(branchArtifact(src.value, carried.value, experienceId, { by: v.by, at: v.at }));
+                if (!d.ok) {
+                    err("artifact-unhashable", `version ${hash}: cannot recompute the branch`);
+                    continue;
+                }
+                derived = d.value;
+                if (derived.versionHash !== hash)
+                    err("branch-artifact-mismatch", `version ${hash}: recomputing the branch gives ${derived.versionHash}`);
+            }
+            if (derived !== undefined && derived.versionHash === hash)
+                rebuilt.set(hash, derived);
+            else if (derived === undefined)
+                err("lineage-parent-unverified", `version ${hash}: could not be rebuilt`);
+        }
+        return findings;
+    }
+    // ── internals ───────────────────────────────────────────────────────────────
+    /**
+     * The one write path: check `expectedHead` against the head, let `prepare` verify and build the
+     * version, store its bytes, then append at the log's tip. A lost append re-reads: if the head is
+     * still `expectedHead` (only a promotion slipped in) it retries at the new tip; otherwise it is
+     * `head-moved`. The blob is written BEFORE the event and is content-addressed, so a lost race
+     * leaves an unreferenced, harmless blob — never a log entry without bytes.
+     */
+    async commit(experienceId, expectedHead, prepare) {
+        let s = await this.state(experienceId);
+        if (!s.ok)
+            return s;
+        const moved = (actual) => ({
+            ok: false,
+            refusal: { kind: "head-moved", expectedHead, actualHead: actual },
+        });
+        if (s.value.head !== expectedHead)
+            return moved(s.value.head);
+        let head = null;
+        if (expectedHead !== null) {
+            const loaded = await this.load(s.value, expectedHead);
+            if (!loaded.ok)
+                return loaded;
+            head = loaded.value;
+        }
+        const prepared = await prepare(s.value, head);
+        if (!prepared.ok)
+            return prepared;
+        const { artifact, type, payload } = prepared.value;
+        // The write-side twin of the fold: an event the fold would refuse must never reach the log.
+        const badPayload = payloadRefusal(type, payload({ __loomContent: "sha256:pending" }));
+        if (badPayload !== undefined)
+            return refused(badPayload.code, badPayload.message);
+        // The blob goes in under THIS line's access (never the source line's, for a branch), so erasing
+        // the owner of this line makes it unreadable, and erasing a source line does not touch it.
+        let put;
+        try {
+            put = await putExperience(this.content, artifact, this.accessFor(experienceId));
+        }
+        catch (err) {
+            return this.failedWrite(experienceId, err);
+        }
+        if (!put.ok)
+            return fromFinding(put.finding);
+        for (let attempt = 0; attempt < MAX_TIP_RETRIES; attempt++) {
+            let out;
+            try {
+                out = await this.events.append(experienceId, s.value.sequence, {
+                    type,
+                    at: this.now(),
+                    payload: payload(put.ref),
+                });
+            }
+            catch (err) {
+                return this.failedWrite(experienceId, err);
+            }
+            if (out.ok) {
+                const after = await this.state(experienceId);
+                if (!after.ok)
+                    return after;
+                return {
+                    ok: true,
+                    value: {
+                        experience: put.experience,
+                        version: after.value.versions.get(put.experience.versionHash),
+                    },
+                };
+            }
+            s = await this.state(experienceId);
+            if (!s.ok)
+                return s;
+            if (s.value.head !== expectedHead)
+                return moved(s.value.head);
+        }
+        return refused("lineage-contended", `could not append to "${experienceId}" after ${MAX_TIP_RETRIES} attempts`);
+    }
+}
+/** Why replaying `ops` on `parent` does NOT yield `expectedHash`, or undefined when it does. */
+function checkOps(parent, ops, expectedHash, applyOpts) {
+    const f = (code, message) => ({ code, severity: "error", message });
+    if (ops.length === 0)
+        return f("empty-ops", "a version after the first records at least one op");
+    for (const [i, r] of ops.entries())
+        if (r.baseVersion !== undefined && r.baseVersion !== parent.versionHash)
+            return f("stale-base-version", `op #${i} (${r.op.type}) was authored against ${r.baseVersion} but its parent is ${parent.versionHash}`);
+    const out = replay(parent, ops.map((r) => r.op), applyOpts);
+    if (!out.ok)
+        return f("ops-refused", out.finding.message);
+    const sealed = sealed_(out.value);
+    if (!sealed.ok)
+        return sealed.refusal.kind === "refused" ? sealed.refusal.finding : undefined;
+    if (sealed.value.versionHash !== expectedHash)
+        return f("ops-artifact-mismatch", `replaying the recorded ops from ${parent.versionHash} gives ${sealed.value.versionHash}, not ${expectedHash}: the ops do not produce this artifact`);
+    return undefined;
+}
+function replayed(parent, ops, applyOpts) {
+    const out = replay(parent, ops.map((r) => r.op), applyOpts);
+    if (!out.ok)
+        return undefined;
+    const sealed = sealed_(out.value);
+    return sealed.ok ? sealed.value : undefined;
+}
+/**
+ * `verify` checks ADDRESSES, not authority: the write path (`advance`/`compose`) is where a
+ * `declassify*` op is gated, so a version that is already in the log replays with declassify
+ * allowed. Refusing it here would report a legitimately host-authorized version as `ops-refused`.
+ */
+const VERIFY_APPLY = { allowDeclassify: true, legacyBind: true };
+/** Does any recorded op (or a prompt's materialized ops, nested) declassify? Iterative, bounded. */
+function recordsDeclassify(ops) {
+    const stack = ops.map((r) => r.op);
+    for (let seen = 0; stack.length > 0 && seen < 100_000; seen++) {
+        const op = stack.pop();
+        if (op === null || typeof op !== "object")
+            continue;
+        if (typeof op.type === "string" && op.type.startsWith("declassify"))
+            return true;
+        if (Array.isArray(op.materialized))
+            stack.push(...op.materialized);
+    }
+    return false;
+}
+function checkGenesis(ops) {
+    return ops.length === 0
+        ? undefined
+        : {
+            code: "ops-on-genesis",
+            severity: "error",
+            message: "the first version of a line has no parent to replay ops from; compose on top of it",
+        };
+}
+function sealed_(exp) {
+    try {
+        return { ok: true, value: seal(exp) };
+    }
+    catch (err) {
+        return refused("artifact-unhashable", `the artifact cannot be hashed: ${msg(err)}`);
+    }
+}
+const msg = (err) => (err instanceof Error ? err.message : String(err));
+/** A `Refusal` that is not `refused` cannot come out of a read; keeps the narrowing total. */
+function unreachable() {
+    return {
+        code: "lineage-internal",
+        severity: "error",
+        message: "unexpected refusal kind on a read",
+    };
+}
+//# sourceMappingURL=lineage.js.map