@volter/world-core 2.0.0

package/dist/src/log.js

@@ -0,0 +1,801 @@
+// THE LOG (docs/concepts/the-model.md). One kind of entry, one log per
+// branch, and a branch is a parent plus a position in the parent's log:
+//
+//   parent log   `events.jsonl`   what the branch inherited — the origin's history as fetched, the
+//                                 placeholder's default data, and every entry of this branch that
+//                                 LANDED on the parent (a push, or a deploy at a root), with its
+//                                 receipt. Written only by fetch, refresh and landing; never by a
+//                                 write the app made.
+//   branch log   `actions.jsonl`  this branch's own entries, in order: every write the app made,
+//                                 recorded as it was served. Written only by the write path.
+//   branch.json                   the parent: the placeholder, a base world root at a position,
+//                                 or a served world's URL. Absent = an unbranched world whose
+//                                 parent is whatever its parent log holds.
+//   views/<hash>.json              immutable verified segment ranges and projection layout.
+//   checkpoints/latest.json       the tree bound to the exact inherited view: a read is
+//                                 the checkpoint plus the entries since, never a replay from zero.
+//
+// Landing replaces confirm-and-suppress: an entry that lands is COPIED to the parent log with its
+// receipt (and under the vendor's id when the vendor minted one, `aliasOf` naming the local id),
+// and the fold skips a branch entry whose id the parent already holds. Nothing is suppressed,
+// rebound or quarantined by a bookkeeping row; `unpushed` is the branch log minus what the parent
+// holds. The parent log accepts the v1 observed-event rows too (`toEntry` reads a delta event as
+// an entry; a non-delta observation folds nothing and is kept for `listEvents`), so a protocol 1
+// pack's own fold of the logs keeps working while it is deprecated.
+import { captureHistory, historyChanges, historyEntryTime, historyEntries, historyLength, historyPrefix, inheritedHistory, inheritedHistoryKey, originHead, readHistoryView, replaceHistoryOrigin, saveHistoryView, validateHistoryOrigin } from "./history.js";
+import { dirname, join } from 'node:path';
+import { canonicalStatePath, checkParent, commitParentPin, pinParent, withAncestryLock } from "./ancestry.js";
+import { resolveReferences } from "./references.js";
+import { hashFieldValue } from "./hash.js";
+import { worldPaths } from "./storage.js";
+import { getActiveWorldStore } from "./world-store.js";
+export const CHECKPOINT_EVERY = 100;
+export const DELTA_SUFFIX = '.delta';
+export function parentLogPath(service, root) { return worldPaths(service, root).events; }
+export function branchLogPath(service, root) { return join(dirname(worldPaths(service, root).events), 'actions.jsonl'); }
+export function branchMetaPath(service, root) { return join(dirname(worldPaths(service, root).events), 'branch.json'); }
+/** The fetched cache of a URL parent's whole log — what `fetch` extends and a read folds up to the position. */
+export function originLogPath(service, root) { return join(dirname(worldPaths(service, root).events), 'origin.jsonl'); }
+/** A parent is at a URL when it is not a path on this machine. */
+export function isUrlParent(at) { return /^[a-z][a-z0-9+.-]*:\/\//i.test(at); }
+export function checkpointPath(service, root) { return join(dirname(worldPaths(service, root).events), 'checkpoints', 'latest.json'); }
+const parsedRows = new WeakMap();
+function parseLines(path, lines, offset, out) {
+    for (const [i, line] of lines.entries()) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch (error) {
+            throw new Error(`${path}:${offset + i + 1}: invalid JSONL row: ${error.message}`);
+        }
+    }
+}
+/** A log's content from the start of its last non-blank line to its end: what must still stand at that byte offset
+ *  for the log to have only grown since. `undefined` when the content does not end a line or holds no entry. */
+function tailOf(content) {
+    if (!content.endsWith('\n'))
+        return undefined;
+    // blank as parseLines reads it: a line that trims to nothing (a CRLF's `\r`, spaces) is no entry
+    let start = content.lastIndexOf('\n', content.length - 2) + 1;
+    while (start > 0 && !content.slice(start, content.indexOf('\n', start)).trim())
+        start = content.lastIndexOf('\n', start - 2) + 1;
+    if (!content.slice(start, content.indexOf('\n', start)).trim())
+        return undefined;
+    return content.slice(start);
+}
+function readRows(path) {
+    const store = getActiveWorldStore();
+    const cache = parsedRows.get(store) ?? parsedRows.set(store, new Map()).get(store);
+    const held = cache.get(path);
+    if (store.readRange && held?.bytes !== undefined && held.tail !== undefined) {
+        const chunk = store.readRange(path, held.bytes - Buffer.byteLength(held.tail));
+        if (chunk === null) {
+            cache.delete(path);
+            return [];
+        }
+        const appended = chunk.startsWith(held.tail) ? chunk.slice(held.tail.length) : undefined;
+        if (appended === '')
+            return held.rows.slice();
+        // only whole appended lines extend the rows; a torn last line is read (and refused) as the whole file reads it
+        if (appended !== undefined && appended.endsWith('\n')) {
+            const rows = held.rows.slice();
+            const lines = appended.split('\n');
+            parseLines(path, lines, held.lines, rows);
+            const tail = tailOf(held.tail + appended);
+            cache.set(path, { rows, lines: held.lines + lines.length - 1, bytes: held.bytes + Buffer.byteLength(appended), tail });
+            return rows.slice();
+        }
+    }
+    const content = store.read(path);
+    if (content === null) {
+        cache.delete(path);
+        return [];
+    }
+    if (!store.readRange && held?.content !== undefined) {
+        if (held.content === content)
+            return held.rows.slice();
+        // an append after a whole row extends the rows already parsed; anything else is parsed afresh
+        if (held.content.endsWith('\n') && content.startsWith(held.content)) {
+            const rows = held.rows.slice();
+            parseLines(path, content.slice(held.content.length).split('\n'), held.lines, rows);
+            cache.set(path, { content, rows, lines: held.lines + content.slice(held.content.length).split('\n').length - 1 });
+            return rows.slice();
+        }
+    }
+    const rows = [];
+    const lines = content.split('\n');
+    parseLines(path, lines, 0, rows);
+    const tail = store.readRange ? tailOf(content) : undefined;
+    cache.set(path, tail !== undefined ? { rows, lines: lines.length - 1, bytes: Buffer.byteLength(content), tail } : { content, rows, lines: lines.length - 1 });
+    return rows.slice();
+}
+export function readBranchMeta(service, root) {
+    const raw = getActiveWorldStore().read(branchMetaPath(service, root));
+    if (raw === null)
+        return null;
+    const meta = JSON.parse(raw);
+    // a pointer written before positions were one number: the parent's whole log is parent then branch
+    if (meta.parent && meta.parent.at === undefined && meta.parent.root !== undefined)
+        meta.parent = { at: meta.parent.root, position: (meta.parent.parentCount ?? 0) + (meta.parent.branchCount ?? 0) };
+    return meta;
+}
+export function writeBranchMeta(service, meta, root) {
+    withAncestryLock(() => {
+        if (meta.parent && (!Number.isInteger(meta.parent.position) || meta.parent.position < 0))
+            throw new Error('Invalid branch position');
+        const path = branchMetaPath(service, root);
+        const old = readBranchMeta(service, root);
+        // Tracking can name a different owner from the immediate fork parent. Retain its immutable
+        // view through the existing view dependency mechanism, including empty origin snapshots.
+        for (const origin of [meta.origin, meta.fetchedOrigin])
+            if (origin) {
+                validateHistoryOrigin(origin);
+                checkParent(origin.directory, origin.generation);
+                const descriptor = historyPrefix(readHistoryView(origin.directory, origin.view), origin.position);
+                saveHistoryView(worldPaths(service, root).dir, { ...descriptor, origin: { ...origin, depth: 0 } });
+            }
+        const previousParents = [...(old?.previousParents ?? [])];
+        if (old?.parent?.directory && old.parent.generation)
+            previousParents.push({ directory: old.parent.directory, generation: old.parent.generation });
+        if (previousParents.length)
+            meta = { ...meta, previousParents: [...new Map(previousParents.map(p => [p.directory, p])).values()] };
+        if (meta.parent && !isUrlParent(meta.parent.at)) {
+            const directory = canonicalStatePath(worldPaths(service, meta.parent.at).dir);
+            const view = meta.parent.view ?? captureHistory(service, meta.parent.at).view;
+            const viewDirectory = meta.parent.viewDirectory ?? directory;
+            if (meta.parent.viewDirectory && canonicalStatePath(viewDirectory) !== canonicalStatePath(worldPaths(service, root).dir))
+                throw new Error('Composed history view must belong to this branch');
+            const descriptor = readHistoryView(viewDirectory, view);
+            historyPrefix(descriptor, meta.parent.position);
+            const parent = meta.parent;
+            const generation = pinParent(directory, path, parent.generation);
+            meta = { ...meta, parent: { ...parent, view, at: canonicalStatePath(parent.at), directory, generation } };
+        }
+        if (meta.parent && isUrlParent(meta.parent.at) && !meta.parent.view) {
+            const head = originHead(service, root);
+            if (head)
+                meta = { ...meta, parent: { ...meta.parent, view: head.view, remoteView: head.remoteView } };
+            else if (meta.parent.position === 0) {
+                const empty = captureHistory(service, root);
+                meta = { ...meta, parent: { ...meta.parent, view: empty.view } };
+            }
+            else
+                throw new Error('Origin has no completed immutable history view');
+        }
+        getActiveWorldStore().mkdir(dirname(path));
+        getActiveWorldStore().writeAtomic(path, `${JSON.stringify(meta, null, 2)}\n`);
+        if (meta.parent?.directory && !isUrlParent(meta.parent.at))
+            commitParentPin(meta.parent.directory, path);
+    });
+}
+/** A v1 observed row as an entry: a delta event folds its `changed.*.after`; anything else folds
+ *  nothing and rides along for `listEvents`. An entry row is itself. */
+export function toEntry(row) {
+    if (typeof row.op === 'string')
+        return row;
+    const event = row;
+    const data = (event.data ?? {});
+    const changed = data.changed;
+    const isDelta = typeof event.type === 'string' && event.type.endsWith(DELTA_SUFFIX) && changed !== undefined && typeof changed === 'object';
+    const isEgress = typeof event.type === 'string' && (event.type.endsWith('.write.intent') || event.type.endsWith('.write.result'));
+    // a delta row folds what changed; a flat observed row (a connector's snapshot, a fold of a webhook)
+    // folds its data as the subject's fields — and a `changed` map riding on it (`{ field: { after } }`)
+    // folds its afters over them, so the shape means the same thing on any row; an egress record folds nothing
+    const deltaShaped = changed !== undefined && changed !== null && typeof changed === 'object' && !Array.isArray(changed)
+        && Object.values(changed).every((v) => v !== null && typeof v === 'object' && ('after' in v || 'before' in v));
+    const afters = () => Object.fromEntries(Object.entries(changed).map(([k, v]) => [k, v?.after]));
+    const { changed: _changed, ...flat } = data;
+    const fields = isEgress ? undefined : isDelta ? afters() : deltaShaped ? { ...flat, ...afters() } : data;
+    return {
+        id: event.id, service: event.service, op: 'set', subject: event.subject, occurredAt: event.occurredAt,
+        ...(fields ? { fields } : {}), event,
+        // the default data's rows are the placeholder origin's (docs/concepts/the-model.md#a-branch-is-a-position-not-a-copy, "default data"): a read hides them from the log
+        ...(event.origin === 'virtual' || data.provenance === 'placeholder' ? { provenance: 'placeholder' } : {}),
+    };
+}
+/** An entry as a v1 observed row: its own row when it came from one, else a delta event. */
+export function toEvent(entry) {
+    if (entry.event)
+        return entry.event;
+    const fields = entry.fields ?? {};
+    return {
+        id: entry.id, service: entry.service, type: `${entry.service}.${entry.subject.type}${DELTA_SUFFIX}`, schemaVersion: 1,
+        idempotencyKey: entry.id, occurredAt: entry.occurredAt, observedAt: entry.receipt?.at ?? entry.occurredAt,
+        origin: entry.receipt ? 'external' : 'connector', subject: entry.subject,
+        ...(entry.actor ? { actor: entry.actor } : {}),
+        ...(entry.receipt?.externalId ? { external: { provider: entry.service, id: entry.receipt.externalId, ...(entry.receipt.url ? { url: entry.receipt.url } : {}) } } : {}),
+        data: { changed: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, { after: v }])), ...(entry.receipt ? { receipt: entry.receipt } : {}) },
+    };
+}
+/** This root's own parent-log rows, as entries. */
+function ownParentEntries(service, root) {
+    return readRows(parentLogPath(service, root)).map(toEntry);
+}
+/** This root's own branch-log rows. */
+export function branchEntries(service, root) {
+    return readRows(branchLogPath(service, root));
+}
+/** The parent as this branch sees it: the base world's view at the branch position (its parent
+ *  log to `parentCount`, its branch log to `branchCount`), then everything this root's own parent
+ *  log holds (fetched, refreshed or landed since). An unbranched root is just its own parent log. */
+export function parentEntries(service, root, seen = new Set()) {
+    const view = inheritedHistory(service, root);
+    return [...(view ? historyEntries(view) : []), ...ownParentEntries(service, root)];
+}
+/** The fetched cache of a URL parent's whole log (every entry fetched so far, past the position too). */
+export function originEntries(service, root) {
+    const head = originHead(service, root);
+    return head ? historyEntries(readHistoryView(worldPaths(service, root).dir, head.view)) : readRows(originLogPath(service, root)).map(toEntry);
+}
+/** Extend the cache with one of the parent's entries; deduplicated by id. */
+export function appendOriginEntry(entry, root) {
+    const path = originLogPath(entry.service, root);
+    const store = getActiveWorldStore();
+    store.mkdir(dirname(path));
+    return withAncestryLock(() => store.withLock(`${path}.lock`, () => {
+        if (readRows(path).some((r) => r.id === entry.id))
+            return { appended: false };
+        store.append(path, `${JSON.stringify(entry)}\n`);
+        return { appended: true };
+    }));
+}
+/** Where the parent stands now: the length of its whole log (live at a path, the cache for a URL). */
+export function parentPosition(service, root) {
+    const meta = readBranchMeta(service, root);
+    if (!meta?.parent)
+        return null;
+    return isUrlParent(meta.parent.at) ? originEntries(service, root).length : wholeLog(service, meta.parent.at).length;
+}
+/** Ids the parent holds, including the local ids its landed copies stand for. */
+export function landedIds(parent) {
+    const out = new Set();
+    for (const e of parent) {
+        out.add(e.id);
+        if (e.landsId)
+            out.add(e.landsId);
+    }
+    return out;
+}
+/** The vendor-minted id per local subject: every landed copy that carries `aliasOf`. A local id the
+ *  vendor itself holds names the vendor's subject, never the alias: a World that minted a local id
+ *  before it had observed the vendor's own subject under that id (its tree was behind) must not fold
+ *  the vendor's subject onto the landed one, nor send a caller who addresses the vendor's id there. */
+export function aliasesFrom(parent) {
+    const vendorHeld = new Set();
+    for (const e of parent)
+        if (e.batch !== undefined || e.operation === 'observed' || e.event !== undefined || e.landsId !== undefined)
+            vendorHeld.add(`${e.subject.type}:${e.subject.id}`);
+    const out = new Map();
+    for (const e of parent) {
+        if (!e.aliasOf || e.aliasOf === e.subject.id)
+            continue;
+        const from = `${e.subject.type}:${e.aliasOf}`;
+        if (!vendorHeld.has(from))
+            out.set(from, e.subject.id);
+    }
+    return out;
+}
+const META = new Set(['id', 'type', 'updatedAt']);
+/** Last write per field. `deleted: true` is the tombstone a delete carries; it holds until the subject
+ *  is written again (a create under the same address resurrects it — the write need not say so). */
+function overlay(tree, type, id, fields, at) {
+    const key = `${type}:${id}`;
+    const existing = tree.get(key) ?? { type, id, updatedAt: at, fields: {} };
+    const merged = { ...existing.fields, ...fields };
+    if (existing.fields.deleted === true && fields.deleted !== true)
+        delete merged.deleted;
+    tree.set(key, { ...existing, updatedAt: at, fields: merged });
+}
+/** Fold entries onto a tree, in order: `set` overlays its fields and applies its projection; a
+ *  reverted entry folds nothing; a `confirm` row (v1) folds nothing. `skip` names entries the
+ *  parent already holds. */
+export function foldEntries(tree, entries, skip = new Set()) {
+    const reverted = new Set(entries.filter((e) => e.op === 'revert' && e.revertsActionId).map((e) => e.revertsActionId));
+    for (const e of entries) {
+        if (e.op !== 'set' || reverted.has(e.id) || skip.has(e.id))
+            continue;
+        // a landed copy the vendor did not take (refused by a check, failed at the vendor) is on the log with
+        // its receipt, and not in the tree: the tree holds what the vendor holds or what is still queued
+        if (e.landsId && (e.receipt?.status === 'refused' || e.receipt?.status === 'failed'))
+            continue;
+        if (e.fields)
+            overlay(tree, e.subject.type, e.subject.id, e.fields, e.occurredAt);
+        if (e.projection) {
+            for (const c of e.projection.creates ?? [])
+                overlay(tree, c.type, c.id, c.fields, e.occurredAt);
+            for (const u of e.projection.updates ?? [])
+                overlay(tree, u.type, u.id, u.fields, e.occurredAt);
+            for (const d of e.projection.deletes ?? [])
+                tree.delete(`${d.type}:${d.id}`);
+        }
+    }
+}
+/** Fold aliases: whatever still sits under a local id (a later local update against the id the
+ *  caller holds) folds onto the vendor's row. */
+export function foldAliases(tree, aliases, service, only) {
+    for (const [fromKey, toId] of aliases) {
+        const stray = tree.get(fromKey);
+        if (!stray)
+            continue;
+        overlay(tree, stray.type, toId, stray.fields, stray.updatedAt);
+        tree.delete(fromKey);
+    }
+    // declared references follow the adoption (docs/contributing/architecture.md#alias-aware-lookup-at-the-request-boundary), whatever order the entries folded in
+    if (service !== undefined && aliases.size > 0) {
+        // `only`: an extension's touched subjects, the only ones an earlier fold has not already resolved
+        for (const s of only ? [...only].map((k) => tree.get(k)).filter((held) => held !== undefined) : tree.values()) {
+            const resolved = resolveReferences(service, s.type, s.fields, aliases);
+            if (resolved !== s.fields)
+                s.fields = resolved;
+        }
+    }
+}
+/** The tree as resources: `id`, `type` and `updatedAt` are the SUBJECT's. A resource whose own fields
+ *  carry a different `id`, `type` or `updatedAt` (a Jira issue has a key and a numeric id; a Stripe
+ *  price has a `type` of its own) keeps them BESIDE the row, on a non-enumerable property: a spread,
+ *  `Object.entries`, JSON and a conformance sweep never see them, so a pack that serves the row as it
+ *  stands serves exactly the vendor's fields it wrote; `ownFields` restores them for a pack that wants
+ *  the vendor's own values in the vendor's positions. */
+const OWN = Symbol.for('volter.resource.own');
+export function treeResources(tree) {
+    return [...tree.values()].map((s) => {
+        const out = { id: s.id, type: s.type, updatedAt: s.updatedAt };
+        const own = {};
+        for (const [k, v] of Object.entries(s.fields)) {
+            if (!META.has(k))
+                out[k] = v;
+            else if (v !== undefined && v !== out[k])
+                own[k] = v;
+        }
+        if (Object.keys(own).length)
+            Object.defineProperty(out, OWN, { value: own, enumerable: false });
+        return out;
+    });
+}
+/** A copy of a resource a reader may change: its fields, and the vendor's own id/type/updatedAt it keeps beside them. */
+export function copyResource(r) {
+    const out = { ...r };
+    const own = r[OWN];
+    if (own !== undefined)
+        Object.defineProperty(out, OWN, { value: own, enumerable: false });
+    return out;
+}
+/** A resource's own fields, the vendor's way: the subject's address stripped, its own `id`/`type`/`updatedAt` restored when it had them. */
+export function ownFields(r) {
+    const { id: _id, type: _type, updatedAt: _at, ...rest } = r;
+    const own = (r[OWN] ?? {});
+    // restored first: a vendor's object leads with its id, and a reader's grep may count on the order
+    return { ...(own.id !== undefined ? { id: own.id } : {}), ...(own.type !== undefined ? { type: own.type } : {}), ...rest, ...(own.updatedAt !== undefined ? { updatedAt: own.updatedAt } : {}) };
+}
+export function dropCheckpoint(service, root) { getActiveWorldStore().remove(checkpointPath(service, root)); }
+/** Preserve each ancestor's observed-then-local overlay, including landed IDs and aliases. */
+export function foldHistory(entries, layout, service) {
+    const baseCount = layout.base ? historyLength(layout.base) : 0;
+    const tree = layout.base ? foldHistory(entries.slice(0, baseCount), layout.base, service) : new Map();
+    const parent = entries.slice(0, baseCount + layout.parent);
+    foldEntries(tree, parent.slice(baseCount));
+    foldEntries(tree, entries.slice(baseCount + layout.parent, baseCount + layout.parent + layout.branch), landedIds(parent));
+    foldAliases(tree, aliasesFrom(parent), service);
+    return tree;
+}
+export function readTree(service, root, opts = {}) {
+    return treeResources(readTreeMap(service, root, opts));
+}
+/** The upstream view for observation diffing, without this root's local overlay. Inherited
+ *  history keeps its own layout: an ancestor's local writes are part of our pinned base. */
+export function readParentTreeMap(service, root) {
+    return withAncestryLock(() => {
+        const inherited = inheritedHistory(service, root);
+        const own = ownParentEntries(service, root);
+        return foldHistory([...(inherited ? historyEntries(inherited) : []), ...own], {
+            ...(inherited ? { base: inherited.layout } : {}), parent: own.length, branch: 0,
+        }, service);
+    });
+}
+const treeMemos = new WeakMap();
+/** How many extensions a memo remembers the touched subjects of; a projection further behind refolds. */
+const TREE_STEPS_KEPT = 64;
+function statKey(path) { const s = getActiveWorldStore().stat(path); return s ? `${s.size}:${s.mtimeMs}` : '-'; }
+/** What a service's PARENT side at `root` is folded from (its parent log, branch.json and inherited history), as one
+ *  string: while it stands, its aliases and landed ids are the same, whatever the branch's own log does. */
+export function parentStamp(service, root) { return parentKeyOf(service, root); }
+function parentKeyOf(service, root) { return `${statKey(parentLogPath(service, root))}|${getActiveWorldStore().read(branchMetaPath(service, root)) ?? ''}|${inheritedHistoryKey(service, root)}`; }
+/** What a service's tree (and every subject's history) at `root` is folded from, as one string: while it
+ *  stands, nothing was written. A pack that projects the tree into its own state memoizes on it. */
+export function treeStamp(service, root) { return `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}`; }
+const cloneTree = (tree) => new Map([...tree].map(([k, s]) => [k, { ...s, fields: { ...s.fields } }]));
+const memoStamp = (m) => `${m.parentKey}#${m.branchKey}`;
+/** The subject keys entries write (as foldEntries folds them), and the vendor rows an alias moves a local one onto. */
+function touchedKeys(entries, aliases) {
+    const keys = new Set();
+    for (const e of entries) {
+        if (e.fields)
+            keys.add(`${e.subject.type}:${e.subject.id}`);
+        for (const c of e.projection?.creates ?? [])
+            keys.add(`${c.type}:${c.id}`);
+        for (const u of e.projection?.updates ?? [])
+            keys.add(`${u.type}:${u.id}`);
+        for (const d of e.projection?.deletes ?? [])
+            keys.add(`${d.type}:${d.id}`);
+    }
+    for (const key of [...keys]) {
+        const to = aliases.get(key);
+        if (to !== undefined)
+            keys.add(`${key.slice(0, key.indexOf(':'))}:${to}`);
+    }
+    return keys;
+}
+/** The keys `fold` inserts into `tree` (a Map puts an inserted key at its end, so a key deleted and set again moves
+ *  there too), in the order they then stand, each once. */
+function insertionsDuring(tree, fold) {
+    const order = new Map();
+    const own = tree;
+    own.set = (key, value) => { if (!tree.has(key)) {
+        order.delete(key);
+        order.set(key, true);
+    } return Map.prototype.set.call(tree, key, value); };
+    try {
+        fold();
+    }
+    finally {
+        delete own.set;
+    }
+    return [...order.keys()].filter((k) => tree.has(k));
+}
+export function readTreeMap(service, root, opts = {}) {
+    if (opts.until !== undefined || opts.at !== undefined || opts.view !== undefined)
+        return readTreeMapFull(service, root, opts);
+    const read = currentTree(service, root);
+    return read.memo ? cloneTree(read.tree) : read.tree;
+}
+/** The current tree: the memo's own (never to be handed out) when the memo holds it, else a fresh fold. */
+function currentTree(service, root) {
+    const store = getActiveWorldStore();
+    let memos = treeMemos.get(store);
+    if (!memos) {
+        memos = new Map();
+        treeMemos.set(store, memos);
+    }
+    const slot = `${service}\u0000${root ?? ''}`;
+    // A hit needs no coordinator: a memo is only ever stored from a fold made under it, and while the
+    // facts still match that fold, nothing was written since. A writer mid-batch has moved them.
+    const unlocked = memos.get(slot);
+    if (unlocked && unlocked.parentKey === parentKeyOf(service, root) && unlocked.branchKey === statKey(branchLogPath(service, root)))
+        return { tree: unlocked.tree, memo: unlocked };
+    return withAncestryLock(() => {
+        const parentKey = parentKeyOf(service, root);
+        const branchKey = statKey(branchLogPath(service, root));
+        const held = memos.get(slot);
+        if (held && held.parentKey === parentKey && held.branchKey === branchKey)
+            return { tree: held.tree, memo: held };
+        const branch = branchEntries(service, root);
+        const last = (entries) => (entries.length ? entries[entries.length - 1].id : null);
+        if (held && held.parentKey === parentKey && branch.length >= held.branchCount
+            && (held.branchCount === 0 ? held.lastBranchId === null : branch[held.branchCount - 1]?.id === held.lastBranchId)
+            && !branch.slice(held.branchCount).some((e) => e.op === 'revert')) {
+            const fresh = branch.slice(held.branchCount);
+            const keys = touchedKeys(fresh, held.aliases);
+            const from = memoStamp(held);
+            let appended;
+            try {
+                appended = insertionsDuring(held.tree, () => {
+                    foldEntries(held.tree, fresh, held.landed);
+                    foldAliases(held.tree, held.aliases, service, keys);
+                });
+            }
+            catch (error) {
+                memos.delete(slot);
+                throw error;
+            } // a half-folded memo is never read again
+            Object.assign(held, { branchKey, branchCount: branch.length, lastBranchId: last(branch) });
+            held.steps.push({ from, to: memoStamp(held), keys, appended });
+            if (held.steps.length > TREE_STEPS_KEPT)
+                held.steps.splice(0, held.steps.length - TREE_STEPS_KEPT);
+            return { tree: held.tree, memo: held };
+        }
+        const tree = readTreeMapFull(service, root);
+        const parent = parentEntries(service, root);
+        // the facts are read again after the fold: a write that raced it leaves nothing memoized
+        if (parentKeyOf(service, root) === parentKey && statKey(branchLogPath(service, root)) === branchKey) {
+            const memo = { parentKey, branchKey, branchCount: branch.length, lastBranchId: last(branch), landed: landedIds(parent), aliases: aliasesFrom(parent), tree, steps: [] };
+            memos.set(slot, memo);
+            return { tree, memo };
+        }
+        return { tree };
+    });
+}
+/** What changed in a service's tree since `since` (a `treeStamp` an earlier read was made at): the subjects
+ *  written since, as resources; the keys (`type:id`) of those no longer in the tree; and, of the changed, the keys
+ *  now at the tree's end in the order they stand there (new to the tree, or deleted and made again), which a
+ *  projection kept in the tree's order moves to its end in that order, updating the rest where they stand.
+ *  `undefined` when this process cannot say (no memo, the parent moved, a revert, or `since` older than the memo
+ *  remembers): the caller refolds. `stamp` is the state the answer brings the caller to. */
+export function treeChangesSince(service, root, since) {
+    const { tree, memo } = currentTree(service, root);
+    if (!memo)
+        return undefined;
+    const stamp = memoStamp(memo);
+    if (since === stamp)
+        return { stamp, changed: [], removed: [], appended: [] };
+    const first = memo.steps.findIndex((s) => s.from === since);
+    if (first < 0)
+        return undefined;
+    const keys = new Set();
+    const order = new Map();
+    for (let i = first; i < memo.steps.length; i++) {
+        if (i > first && memo.steps[i].from !== memo.steps[i - 1].to)
+            return undefined;
+        for (const k of memo.steps[i].keys)
+            keys.add(k);
+        for (const k of memo.steps[i].appended) {
+            order.delete(k);
+            order.set(k, true);
+        }
+    }
+    if (memo.steps[memo.steps.length - 1].to !== stamp)
+        return undefined;
+    const present = new Map();
+    const removed = [];
+    for (const k of keys) {
+        const s = tree.get(k);
+        if (s)
+            present.set(k, s);
+        else
+            removed.push(k);
+    }
+    return { stamp, changed: treeResources(present), removed, appended: [...order.keys()].filter((k) => tree.has(k)) };
+}
+function readTreeMapFull(service, root, opts = {}) {
+    return withAncestryLock(() => {
+        if (opts.at !== undefined || opts.view !== undefined) {
+            const view = opts.view ? readHistoryView(worldPaths(service, root).dir, opts.view) : captureHistory(service, root).descriptor;
+            const at = opts.at ?? historyLength(view.layout);
+            const entries = historyEntries(view);
+            if (at > 0 && at < entries.length && entries[at]?.batch && entries[at]?.batch === entries[at - 1]?.batch) {
+                let from = at;
+                let to = at;
+                const batch = entries[at].batch;
+                while (from > 0 && entries[from - 1]?.batch === batch)
+                    from--;
+                while (to < entries.length && entries[to]?.batch === batch)
+                    to++;
+                throw new Error(`position ${at} falls inside observation ${batch} — use ${from} or ${to}`);
+            }
+            const prefix = historyPrefix(view, at);
+            return foldHistory(entries.slice(0, at), prefix.layout, service);
+        }
+        // a cold read (no memo) trusts a checkpoint cut at exactly these log facts without re-hashing the logs
+        const facts = opts.until === undefined ? `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}` : null;
+        if (facts !== null) {
+            const held = getActiveWorldStore().read(checkpointPath(service, root));
+            const cut = held === null ? null : JSON.parse(held);
+            if (cut?.facts === facts)
+                return new Map(cut.subjects.map(s => [`${s.type}:${s.id}`, { ...s, fields: { ...s.fields } }]));
+        }
+        const inherited = inheritedHistory(service, root);
+        const base = inherited ? historyEntries(inherited) : [];
+        const own = ownParentEntries(service, root);
+        const parent = [...base, ...own];
+        const branchAll = branchEntries(service, root);
+        const until = opts.until === undefined ? -1 : branchAll.findIndex(e => e.id === opts.until);
+        const branch = until < 0 ? branchAll : branchAll.slice(0, until);
+        const parentDigest = hashFieldValue({ inherited, own });
+        const branchDigest = hashFieldValue(branch);
+        const raw = opts.until === undefined ? getActiveWorldStore().read(checkpointPath(service, root)) : null;
+        const cp = raw === null ? null : JSON.parse(raw);
+        if (cp?.parentDigest === parentDigest && cp.branchDigest === branchDigest)
+            return new Map(cp.subjects.map(s => [`${s.type}:${s.id}`, { ...s, fields: { ...s.fields } }]));
+        const layout = { ...(inherited ? { base: inherited.layout } : {}), parent: own.length, branch: branch.length };
+        const incremental = cp?.parentDigest === parentDigest && cp.branchCount <= branch.length && hashFieldValue(branch.slice(0, cp.branchCount)) === cp.branchDigest && !branch.slice(cp.branchCount).some(e => e.op === 'revert');
+        const tree = incremental ? new Map(cp.subjects.map(s => [`${s.type}:${s.id}`, { ...s, fields: { ...s.fields } }])) : foldHistory([...parent, ...branch], layout, service);
+        if (incremental) {
+            foldEntries(tree, branch.slice(cp.branchCount), landedIds(parent));
+            foldAliases(tree, aliasesFrom(parent), service);
+        }
+        if (opts.until === undefined && parent.length + branch.length > CHECKPOINT_EVERY) {
+            // the facts are the ones this fold read; recorded only if no write moved them while it folded
+            const now = `${parentKeyOf(service, root)}#${statKey(branchLogPath(service, root))}`;
+            getActiveWorldStore().writeAtomic(checkpointPath(service, root), JSON.stringify({ parentDigest, branchDigest, branchCount: branch.length, subjects: [...tree.values()], ...(now === facts ? { facts } : {}) }));
+        }
+        return tree;
+    });
+}
+export function cutCheckpoint(service, root) {
+    return withAncestryLock(() => {
+        dropCheckpoint(service, root);
+        const subjects = [...readTreeMap(service, root).values()];
+        const inherited = inheritedHistory(service, root);
+        const own = ownParentEntries(service, root);
+        getActiveWorldStore().writeAtomic(checkpointPath(service, root), JSON.stringify({ parentDigest: hashFieldValue({ inherited, own }), branchDigest: hashFieldValue(branchEntries(service, root)), branchCount: branchEntries(service, root).length, subjects }));
+    });
+}
+/** The branch's entries the parent does not hold: `set` rows, not reverted, not landed. */
+export function unpushedEntries(service, root) {
+    const landed = landedIds(parentEntries(service, root));
+    const branch = branchEntries(service, root);
+    const reverted = new Set(branch.filter((e) => e.op === 'revert' && e.revertsActionId).map((e) => e.revertsActionId));
+    return branch.filter((e) => e.op === 'set' && !reverted.has(e.id) && !landed.has(e.id));
+}
+/** The position a branch is cut at: how far the parent view and the branch log reach right now. */
+/** THE POSITION (contract "Just like Neon", 2): where this twin's whole log stands — one number, the
+ *  count of entries, parent view then branch. Durable cuts pair it with an immutable view ID. */
+export function position(service, root) {
+    return parentEntries(service, root).length + branchEntries(service, root).length;
+}
+/** The position of a twin's log at an instant: the entries that had occurred by then. */
+export function positionAt(service, instant, root, view) {
+    const t = Date.parse(instant);
+    const log = view ? historyEntries(readHistoryView(worldPaths(service, root).dir, view)) : wholeLog(service, root);
+    let n = 0;
+    for (const e of log) {
+        if (historyEntryTime(e) <= t)
+            n += 1;
+        else
+            break;
+    }
+    if (log.slice(n).some(e => historyEntryTime(e) <= t))
+        throw new Error('This instant selects noncontiguous history; use historyAtInstant to capture a view instead of a numeric offset');
+    // an observation is atomic: an instant inside one look resolves to the look's end
+    while (n > 0 && n < log.length && log[n].batch !== undefined && log[n].batch === log[n - 1].batch)
+        n += 1;
+    return n;
+}
+/** The batch a position would split, if any: `position` entries taken, and the next entry belongs to the
+ *  same observation as the last one taken. Answers the boundaries a caller may use instead. */
+export function splitsBatch(service, position, root) {
+    const log = wholeLog(service, root);
+    if (position <= 0 || position >= log.length)
+        return null;
+    const batch = log[position].batch;
+    if (batch === undefined || log[position - 1].batch !== batch)
+        return null;
+    let from = position - 1;
+    while (from > 0 && log[from - 1].batch === batch)
+        from -= 1;
+    let to = position;
+    while (to < log.length && log[to].batch === batch)
+        to += 1;
+    return { batch, from, to };
+}
+/** Refuse a position inside an observation, naming the boundaries. */
+export function assertBatchBoundary(service, position, root) {
+    const split = splitsBatch(service, position, root);
+    if (split)
+        throw new Error(`position ${position} falls inside observation ${split.batch} (entries ${split.from + 1}–${split.to}); an observation is atomic — use ${split.from} or ${split.to}`);
+}
+/** A landed copy of `entry` for the parent log: the receipt on it, the vendor's id as its subject
+ *  when one was minted. Deterministic id, so landing twice is the same row. */
+export function landedCopy(entry, receipt, opts = {}) {
+    const subject = opts.subject ?? entry.subject;
+    const adopted = opts.vendorSubjectId !== undefined && opts.vendorSubjectId !== '' && opts.vendorSubjectId !== subject.id ? { type: subject.type, id: opts.vendorSubjectId } : subject;
+    const fields = opts.fields ?? entry.fields ?? {};
+    const contentHash = hashFieldValue({ landsId: entry.id, subject: adopted, fields, status: receipt.status });
+    const { event: _event, receipt: _receipt, aliasOf: _aliasOf, landsId: _landsId, ...body } = entry;
+    return {
+        ...body,
+        id: `landed:${entry.service}:${adopted.type}:${adopted.id}:${entry.id}:${contentHash}`,
+        op: 'set', subject: adopted, fields, landsId: entry.id,
+        ...(adopted.id !== subject.id ? { aliasOf: subject.id } : {}),
+        receipt,
+    };
+}
+/** Append an entry to this root's own parent log — what fetch does with what origin sends, and what
+ *  a served world does with nothing (its pushes land on its branch log). Deduplicated by id. */
+// The parent log's entry ids, per store and path, valid while the file's size and version are the ones
+// recorded (WorldStore.stat changes on any writer's append): a batch of appends dedupes against an index,
+// not by re-parsing the whole log each time.
+const parentIdIndex = new WeakMap();
+export function appendParentEntry(entry, root) {
+    const path = parentLogPath(entry.service, root);
+    const store = getActiveWorldStore();
+    store.mkdir(dirname(path));
+    return withAncestryLock(() => store.withLock(`${path}.lock`, () => {
+        let indexes = parentIdIndex.get(store);
+        if (!indexes) {
+            indexes = new Map();
+            parentIdIndex.set(store, indexes);
+        }
+        let index = indexes.get(path);
+        if (!index || index.key !== statKey(path)) {
+            index = { key: statKey(path), ids: new Set(readRows(path).flatMap((r) => (typeof r.id === 'string' ? [r.id] : []))) };
+            indexes.set(path, index);
+        }
+        if (index.ids.has(entry.id))
+            return { appended: false };
+        store.append(path, `${JSON.stringify(entry)}\n`);
+        index.ids.add(entry.id);
+        index.key = statKey(path);
+        return { appended: true };
+    }));
+}
+/** The whole log of a twin as a served world hands it out: the parent view, then the branch's own
+ *  entries, one sequence with a position. A clone's parent is exactly this. */
+export function wholeLog(service, root) {
+    return [...parentEntries(service, root), ...branchEntries(service, root)];
+}
+/**
+ * REBASE a branch onto its base's current position (contract: "rebase replays the branch's
+ * entries over a newer base, conflicts per subject and field"). A branch is a pointer, so the
+ * base moving is invisible until this: the pointer advances to the base's present position, the
+ * branch's own entries stay in place and now fold over the moved base, and every entry whose
+ * preconditions no longer hold against the new parent tree is named as a conflict — data on the
+ * result, never a stop. An unbranched world (no pointer) has nothing to rebase.
+ */
+export function rebaseBranch(service, root, opts = {}) {
+    return withAncestryLock(() => {
+        const meta = readBranchMeta(service, root);
+        if (!meta?.parent)
+            return { moved: false, from: 0, to: 0, conflicts: [] };
+        if (opts.origin && !meta.origin)
+            throw new Error('This local fork has no tracked origin; clone the origin before branching');
+        const from = meta.parent.position;
+        let tracked = meta.origin && (opts.origin || meta.origin.depth === 0) ? meta.fetchedOrigin ?? { ...meta.origin, depth: 0 } : undefined;
+        if (tracked && !opts.origin && !isUrlParent(tracked.at)) {
+            const live = captureHistory(service, tracked.at);
+            tracked = { ...tracked, directory: live.descriptor.owner.directory, generation: live.descriptor.owner.generation, view: live.view, position: live.position };
+        }
+        if (tracked && !meta.origin.incomplete && tracked.directory === meta.origin.directory && tracked.view === meta.origin.view && tracked.position === meta.origin.position && tracked.remoteView === meta.origin.remoteView) {
+            if (meta.fetchedOrigin)
+                writeBranchMeta(service, { ...meta, fetchedOrigin: undefined }, root);
+            return { moved: false, from, to: from, conflicts: [] };
+        }
+        const head = tracked ?? (isUrlParent(meta.parent.at) ? originHead(service, root) : captureHistory(service, meta.parent.at));
+        if (!head)
+            throw new Error('Origin has no completed immutable history view');
+        const directory = isUrlParent(meta.parent.at) ? worldPaths(service, root).dir : worldPaths(service, meta.parent.at).dir;
+        const previous = inheritedHistory(service, root);
+        const next = tracked ? replaceHistoryOrigin(previous, meta.origin, tracked) : readHistoryView(directory, head.view);
+        const nextView = tracked ? saveHistoryView(worldPaths(service, root).dir, next) : head.view;
+        const to = historyLength(next.layout);
+        const moved = to !== from || nextView !== meta.parent.view;
+        // Compare the evaluated old and new views, including removals and reordered layers.
+        const before = historyEntries(previous);
+        const since = historyChanges(service, previous, next);
+        // only a subject that EXISTED at this branch's position can conflict: two branches each minting the
+        // same local id for different records is not a disagreement (the vendor mints the real id)
+        const existed = new Set(before.filter((e) => e.op === 'set').flatMap((e) => [`${e.subject.type}:${e.subject.id}`, ...(e.aliasOf ? [`${e.subject.type}:${e.aliasOf}`] : [])]));
+        // conflicts: a field this branch set that the parent set since, to something else — named by
+        // entry, subject and field (contract "Drift and rebase in v2")
+        const stable = (v) => JSON.stringify(v) ?? 'undefined';
+        // a field both sides set to an INSTANT (updated_at, created) is when each wrote, not what: never a conflict
+        const instant = (v) => typeof v === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d/.test(v) && Number.isFinite(Date.parse(v));
+        const currentAliases = aliasesFrom(historyEntries(next));
+        const conflicts = [];
+        for (const e of branchEntries(service, root)) {
+            if (e.op !== 'set' || !e.fields || !existed.has(`${e.subject.type}:${e.subject.id}`))
+                continue;
+            const fields = resolveReferences(service, e.subject.type, e.fields, currentAliases);
+            for (const p of since) {
+                if (p.op !== 'set' || !p.fields || p.subject.type !== e.subject.type || (p.subject.id !== e.subject.id && p.aliasOf !== e.subject.id))
+                    continue;
+                if (p.fields.deleted === true && fields.deleted !== true)
+                    conflicts.push({ entryId: e.id, subject: e.subject, field: 'deleted', op: 'exists', expected: true, actual: false });
+                for (const [field, value] of Object.entries(p.fields))
+                    if (field in fields && stable(fields[field]) !== stable(value) && !(instant(value) && instant(fields[field])))
+                        conflicts.push({ entryId: e.id, subject: e.subject, field, op: 'set', expected: fields[field], actual: value });
+            }
+        }
+        if (moved) {
+            const { viewDirectory: _oldViewDirectory, ...parent } = meta.parent;
+            writeBranchMeta(service, { ...meta, fetchedOrigin: undefined, origin: tracked ? { ...tracked, depth: meta.origin.depth } : next.origin, parent: { ...parent, position: to, view: nextView, ...(tracked ? { viewDirectory: canonicalStatePath(worldPaths(service, root).dir) } : {}), ...('remoteView' in head ? { remoteView: head.remoteView } : {}) } }, root);
+            dropCheckpoint(service, root);
+        }
+        return { moved, from, to, conflicts };
+    });
+}
+/**
+ * HISTORY through the kernel: every entry that touched a subject (or every subject of a type), parent
+ * log then branch log, in order, with reverted entries dropped and landed copies shown once. A pack
+ * that serves a changelog (Jira's), or must never reuse an id it once minted, reads this — never a
+ * log file. Each entry's `fields` is what it set; the fold is the reader's.
+ */
+export function subjectHistory(service, subject, root) {
+    const parent = parentEntries(service, root);
+    const held = landedIds(parent);
+    const branch = branchEntries(service, root);
+    const reverted = new Set(branch.filter((e) => e.op === 'revert' && e.revertsActionId).map((e) => e.revertsActionId));
+    const touches = (e) => e.op === 'set' && e.subject.type === subject.type && (subject.id === undefined || e.subject.id === subject.id || e.aliasOf === subject.id);
+    return [...parent.filter((e) => touches(e) && e.fields !== undefined), ...branch.filter((e) => touches(e) && !reverted.has(e.id) && !held.has(e.id))];
+}