@egildo/provenance 0.0.0-stage → 0.7.0

package/dist/session.js

@@ -0,0 +1,1057 @@
+// A session: roots, every source reachable from them, and the declared edges between them.
+// Rules and states are specs/source-graph-kernel/data-model.md's.
+import { byteOffsets } from "./offsets.js";
+import { hasScheme, resolve } from "./resolvers.js";
+/** The refusal codes the session reads (FIX-003), Cascata's names: the key is there; the place is gone. */
+const EXISTS_CODE = "edit-target-exists";
+const GONE_CODES = new Set(["edit-target-absent", "edit-parent-scalar"]);
+const sameBytes = (a, b) => a.length === b.length && a.every((byte, i) => byte === b[i]);
+/**
+ * Whether two ranges overlap. Empty ranges at one offset do not: they are inserts at the same spot, spliced in
+ * staging order (insert-delete FR-008). An empty range strictly inside another does.
+ */
+const overlaps = (a, b) => a.start < b.end && b.start < a.end;
+/** A writer is still pure, so one function asks its opened document to do an operation, or says the document cannot. */
+function perform(doc, key, operation) {
+    const cannot = (verb) => ({ ok: false, reason: `the writer for ${key} cannot ${verb}: its document has no ${verb}` });
+    if (operation.op === "remove")
+        return doc.remove ? doc.remove(operation.path) : cannot("remove");
+    if (operation.op === "add")
+        return doc.add ? doc.add(operation.path, operation.value) : cannot("add");
+    return doc.write(operation.path, operation.value);
+}
+/** A writer's range outside the bytes it was given is its bug, like an index `byteOffsets` cannot convert. */
+function checkRange(length, start, end, what) {
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end > length) {
+        throw new RangeError(`${what} gave the range ${start}-${end}, outside the ${length} bytes it was given`);
+    }
+}
+/**
+ * The base with every edit spliced in, applied from the end backwards so each range stays valid. `edits`
+ * are in staging order; of several empty-ranged edits at one offset the earlier-staged ends up first in the
+ * text, which is to say it is applied last (FR-008).
+ */
+function splice(base, edits) {
+    let out = base;
+    const backwards = edits.map((edit, order) => ({ edit, order })).sort((a, b) => b.edit.start - a.edit.start || b.edit.end - a.edit.end || b.order - a.order);
+    for (const { edit: e } of backwards) {
+        const next = new Uint8Array(e.start + e.bytes.length + (out.length - e.end));
+        next.set(out.subarray(0, e.start));
+        next.set(e.bytes, e.start);
+        next.set(out.subarray(e.end), e.start + e.bytes.length);
+        out = next;
+    }
+    return out;
+}
+/** Findings per handler and version, shared by every session that uses the handler. */
+const cache = new WeakMap();
+/**
+ * What every open session holds: the handler and version of each source it has analysed, and of
+ * each finding its running piece of work has taken from the cache or made so far. A finding lives
+ * while some open session holds it (specs/held-versions/); `sweep` drops the rest.
+ */
+const open = new Set();
+/**
+ * Drops from the cache of each given handler every version no open session holds. Safe at the end
+ * of any session's piece of work: a session mid-work holds what its piece has met.
+ * ponytail: walks every held source of every open session per sweep; keep a count per version if
+ * a session of many thousands of sources ever makes that cost show.
+ */
+function sweep(handlers) {
+    const held = new Map();
+    for (const holds of open) {
+        for (const [handler, version] of holds()) {
+            const versions = held.get(handler) ?? new Set();
+            held.set(handler, versions.add(version));
+        }
+    }
+    for (const handler of handlers) {
+        const byVersion = cache.get(handler);
+        if (byVersion)
+            for (const version of byVersion.keys())
+                if (!held.get(handler)?.has(version))
+                    byVersion.delete(version);
+    }
+}
+async function sha256(bytes) {
+    // `slice` copies onto a plain ArrayBuffer: digest refuses a view that may be shared memory.
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes.slice()));
+    return Array.from(digest, b => b.toString(16).padStart(2, "0")).join("");
+}
+/** A root-absolute URL path, such as `<base href="/">`'s: a path on the embedder's site, never a directory. */
+const isRooted = (base) => base.startsWith("/") && !base.startsWith("//");
+/**
+ * Joins a relative request to a rooted base the way a browser does, so it resolves as the
+ * root-absolute request that results, which is the embedder's (research.md, Resolution). Any other
+ * request stays as written.
+ */
+function joined(request, base) {
+    if (base === undefined || !isRooted(base) || request === "" || /^[#/]/.test(request) || hasScheme(request))
+        return request;
+    const url = new URL(request, new URL(base, "http://site"));
+    return url.pathname + url.search + url.hash;
+}
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+export async function openSession(options) {
+    const { host, handlers, resolvers = [], writers = [], writable = [] } = options;
+    if (typeof options.entry !== "string" || options.entry === "")
+        throw new TypeError("entry must be a location");
+    const ids = new Map();
+    const nodes = new Map();
+    /** The entry and what the embedder added; no read pass touches these. */
+    const roots = new Set();
+    /** What each label's latest ended read pass recorded. */
+    const passRoots = new Map();
+    /** The open pass per label, by identity, so a newer pass can discard an older one. */
+    const livePasses = new Map();
+    const listeners = new Set();
+    // No call started this work, so a throw has nowhere to go but out: re-rejecting makes it unhandled.
+    const watch = host.watch(locations => void serialize(() => absorb(locations)).catch(error => Promise.reject(error)));
+    let queue = Promise.resolve();
+    let closed = false;
+    /** What the running piece of work has analysed or read from the cache; released when it ends. */
+    const inFlight = [];
+    /** The staged edits, by the source's key. A preview of them is a version like any other. */
+    const staged = new Map();
+    function* holds() {
+        yield* inFlight;
+        for (const [key, staging] of staged) {
+            const handler = staging.preview === undefined ? undefined : handlers.find(h => h.claims(key));
+            if (handler && staging.preview !== undefined)
+                yield [handler, staging.preview];
+        }
+        for (const node of nodes.values()) {
+            if (node.state !== "analysed")
+                continue;
+            const handler = handlers.find(h => h.claims(node.key));
+            if (handler)
+                yield [handler, node.version];
+        }
+    }
+    open.add(holds);
+    /**
+     * Runs session work one piece at a time, so a change batch never interleaves with another.
+     * Work still queued at `close()` never runs. Work that throws leaves the session as it was, and
+     * rejects the returned promise; the queue goes on. The change the work returns is announced only
+     * after the work is kept, so a listener's throw rejects the call and undoes nothing.
+     */
+    function serialize(work) {
+        const next = queue.then(async () => {
+            if (closed)
+                return;
+            const before = {
+                ids: new Map(ids),
+                nodes: new Map(nodes),
+                roots: new Set(roots),
+                passRoots: new Map(passRoots),
+                // `doc` is an opened document, never changed once opened: copying the reference is a copy.
+                staged: new Map([...staged].map(([key, staging]) => [key, { ...staging, edits: staging.edits.map(e => ({ ...e })) }])),
+                // Links are mutated in place when the world changes under them.
+                links: [...nodes.values()].flatMap(node => node.links.map(l => ({ link: l, target: l.target, probes: l.probes }))),
+            };
+            let change;
+            notices.length = 0;
+            writtenKeys.length = 0;
+            try {
+                change = await work();
+            }
+            catch (error) {
+                for (const { link: l, target, probes } of before.links) {
+                    l.target = target;
+                    l.probes = probes;
+                }
+                restore(ids, before.ids);
+                restore(nodes, before.nodes);
+                restore(passRoots, before.passRoots);
+                restore(staged, before.staged);
+                notices.length = 0;
+                for (const key of writtenKeys)
+                    staged.delete(key); // their edits are on disk; the host's change report brings the session up to them
+                writtenKeys.length = 0;
+                roots.clear();
+                for (const key of before.roots)
+                    roots.add(key);
+                throw error;
+            }
+            finally {
+                // After a rollback has restored the nodes, so the versions it went back to are still held.
+                inFlight.length = 0;
+                sweep(handlers);
+            }
+            if (change)
+                emit(change);
+        });
+        queue = next.catch(() => undefined);
+        return next;
+    }
+    function restore(live, saved) {
+        live.clear();
+        for (const [key, value] of saved)
+            live.set(key, value);
+    }
+    const idFor = (key) => {
+        let id = ids.get(key);
+        if (id === undefined)
+            ids.set(key, (id = `s${ids.size + 1}`));
+        return id;
+    };
+    const keyFor = async (location) => (await host.canonicalize(location)) ?? host.paths.resolve(location);
+    /** Resolves a link in place. False means the request makes no edge at all (`data:`, a fragment). */
+    async function link(link) {
+        const found = await resolve(link.lookup, link.base, host, resolvers);
+        if (found === null)
+            return false;
+        if ("external" in found) {
+            link.target = { key: found.external, external: true };
+            link.probes = [];
+        }
+        else {
+            link.target = found.target === undefined ? undefined : { key: found.target, external: false };
+            link.probes = found.probes;
+        }
+        return true;
+    }
+    function baseFor(key, base) {
+        const directory = host.paths.dirname(key);
+        if (base === undefined || isRooted(base))
+            return directory;
+        if (base.startsWith("//"))
+            return `https:${base}`;
+        if (/^https?:/i.test(base))
+            return base;
+        const resolved = host.paths.resolve(directory, base);
+        return base.endsWith("/") ? resolved : host.paths.dirname(resolved);
+    }
+    /** The handler's findings for one version, from the cache or made now; held until the piece of work ends. */
+    function findingsFor(handler, version, text) {
+        let byVersion = cache.get(handler);
+        if (!byVersion)
+            cache.set(handler, (byVersion = new Map()));
+        let findings = byVersion.get(version);
+        if (!findings)
+            byVersion.set(version, (findings = handler.analyze(text)));
+        inFlight.push([handler, version]);
+        return findings;
+    }
+    /** What rebases did to staged edits during the running piece of work, for the change it reports. */
+    const notices = [];
+    /** Sources the running commit has written. A disk write cannot be rolled back, so they stay committed. */
+    const writtenKeys = [];
+    const drained = () => {
+        const edits = notices.splice(0);
+        return edits.length === 0 ? {} : { edits };
+    };
+    /** Every staged edit of a source whose target is gone is conflicted: dropped, and reported. */
+    function conflict(key) {
+        const staging = staged.get(key);
+        if (!staging)
+            return;
+        staged.delete(key);
+        for (const e of staging.edits)
+            notices.push({ source: idFor(key), path: e.path, outcome: "conflicted", reason: "gone" });
+    }
+    /** Moves a source's staged edits onto `bytes`, its new version, finding each by its path (FR-008). */
+    function rebase(key, staging, bytes, version) {
+        const source = idFor(key);
+        const kept = [];
+        // One opening of the new version serves every edit; bytes that do not open leave none of them writable.
+        const opening = staging.writer.open(bytes);
+        if (!opening.ok) {
+            // A version that does not open (a file saved mid-typing) costs no staged edit: they wait against their base
+            // until a version that opens arrives, and rebase onto that one (FIX-001, the owner's ruling).
+            staging.waiting = opening.reason;
+            for (const e of staging.edits)
+                notices.push({ source, path: e.path, outcome: "waiting", detail: opening.reason });
+            return;
+        }
+        staging.waiting = undefined;
+        const doc = opening.document;
+        for (const e of staging.edits) {
+            // The shift guard (FR-013) comes first: through a list that changed length, the path may name another item.
+            if (staging.doc.shifted?.(e.path, doc)) {
+                notices.push({ source, path: e.path, outcome: "conflicted", reason: "shifted" });
+                continue;
+            }
+            let again;
+            if (e.op === "set") {
+                const found = doc.locate(e.path);
+                if (!found.ok) {
+                    notices.push({ source, path: e.path, outcome: "conflicted", reason: "gone", detail: found.reason });
+                    continue;
+                }
+                checkRange(bytes.length, found.start, found.end, "the writer");
+                // The value is written again on the new bytes: its spelling can depend on its neighbours.
+                again = doc.write(e.path, e.value);
+                if (!again.ok) {
+                    notices.push({ source, path: e.path, outcome: "conflicted", reason: "unwritable", detail: again.reason });
+                    continue;
+                }
+            }
+            else if (e.op === "remove") {
+                // A delete (FR-010) acts on the whole entry, which someone else's work may live inside: if the entry's
+                // located bytes are not the ones this edit was staged against, it is the colleague's now and is kept.
+                const found = doc.locate(e.path);
+                if (!found.ok) {
+                    notices.push({ source, path: e.path, outcome: "conflicted", reason: "gone", detail: found.reason });
+                    continue;
+                }
+                checkRange(bytes.length, found.start, found.end, "the writer");
+                if (!doc.remove) {
+                    notices.push({ source, path: e.path, outcome: "conflicted", reason: "unwritable" });
+                    continue;
+                }
+                again = doc.remove(e.path);
+                if (!again.ok) {
+                    notices.push({ source, path: e.path, outcome: "conflicted", reason: GONE_CODES.has(again.code ?? "") ? "gone" : "unwritable", detail: again.reason });
+                    continue;
+                }
+                checkRange(bytes.length, again.edit.start, again.edit.end, "the writer");
+                // What the delete cuts now must be what it cut when it was staged, attached comments included (FIX-002):
+                // anything a colleague put there is theirs, and the delete yields.
+                if (!sameBytes(bytes.subarray(again.edit.start, again.edit.end), staging.base.subarray(e.start, e.end))) {
+                    notices.push({ source, path: e.path, outcome: "conflicted", reason: "changed" });
+                    continue;
+                }
+            }
+            else {
+                // An insert (FR-007). A refusal's code says why (FIX-003); a writer that gives none is asked whether the key is
+                // there now: if so a colleague added it (`exists`), and if not the place it went into is gone.
+                if (!doc.add) {
+                    notices.push({ source, path: e.path, outcome: "conflicted", reason: "unwritable" });
+                    continue;
+                }
+                again = doc.add(e.path, e.value);
+                if (!again.ok) {
+                    const code = again.code;
+                    const reason = code === undefined ? (doc.locate(e.path).ok ? "exists" : "gone") : code === EXISTS_CODE ? "exists" : GONE_CODES.has(code) ? "gone" : "unwritable";
+                    notices.push({ source, path: e.path, outcome: "conflicted", reason, detail: again.reason });
+                    continue;
+                }
+            }
+            const { start, end } = again.edit;
+            checkRange(bytes.length, start, end, "the writer");
+            // Staging refused overlap on the old bytes; the writer's answers on the new ones can overlap.
+            // The earlier-staged edit keeps its place and the later one is conflicted, never spliced over it.
+            if (kept.some(k => overlaps(k, again.edit))) {
+                notices.push({ source, path: e.path, outcome: "conflicted", reason: "overlap" });
+                continue;
+            }
+            const now = bytes.slice(start, end);
+            const was = staging.base.subarray(e.start, e.end);
+            // Only a set replaces a value that is there; an insert has no disk value to override.
+            const same = e.op !== "set" || (now.length === was.length && now.every((byte, i) => byte === was[i]));
+            const moved = start !== e.start || end !== e.end;
+            const status = same ? e.status : "overrides";
+            const disk = same ? e.disk : now;
+            const rewritten = { path: e.path, bytes: again.edit.bytes, start, end, status, ...(disk === undefined ? {} : { disk }) };
+            kept.push(e.op === "remove" ? { ...rewritten, op: "remove" } : { ...rewritten, op: e.op, value: e.value });
+            if (!same)
+                notices.push({ source, path: e.path, outcome: "overrides", start, end, disk: now });
+            else if (moved)
+                notices.push({ source, path: e.path, outcome: "moved", start, end });
+            else if (!sameBytes(again.edit.bytes, e.bytes))
+                notices.push({ source, path: e.path, outcome: "respelled", start, end });
+        }
+        staging.edits = kept;
+        staging.doc = doc;
+        staging.base = bytes;
+        staging.version = version;
+        staging.preview = undefined;
+        if (kept.length === 0)
+            staged.delete(key);
+    }
+    /** Takes a source's new version into the session, rebasing the edits staged against the old one. */
+    function adopt(key, fresh) {
+        nodes.set(key, fresh);
+        const staging = staged.get(key);
+        if (!staging)
+            return;
+        if (fresh.state === "refused" || fresh.state === "external" || fresh.bytes === undefined)
+            conflict(key);
+        else
+            rebase(key, staging, fresh.bytes, fresh.version);
+    }
+    /** Reads, hashes and analyses one source. Never throws for the state of the world. */
+    async function load(key, external) {
+        const id = idFor(key);
+        if (external)
+            return { id, key, state: "external", links: [] };
+        const read = await host.read(key);
+        if (!read.ok)
+            return { id, key, state: "refused", reason: read.reason, links: [] };
+        const version = await sha256(read.bytes);
+        const handler = handlers.find(h => h.claims(key));
+        const kept = writers.some(w => w.claims(key)) ? { bytes: read.bytes } : {};
+        if (!handler)
+            return { id, key, state: "leaf", version, links: [], ...kept };
+        let text;
+        try {
+            text = decoder.decode(read.bytes);
+        }
+        catch {
+            return { id, key, state: "undecodable", version, links: [], ...kept };
+        }
+        const findings = findingsFor(handler, version, text);
+        const indices = findings.requests.flatMap(r => [r.start, r.end]);
+        const offsets = byteOffsets(text, indices);
+        const base = baseFor(key, findings.base);
+        const links = [];
+        for (const [k, r] of findings.requests.entries()) {
+            const l = { from: { start: offsets[2 * k], end: offsets[2 * k + 1] }, request: r.request, lookup: joined(r.request, findings.base), kind: r.kind, base, probes: [] };
+            if (await link(l))
+                links.push(l);
+        }
+        return { id, key, state: "analysed", version, links, ...kept };
+    }
+    /**
+     * Brings the session to its fixpoint: every source reachable from the roots is present, every
+     * other one is gone, and the host watches what matters. Returns the keys added and removed.
+     */
+    async function settle() {
+        const reachable = new Set();
+        const added = [];
+        const all = new Set([...roots, ...[...passRoots.values()].flatMap(keys => [...keys])]);
+        const worklist = [...all].map(key => ({ key, external: false }));
+        for (let next = worklist.shift(); next; next = worklist.shift()) {
+            if (reachable.has(next.key))
+                continue;
+            reachable.add(next.key);
+            let node = nodes.get(next.key);
+            if (!node) {
+                node = await load(next.key, next.external);
+                nodes.set(next.key, node);
+                added.push(next.key);
+            }
+            for (const l of node.links)
+                if (l.target)
+                    worklist.push(l.target);
+        }
+        const removed = [...nodes.keys()].filter(key => !reachable.has(key));
+        for (const key of removed) {
+            nodes.delete(key);
+            conflict(key); // a source that left the graph has nowhere for its edits to land
+        }
+        const watched = new Set();
+        for (const node of nodes.values()) {
+            if (node.state !== "external")
+                watched.add(node.key);
+            for (const l of node.links)
+                for (const probe of l.probes)
+                    watched.add(probe);
+        }
+        // Work already running at `close()` finishes, but must not watch again: a Node host would
+        // open directory watchers that keep the process alive.
+        if (!closed)
+            watch.set([...watched]);
+        return { added, removed };
+    }
+    /** Tells every listener, each even if another throws; the first throw is then rethrown. */
+    function emit(change) {
+        if (change.added.length + change.removed.length + change.changed.length + (change.edits?.length ?? 0) === 0)
+            return;
+        const thrown = [];
+        for (const listener of listeners) {
+            try {
+                listener(change);
+            }
+            catch (error) {
+                thrown.push(error);
+            }
+        }
+        if (thrown.length > 0)
+            throw thrown[0];
+    }
+    /** Settles, for anything that changes the roots or the world; returns the change to announce. */
+    async function report(changedKeys) {
+        const { added, removed } = await settle();
+        return {
+            added: added.map(idFor),
+            removed: removed.map(idFor),
+            changed: changedKeys.filter(key => nodes.has(key)).map(idFor),
+            ...drained(),
+        };
+    }
+    const versionOf = (node) => node === undefined ? undefined : node.state === "refused" ? `refused:${node.reason}` : "version" in node ? node.version : "external";
+    /** Absorbs one batch of host events (data-model.md, rules 3 and 4). */
+    async function absorb(locations) {
+        const touched = new Set(locations);
+        const changed = [];
+        for (const node of [...nodes.values()]) {
+            if (touched.has(node.key) && node.state !== "external") {
+                const fresh = await load(node.key, false);
+                if (versionOf(fresh) !== versionOf(node)) {
+                    adopt(node.key, fresh);
+                    changed.push(node.key);
+                }
+            }
+        }
+        for (const node of nodes.values()) {
+            for (const l of node.links)
+                if (l.probes.some(p => touched.has(p)))
+                    await link(l);
+        }
+        return report(changed);
+    }
+    const edge = (node, l) => {
+        const target = l.target && nodes.get(l.target.key)?.id;
+        const version = "version" in node ? node.version : "";
+        return {
+            from: { source: node.id, version, start: l.from.start, end: l.from.end },
+            request: l.request,
+            ...(target === undefined ? {} : { target }),
+            kind: l.kind,
+            origin: "declared",
+            probes: l.probes,
+        };
+    };
+    const view = (node) => {
+        const { id, key: location } = node;
+        switch (node.state) {
+            case "refused":
+                return { id, location, state: node.state, reason: node.reason };
+            case "external":
+                return { id, location, state: node.state };
+            default:
+                return { id, location, state: node.state, version: node.version };
+        }
+    };
+    const allEdges = () => [...nodes.values()].flatMap(node => node.links.map(l => edge(node, l)));
+    const nodeById = (id) => [...nodes.values()].find(node => node.id === id);
+    /** Strongly connected components with more than one source, or a source asking for itself (Tarjan). */
+    function cycles() {
+        const index = new Map();
+        const low = new Map();
+        const stack = [];
+        const found = [];
+        const next = (key) => (nodes.get(key)?.links ?? []).flatMap(l => (l.target && nodes.has(l.target.key) ? [l.target.key] : []));
+        const visit = (key) => {
+            index.set(key, index.size);
+            low.set(key, index.get(key) ?? 0);
+            stack.push(key);
+            for (const to of next(key)) {
+                if (!index.has(to)) {
+                    visit(to);
+                    low.set(key, Math.min(low.get(key) ?? 0, low.get(to) ?? 0));
+                }
+                else if (stack.includes(to)) {
+                    low.set(key, Math.min(low.get(key) ?? 0, index.get(to) ?? 0));
+                }
+            }
+            if (low.get(key) === index.get(key)) {
+                const component = [];
+                let member;
+                do {
+                    member = stack.pop();
+                    if (member !== undefined)
+                        component.push(member);
+                } while (member !== undefined && member !== key);
+                if (component.length > 1 || next(key).includes(key))
+                    found.push(component.map(idFor));
+            }
+        };
+        for (const key of nodes.keys())
+            if (!index.has(key))
+                visit(key);
+        return found;
+    }
+    /** Ends a pass that is still its label's live one: its keys become the label's roots (data-model.md, rule 5). */
+    async function endPass(label, keys, reads) {
+        passRoots.set(label, keys);
+        const changed = [];
+        for (const [key, version] of reads) {
+            const node = nodes.get(key);
+            if (!node || versionOf(node) === version)
+                continue;
+            const fresh = await load(key, false);
+            if (versionOf(fresh) !== versionOf(node)) {
+                adopt(key, fresh);
+                changed.push(key);
+            }
+        }
+        const { added, removed } = await settle();
+        // The render used other bytes than the session now holds: a change, not a new source.
+        const mismatched = [...reads].filter(([key, version]) => nodes.has(key) && versionOf(nodes.get(key)) !== version).map(([key]) => key);
+        return {
+            added: added.filter(key => !mismatched.includes(key)).map(idFor),
+            removed: removed.map(idFor),
+            changed: [...new Set([...changed, ...mismatched])].filter(key => nodes.has(key)).map(idFor),
+            ...drained(),
+        };
+    }
+    function read(label = "") {
+        const token = {};
+        livePasses.set(label, token);
+        const reads = new Map();
+        const notes = new Set();
+        const missing = new Set();
+        const recording = [];
+        let manifest;
+        const recordMissing = (location) => void recording.push(keyFor(location).then(key => void missing.add(key)));
+        const passHost = {
+            paths: host.paths,
+            async canonicalize(location) {
+                const found = await host.canonicalize(location);
+                if (found === undefined && manifest === undefined)
+                    missing.add(host.paths.resolve(location));
+                return found;
+            },
+            // Hands back the host's answer at once; hashing and canonicalizing are recorded on the side.
+            async read(location) {
+                const result = await host.read(location);
+                if (manifest !== undefined)
+                    return result;
+                if (!result.ok)
+                    recordMissing(location);
+                else {
+                    const bytes = result.bytes;
+                    recording.push(Promise.all([keyFor(location), sha256(bytes)]).then(([key, version]) => void reads.set(key, version)));
+                }
+                return result;
+            },
+            cacheRead: async () => undefined,
+            cacheWrite: async () => {
+                throw new Error("no cache configured");
+            },
+        };
+        async function finish() {
+            await Promise.all(recording);
+            for (const key of [...reads.keys(), ...notes])
+                missing.delete(key);
+            const keys = new Set([...reads.keys(), ...notes, ...missing]);
+            if (livePasses.get(label) === token) {
+                livePasses.delete(label);
+                await serialize(() => endPass(label, keys, reads));
+            }
+            const noted = [...notes].filter(key => !reads.has(key)).map(key => ({ key, node: nodes.get(key) }));
+            const versioned = (node) => (node && "version" in node ? node.version : undefined);
+            return {
+                read: [
+                    ...[...reads].map(([key, version]) => ({ source: idFor(key), version })),
+                    ...noted.flatMap(({ key, node }) => {
+                        const version = versioned(node);
+                        return version === undefined ? [] : [{ source: idFor(key), version }];
+                    }),
+                ],
+                missing: [...missing, ...noted.filter(({ node }) => versioned(node) === undefined).map(({ key }) => key)],
+            };
+        }
+        return {
+            host: passHost,
+            note(location) {
+                if (manifest === undefined)
+                    recording.push(keyFor(location).then(key => void notes.add(key)));
+            },
+            end: () => (manifest ??= finish()),
+        };
+    }
+    /** Whether the source at `location` can have edits staged: in the graph, readable, and claimed by a writer. */
+    async function stageable(location) {
+        const key = await keyFor(location);
+        const node = nodes.get(key);
+        if (!node)
+            return { ok: false, reason: "not a source in the session's graph" };
+        if (node.state === "external")
+            return { ok: false, reason: `${key} is external, and cannot be edited` };
+        if (node.state === "refused")
+            return { ok: false, reason: `${key} could not be read: ${node.reason}` };
+        const writer = writers.find(w => w.claims(key));
+        if (!writer)
+            return { ok: false, reason: `no writer claims ${key}` };
+        return { ok: true, key, node, writer };
+    }
+    /**
+     * Stages one edit. `against` is a restore's (saved-index FR-006): the base to stage a source's first edit against
+     * in place of the one the session holds; a source already being staged keeps the base it has.
+     */
+    async function stageEdit(location, operation, against) {
+        const { path } = operation;
+        const found = await stageable(location);
+        if (!found.ok)
+            return found;
+        const { key, node, writer } = found;
+        let staging = staged.get(key);
+        // The base the session holds: the bytes of the version it last took in. A disk that has moved
+        // since is the rebase's business, when the host reports it.
+        const base = staging?.base ?? against?.bytes ?? ("bytes" in node ? node.bytes : undefined);
+        if (!base)
+            return { ok: false, reason: `${key} was not read` };
+        let doc = staging?.doc;
+        if (!doc) {
+            const opening = writer.open(base);
+            if (!opening.ok)
+                return { ok: false, reason: opening.reason };
+            doc = opening.document;
+        }
+        const others = staging?.edits ?? [];
+        const same = others.find(e => e.path === path);
+        const inside = doc.inside;
+        // What lies inside what is the writer's to say: its path language, its reader (ruling 8). At most one staged
+        // edit can contain a path, since an edit inside another amends it instead of joining the index.
+        const within = inside && others.find(e => e.path !== path && inside.call(doc, path, e.path));
+        /** Stages the edit again with a new value, in the place it held; the writer's refusal is the caller's. */
+        const restage = (edit, value) => {
+            const again = perform(doc, key, { op: edit.op, path: edit.path, value });
+            if (!again.ok)
+                return { ok: false, reason: again.reason };
+            const { start, end, bytes } = again.edit;
+            checkRange(base.length, start, end, "the writer");
+            const clash = others.find(e => e !== edit && overlaps(e, again.edit));
+            if (clash)
+                return { ok: false, reason: `the edit overlaps the staged edit at ${clash.path}` };
+            if (staging) {
+                staging.edits = staging.edits.map(e => (e === edit ? { ...edit, value, start, end, bytes } : e));
+                staging.preview = undefined;
+            }
+            return { ok: true };
+        };
+        if (within) {
+            // An edit inside a staged edit (FR-011): inside a delete it is refused; inside a set or an insert it
+            // amends the staged value, which the writer then writes again, so the bytes stay the writer's.
+            if (within.op === "remove")
+                return { ok: false, reason: `the entry at ${within.path} is staged for removal` };
+            if (!doc.amend)
+                return { ok: false, reason: `the writer for ${key} cannot amend the staged edit at ${within.path}: its document has no amend` };
+            const amended = doc.amend({ path: within.path, value: within.value }, operation);
+            // The writer said the path is inside; an amend that says otherwise is the writer contradicting itself, a bug (FIX-005).
+            if (!amended.inside)
+                throw new Error(`the writer for ${key} says ${operation.path} is inside the staged edit at ${within.path}, and its amend says it is not`);
+            return amended.ok ? restage(within, amended.value) : { ok: false, reason: amended.reason };
+        }
+        if (staging && same?.op === "add") {
+            // On a staged insert's own path: a set or an add changes the insert wholesale, a remove undoes it.
+            if (operation.op !== "remove")
+                return restage(same, operation.value);
+            staging.edits = staging.edits.filter(e => e !== same);
+            staging.preview = undefined;
+            if (staging.edits.length === 0)
+                staged.delete(key);
+            return { ok: true };
+        }
+        // On a staged delete's path, a set or an add is a set of the entry, which is in the base; otherwise the
+        // operation is staged as it came, and a staged edit at its path (a set, a delete) is replaced.
+        const effective = same?.op === "remove" && operation.op !== "remove" ? { op: "set", path, value: operation.value } : operation;
+        const written = perform(doc, key, effective);
+        if (!written.ok) {
+            const blind = !doc.inside && others.some(e => e.op === "add");
+            return { ok: false, reason: blind ? `${written.reason}; the writer's document has no inside, so it cannot say whether the path lies inside a staged insert` : written.reason };
+        }
+        const { start, end, bytes } = written.edit;
+        checkRange(base.length, start, end, "the writer");
+        const clash = others.find(e => e.path !== path && overlaps(e, written.edit));
+        if (clash)
+            return { ok: false, reason: `the edit overlaps the staged edit at ${clash.path}` };
+        if (!staging)
+            staged.set(key, (staging = { writer, version: against?.version ?? node.version, base, doc, edits: [] }));
+        const edit = { path, start, end, bytes, status: "staged", ...(effective.op === "remove" ? { op: "remove" } : { op: effective.op, value: effective.value }) };
+        // Replaced, the edit goes last: the list is in the order edits were staged, which a rebase reads.
+        staging.edits = [...staging.edits.filter(e => e.path !== path), edit];
+        staging.preview = undefined;
+        return { ok: true };
+    }
+    /** Stages one saved source again against its saved base, then rebases it onto the version the session holds (saved-index FR-006). */
+    async function restoreSource(entry) {
+        const refused = (reason) => ({ location: entry.location, outcome: "refused", reason, edits: [] });
+        const found = await stageable(entry.location);
+        if (!found.ok)
+            return refused(found.reason);
+        const { key, node } = found;
+        if (staged.has(key))
+            return refused(`${key} already has staged edits`);
+        const held = "bytes" in node ? node.bytes : undefined;
+        if (!held)
+            return refused(`${key} was not read`);
+        if ((await sha256(entry.bytes)) !== entry.base)
+            return refused("the saved bytes do not hash to the saved base version");
+        const against = { version: entry.base, bytes: entry.bytes.slice() };
+        const edits = [];
+        for (const saved of entry.edits) {
+            const operation = saved.op === "remove" ? { op: "remove", path: saved.path } : saved.value === undefined ? undefined : { op: saved.op, path: saved.path, value: saved.value };
+            const result = operation === undefined ? { ok: false, reason: `a ${saved.op} needs a value` } : await stageEdit(entry.location, operation, against);
+            if (!result.ok) {
+                edits.push({ path: saved.path, outcome: "refused", reason: result.reason });
+                continue;
+            }
+            edits.push({ path: saved.path, outcome: "restored" });
+            // Its status is part of what was saved (FR-003): staging made it plain `staged`.
+            const put = staged.get(key)?.edits.find(e => e.path === saved.path);
+            if (put) {
+                put.status = saved.status;
+                if (saved.disk !== undefined)
+                    put.disk = saved.disk.slice();
+            }
+        }
+        const staging = staged.get(key);
+        if (!staging)
+            return { location: entry.location, outcome: "refused", reason: "none of its edits could be restored", edits };
+        // The session's version is not the saved base: the usual rebase, which says what it did through the notices.
+        if (node.version !== entry.base)
+            rebase(key, staging, held, node.version);
+        return { location: entry.location, outcome: "restored", edits };
+    }
+    /** Whether a commit may write here: under a writable root, judged on whole segments of canonical locations. */
+    async function isWritable(key) {
+        const { separator, resolve } = host.paths;
+        for (const root of writable) {
+            const canonical = (await host.canonicalize(root)) ?? resolve(root);
+            const prefix = canonical.endsWith(separator) ? canonical : canonical + separator;
+            if (key === canonical || key.startsWith(prefix))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Prepares one source for a commit (atomic-commit FR-001): the checks, the read, the rebase, and the bytes to write.
+     * Touches no disk. A source that cannot be written, or that lost an edit, comes back as the report entry that
+     * says so (`cause`); it stops the commit.
+     */
+    async function prepare(key, staging) {
+        const source = idFor(key);
+        const nothing = (outcome, reason) => ({ cause: { source, location: key, outcome, reason, edits: [] } });
+        if (!(await isWritable(key)))
+            return nothing("refused", `${key} is outside every writable root`);
+        if (host.write === undefined)
+            return nothing("refused", "the host cannot write");
+        const read = await host.read(key);
+        if (!read.ok)
+            return nothing("failed", read.reason);
+        const first = notices.length;
+        const version = await sha256(read.bytes);
+        if (version !== staging.version)
+            rebase(key, staging, read.bytes, version);
+        if (staging.waiting !== undefined && staged.get(key) === staging)
+            return nothing("refused", `the file on disk does not open: ${staging.waiting}`);
+        const dropped = notices.slice(first).filter(n => n.outcome === "conflicted" && n.source === source);
+        const remaining = staged.get(key);
+        if (dropped.length > 0 || !remaining) {
+            const edits = dropped.map(n => ({ path: n.path, outcome: "conflicted", ...(n.reason === undefined ? {} : { reason: n.reason }), ...(n.detail === undefined ? {} : { detail: n.detail }) }));
+            return { cause: { source, location: key, outcome: "conflicted", edits } };
+        }
+        const bytes = splice(remaining.base, remaining.edits);
+        // Analysed now, before any write (FR-012, ruled): a handler that throws on the new text stops the commit with
+        // nothing on disk. The findings are held for this piece of work, so the load after the write hits the cache.
+        const handler = handlers.find(h => h.claims(key));
+        if (handler) {
+            let text;
+            try {
+                text = decoder.decode(bytes);
+            }
+            catch {
+                text = undefined;
+            }
+            if (text !== undefined)
+                findingsFor(handler, await sha256(bytes), text);
+        }
+        const edits = remaining.edits.map((e) => (e.status === "overrides" && e.disk ? { path: e.path, outcome: "overrode", disk: e.disk } : { path: e.path, outcome: "written" }));
+        return { key, source, bytes, disk: read.bytes, version: await sha256(bytes), edits };
+    }
+    /**
+     * Commits a set of staged sources, all or none (atomic-commit): prepare every one, and only if none is a cause write
+     * them in order; a failed write puts the written ones back, newest first. `commit()` passes the whole index;
+     * a group would pass its sources.
+     */
+    async function commitSources(entries, changed) {
+        const put = (key, bytes) => (host.write ? host.write(key, bytes) : Promise.resolve({ ok: false, reason: "the host cannot write" }));
+        const prepared = [];
+        for (const [key, staging] of entries)
+            prepared.push(await prepare(key, staging));
+        let stopper = prepared.flatMap(p => ("cause" in p ? [p.cause.location] : []))[0];
+        const wrote = [];
+        const fresh = new Map();
+        let failed;
+        if (stopper === undefined) {
+            for (const p of prepared) {
+                if ("cause" in p)
+                    continue;
+                const written = await put(p.key, p.bytes);
+                if (!written.ok) {
+                    failed = { source: p.source, location: p.key, outcome: "failed", reason: written.reason, edits: [] };
+                    stopper = p.key;
+                    break;
+                }
+                writtenKeys.push(p.key);
+                wrote.push(p);
+                // Analysed before the next write: a handler that throws on the new text stops the commit here, as it always did.
+                fresh.set(p.key, await load(p.key, false));
+            }
+        }
+        // Undo (FR-004): the host's own write, after checking the disk still holds what this commit wrote (ruling 6).
+        const unrestored = new Map();
+        if (failed) {
+            for (const p of wrote.reverse()) {
+                const was = await host.read(p.key);
+                let why;
+                if (!was.ok)
+                    why = `putting ${p.key} back failed: could not read it: ${was.reason}`;
+                else if ((await sha256(was.bytes)) !== p.version)
+                    why = `${p.key} was saved by someone else after this commit wrote it; left as it is`;
+                else {
+                    // ponytail: a colleague can still save between the read above and this write; closing it needs a host verb that writes only if unchanged (parked).
+                    const back = await put(p.key, p.disk);
+                    if (!back.ok)
+                        why = `putting ${p.key} back failed: ${back.reason}`;
+                }
+                if (why === undefined)
+                    writtenKeys.splice(writtenKeys.indexOf(p.key), 1);
+                else
+                    unrestored.set(p.key, why);
+            }
+        }
+        const sources = [];
+        for (const p of prepared) {
+            if ("cause" in p)
+                sources.push(p.cause);
+            else if (failed && failed.location === p.key)
+                sources.push(failed);
+            else if (unrestored.has(p.key))
+                sources.push({ source: p.source, location: p.key, outcome: "unrestored", reason: unrestored.get(p.key), version: p.version, edits: p.edits });
+            else if (stopper !== undefined)
+                sources.push({ source: p.source, location: p.key, outcome: "aborted", reason: `the commit was aborted by ${stopper}`, edits: [] });
+            else
+                sources.push({ source: p.source, location: p.key, outcome: "written", version: p.version, edits: p.edits });
+        }
+        // What is on disk now leaves the index and the node catches up (a source put back keeps its edits and its node).
+        for (const p of prepared) {
+            if ("cause" in p || !writtenKeys.includes(p.key))
+                continue;
+            staged.delete(p.key);
+            const node = fresh.get(p.key);
+            if (!node)
+                continue;
+            if (versionOf(node) !== versionOf(nodes.get(p.key)))
+                changed.push(p.key);
+            nodes.set(p.key, node);
+        }
+        return { outcome: stopper === undefined ? "committed" : "aborted", sources };
+    }
+    const session = {
+        read,
+        sources: () => [...nodes.values()].map(view),
+        source: id => {
+            const node = nodeById(id);
+            return node && view(node);
+        },
+        edgesFrom: id => allEdges().filter(e => e.from.source === id),
+        edgesInto: id => allEdges().filter(e => e.target === id),
+        unresolved: () => allEdges().filter(e => e.target === undefined),
+        cycles,
+        addRoot: location => serialize(async () => {
+            roots.add(await keyFor(location));
+            return report([]);
+        }),
+        removeRoot: location => serialize(async () => {
+            roots.delete(await keyFor(location));
+            return report([]);
+        }),
+        onChange(listener) {
+            listeners.add(listener);
+            return () => void listeners.delete(listener);
+        },
+        stage(location, operation) {
+            let result = { ok: false, reason: "the session is closed" };
+            return serialize(async () => void (result = await stageEdit(location, operation))).then(() => result);
+        },
+        index: () => [...staged].flatMap(([key, staging]) => staging.edits.map((e) => ({
+            source: idFor(key),
+            path: e.path,
+            op: e.op,
+            ...(e.value === undefined ? {} : { value: e.value }),
+            base: staging.version,
+            start: e.start,
+            end: e.end,
+            status: e.status,
+            ...(e.disk === undefined ? {} : { disk: e.disk }),
+            ...(staging.waiting === undefined ? {} : { waiting: staging.waiting }),
+        }))),
+        save: () => ({
+            format: 1,
+            sources: [...staged].map(([key, staging]) => ({
+                location: key,
+                base: staging.version,
+                bytes: staging.base.slice(),
+                edits: staging.edits.map(e => ({
+                    op: e.op,
+                    path: e.path,
+                    ...(e.value === undefined ? {} : { value: e.value }),
+                    status: e.status,
+                    ...(e.disk === undefined ? {} : { disk: e.disk.slice() }),
+                })),
+            })),
+        }),
+        restore(saved) {
+            let result = { outcome: "refused", reason: "the session is closed", sources: [] };
+            if (saved.format !== 1)
+                return Promise.resolve({ outcome: "refused", reason: `the saved index has format ${String(saved.format)}, and only format 1 is known`, sources: [] });
+            return serialize(async () => {
+                const sources = [];
+                for (const entry of saved.sources)
+                    sources.push(await restoreSource(entry));
+                result = { outcome: "restored", sources };
+                return report([]);
+            }).then(() => result);
+        },
+        unstage: (location, path) => serialize(async () => {
+            const key = await keyFor(location);
+            const staging = staged.get(key);
+            if (!staging)
+                return;
+            if (path === undefined)
+                staged.delete(key);
+            else {
+                staging.edits = staging.edits.filter(e => e.path !== path);
+                staging.preview = undefined;
+                if (staging.edits.length === 0)
+                    staged.delete(key);
+            }
+        }),
+        preview(id) {
+            let result;
+            return serialize(async () => {
+                const node = nodeById(id);
+                const staging = node && staged.get(node.key);
+                if (!node || !staging)
+                    return;
+                const bytes = splice(staging.base, staging.edits);
+                const version = await sha256(bytes);
+                const handler = handlers.find(h => h.claims(node.key));
+                let text;
+                try {
+                    text = decoder.decode(bytes);
+                }
+                catch {
+                    text = undefined;
+                }
+                if (handler && text !== undefined) {
+                    findingsFor(handler, version, text);
+                    staging.preview = version;
+                }
+                result = { bytes, version };
+            }).then(() => result);
+        },
+        commit() {
+            let result = { outcome: "committed", sources: [] };
+            return serialize(async () => {
+                const changed = [];
+                result = await commitSources([...staged], changed);
+                return report(changed);
+            }).then(() => result);
+        },
+        close() {
+            closed = true;
+            watch.close();
+            listeners.clear();
+            open.delete(holds);
+            sweep(handlers);
+        },
+    };
+    try {
+        await serialize(async () => {
+            roots.add(await keyFor(options.entry));
+            await settle();
+        });
+    }
+    catch (error) {
+        session.close(); // nobody can close a session that never opened, and it would hold its finds forever
+        throw error;
+    }
+    return session;
+}