@north-light/api 0.3.580 → 0.3.587

package/dist/core/graph/documents.js

@@ -0,0 +1,653 @@
+/** Documents: write, CAS edit, revisions and heads, links per revision, record fields, move,
+ *  delete, history, read, and the two import paths (migration, repo sync). Every act records
+ *  its actor's `acted-on` edge and watch and publishes its event in the caller's transaction. */
+import { randomUUID } from 'node:crypto';
+import { CrtrError, notFound, usage } from '../errors.js';
+import { ExitCode } from '../../types.js';
+import { get as getBody, getMany as getBodies, put as putBody } from './bodies.js';
+import { dropUnresolved, linksOf, recordActedOn, setLinks, setUnresolved, unresolvedLinksCouldName } from './edges.js';
+import { publish } from './events.js';
+import { readableOrDeleted, resolveName } from './names.js';
+import { createObject, getById } from './objects.js';
+import { liveLookups, readerForNode, readerForObject } from './reader.js';
+import { replaceRules, setRulesOwner } from './rules.js';
+import { recordWatch } from './watches.js';
+import { withCanvasWrite } from '../canvas/db.js';
+import { PURGE_RETENTION_MS } from '../storage/purge.js';
+import { filterAsync, forEachAsync, mapAsync } from '../async-array.js';
+import { check, resolveReader, userOf } from '../permissions/evaluator.js';
+import { missingMemoryScope } from '../permissions/ceiling.js';
+import { deleteFact, parseSubject, writeActsFor, writeFact } from '../permissions/facts.js';
+import { PermissionError } from '../permissions/errors.js';
+// ── shared helpers ─────────────────────────────────────────────────────────
+/** The object a reader acts as: its node, its app, or the person. */
+export function actorOf(reader) {
+    return reader.class === 'node' ? reader.node : reader.class === 'app' ? reader.app : reader.class === 'object' ? reader.object : reader.person;
+}
+async function actingOf(db, reader) {
+    const forUser = `user:${await userOf(db, reader)}`;
+    if (reader.class === 'person')
+        return { app: null, for: forUser };
+    const identity = await db.prepare(`SELECT external_id FROM identities WHERE object = ? AND scheme = 'app'`).get(reader.app.id);
+    return { app: identity?.external_id ?? null, for: forUser };
+}
+function conflict(message, details) {
+    return new CrtrError('conflict', message, ExitCode.GENERAL, details);
+}
+function assertDocument(doc) {
+    if (doc.type !== 'document')
+        throw usage(`${doc.type} ${doc.id} is not a document`);
+}
+/** The type of the top of the object's owner chain (its own type when it has no owner): `repo` for anything a repo owns. */
+async function spaceType(db, object) {
+    const top = await db.prepare(`WITH RECURSIVE chain(id, owner, type, depth) AS (
+      SELECT id, owner, type, 0 FROM objects WHERE id = ?
+      UNION ALL
+      SELECT o.id, o.owner, o.type, c.depth + 1 FROM objects o JOIN chain c ON o.id = c.owner WHERE c.depth < 12
+    ) SELECT type FROM chain ORDER BY depth DESC LIMIT 1`).get(object.id);
+    return top?.type ?? object.type;
+}
+/** PUBLIC: a repo owns only public documents. */
+async function assertPublicInRepo(db, owner, privacy) {
+    if (privacy !== 'public' && await spaceType(db, owner) === 'repo') {
+        throw usage(`a repo owns only public documents; ${owner.name} cannot own a ${privacy} one`, { rule: 'repo-public-only', next: 'Write it as public, or give it another owner (your own documents can carry `if: {repo: <handle>}`).' });
+    }
+}
+async function assertNameFree(db, owner, name, except) {
+    if (name.trim() === '' || name !== name.trim())
+        throw usage(`invalid document name ${JSON.stringify(name)}`);
+    const held = await db.prepare(`SELECT id FROM objects WHERE (type = 'document' OR strpos(type, '.') > 0) AND owner = ? AND name = ? AND deleted_at IS NULL AND home_machine IS NULL`)
+        .get(owner.id, name);
+    if (held && held.id !== except?.id)
+        throw conflict(`${owner.name} already has a document named ${name}`, { name, holder: held.id });
+}
+async function readable(db, reader, doc) {
+    if (!await check(db, reader, 'read', doc.id))
+        throw notFound(`no document ${doc.id}`);
+}
+function scopeMissing(scope) {
+    return new CrtrError('scope_missing', `missing scope ${scope}`, ExitCode.GENERAL, { scope });
+}
+async function changeable(db, reader, doc) {
+    await readable(db, reader, doc);
+    const { source_path } = await documentRecord(db, doc);
+    if (source_path !== null) {
+        throw new CrtrError('forbidden', `${doc.name} is a built-in document shipped by a package; \`crtr doc\` cannot change it`, ExitCode.GENERAL, {
+            id: doc.id,
+            next: 'Edit it in the source repository of the package that ships it (for crtr\'s own documents, the crouter repo), not with `crtr doc`.',
+        });
+    }
+    const missing = await missingMemoryScope(db, reader, doc.id, 'rw');
+    if (missing !== null)
+        throw scopeMissing(missing);
+    if (!await check(db, reader, 'edit', doc.id))
+        throw new CrtrError('forbidden', `you cannot change ${doc.name}`, ExitCode.GENERAL, { id: doc.id });
+}
+async function toRevision(db, raw) {
+    const parents = await db.prepare(`SELECT p.rev_id FROM revision_parents rp JOIN revisions p ON p.rev_id = rp.parent
+    WHERE rp.child = ? ORDER BY p.rev_id`).all(raw.rev_id);
+    return {
+        rev_id: raw.rev_id, seq: raw.seq, number: raw.number, body_hash: raw.body_hash,
+        author: raw.author,
+        rationale: raw.rationale, verbatim: raw.verbatim === 1, created_at: raw.created_at,
+        acting_app: raw.acting_app, acting_for: raw.acting_for, parents: parents.map((p) => p.rev_id),
+    };
+}
+/** Head revisions (no child), highest number first. More than one means the document needs a merge. */
+export async function heads(db, doc) {
+    const raws = await db.prepare(`SELECT * FROM revisions r WHERE r.document = ?
+    AND NOT EXISTS (SELECT 1 FROM revision_parents p WHERE p.parent = r.rev_id) ORDER BY r.number DESC, r.rev_id`).all(doc.id);
+    return (await mapAsync(raws, async (r) => await toRevision(db, r)));
+}
+function headsKeyOf(revs) {
+    return revs.map((r) => r.rev_id).sort().join(',');
+}
+export async function documentRecord(db, doc) {
+    const row = await db.prepare('SELECT * FROM documents WHERE object = ?').get(doc.id);
+    if (!row)
+        throw notFound(`no document record for ${doc.id}`);
+    return {
+        summary: row['summary'], heads_key: row['heads_key'], revision: row['revision'],
+        why_it_exists: row['why_it_exists'], unlisted: row['unlisted'] === 1,
+        lint_ignore: row['lint_ignore_json'] === null ? null : JSON.parse(row['lint_ignore_json']),
+        extensions: row['extensions_json'] === null ? null : JSON.parse(row['extensions_json']),
+        source_path: row['source_path'],
+    };
+}
+async function insertRevision(db, doc, rev) {
+    const raw = await db.prepare(`INSERT INTO revisions (document, rev_id, number, body_hash, author, rationale, verbatim, created_at, acting_app, acting_for)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`).get(doc.id, rev.rev_id ?? randomUUID(), rev.number, rev.body_hash, rev.author?.id ?? null, rev.rationale, rev.verbatim ? 1 : 0, rev.created_at ?? new Date().toISOString(), rev.acting?.app ?? null, rev.acting?.for ?? null);
+    const link = db.prepare('INSERT INTO revision_parents (child, parent) VALUES (?, ?)');
+    for (const parent of rev.parents)
+        await link.run(raw.rev_id, parent);
+    return raw;
+}
+/** The `[[name]]` links a body names, in order, each once. */
+export function linksIn(body) {
+    const out = new Set();
+    for (const m of body.matchAll(/\[\[([^[\]\n]+?)\]\]/g))
+        out.add(m[1].trim());
+    return [...out];
+}
+/** Resolve each of `names` in `reader`'s view. A name that resolves to nothing or to several objects stays
+ *  text and is returned in `unresolved`; one that may live on another runtime is neither linked nor reported. */
+async function resolveLinks(db, reader, names) {
+    const links = [];
+    const unresolved = [];
+    for (const name of names) {
+        const hit = await resolveName(db, reader, name);
+        if ('object' in hit)
+            links.push({ written_as: name, dst: hit.object });
+        else if ('deleted' in hit)
+            links.push({ written_as: name, dst: hit.deleted });
+        else if (!('remote' in hit))
+            unresolved.push(name);
+    }
+    return { links, unresolved };
+}
+/** Derive the document's `links-to` edges from `body`, resolving each name in the writer's
+ *  view. A name that resolves to nothing or to several objects stays text and is returned,
+ *  and remembered so {@link linkNewlyNamed} can link it when a document by that name appears;
+ *  one that may live on another runtime is neither linked nor reported. */
+export async function setRevisionLinks(db, reader, doc, body) {
+    const { links, unresolved } = await resolveLinks(db, reader, linksIn(body));
+    await collectUnlinked(db, await setLinks(db, doc, links));
+    await setUnresolved(db, doc, unresolved);
+    return unresolved;
+}
+/** `target` has just come into existence or gained a name. Every live document whose current revision holds an
+ *  unresolved link that could name it re-resolves that link in its OWNER's view (not the caller's); the link gains its
+ *  edge only when the name now resolves to `target`. A name that is still partial, ambiguous or resolves elsewhere stays unresolved. */
+async function linkNewlyNamed(db, target, reposFn) {
+    const bySource = new Map();
+    for (const { src, name } of await unresolvedLinksCouldName(db, target.name, target.id))
+        bySource.set(src, [...bySource.get(src) ?? [], name]);
+    for (const [srcId, names] of bySource) {
+        const src = await getById(db, srcId);
+        const owner = src?.owner == null ? null : await getById(db, src.owner);
+        if (!src || src.deleted_at || src.home_machine !== null || !owner || owner.deleted_at)
+            continue;
+        const view = owner.type === 'node'
+            ? await readerForNode(db, owner.id, reposFn ?? (async () => []), liveLookups(db), true)
+            : await readerForObject(db, src, reposFn);
+        const gained = (await resolveLinks(db, view, names)).links.filter((l) => l.dst.id === target.id);
+        if (gained.length === 0)
+            continue;
+        await setLinks(db, src, [...await linksOf(db, src), ...gained]);
+        await dropUnresolved(db, src, gained.map((l) => l.written_as));
+    }
+}
+/** The handle a link names `owner` by: a node's id, the owner's handle, or
+ *  `<type>:<handle>` when another owner type sharing that handle also holds a
+ *  live document named `name`, so the plain form would be ambiguous. */
+async function ownerPrefix(db, owner, name) {
+    if (owner.type === 'node')
+        return owner.id;
+    const shared = await db.prepare(`SELECT 1 FROM objects o JOIN objects d ON d.owner = o.id
+    WHERE o.name = ? AND o.type <> ? AND o.type IN ('person','app','repo','profile')
+      AND d.type = 'document' AND d.name = ? AND d.deleted_at IS NULL LIMIT 1`).get(owner.name, owner.type, name);
+    return shared ? `${owner.type}:${owner.name}` : owner.name;
+}
+/** `body` with each `[[link]]` the document's `links-to` edges resolved shown under its target's
+ *  current name, so a rename rewrites no stored body yet every read shows the new name (spec §4).
+ *  A link written as the target's id, or to a deleted target, stays as written. */
+export async function withCurrentNames(db, doc, body) {
+    const rows = await db.prepare(`SELECT e.written_as, o.* FROM edges e JOIN objects o ON o.id = e.dst
+    WHERE e.type = 'links-to' AND e.src = ? AND e.written_as IS NOT NULL`).all(doc.id);
+    if (rows.length === 0)
+        return body;
+    const current = new Map();
+    for (const target of rows) {
+        if (target.deleted_at || target.written_as === target.id)
+            continue;
+        const bare = !target.written_as.includes('/');
+        if (bare && target.name === target.written_as)
+            continue;
+        const owner = target.owner === null ? null : await getById(db, target.owner);
+        const full = owner ? `${await ownerPrefix(db, owner, target.name)}/${target.name}` : target.name;
+        const name = bare && target.owner === doc.owner ? target.name : full;
+        if (name !== target.written_as)
+            current.set(target.written_as, name);
+    }
+    if (current.size === 0)
+        return body;
+    return body.replace(/\[\[([^[\]\n]+?)\]\]/g, (whole, inner) => {
+        const name = current.get(inner.trim());
+        return name === undefined ? whole : `[[${name}]]`;
+    });
+}
+/** Write the record fields that are present; `null` clears a nullable one. Rules are
+ *  replaced when given. Does not publish; callers publish the act the fields belong to. */
+export async function applyDocumentFields(db, doc, fields) {
+    if (fields.preview !== undefined) {
+        if (fields.preview.trim() === '')
+            throw usage('a document needs a preview', { field: 'preview' });
+        await db.prepare('UPDATE objects SET preview = ? WHERE id = ?').run(fields.preview, doc.id);
+    }
+    if (fields.privacy !== undefined) {
+        await assertPublicInRepo(db, (await getById(db, doc.owner)), fields.privacy);
+        await db.prepare('UPDATE objects SET privacy = ? WHERE id = ?').run(fields.privacy, doc.id);
+    }
+    const set = async (column, value) => await db.prepareUncached(`UPDATE documents SET ${column} = ? WHERE object = ?`).run(value, doc.id);
+    if (fields.summary !== undefined)
+        await set('summary', fields.summary);
+    if (fields.whyItExists !== undefined)
+        await set('why_it_exists', fields.whyItExists);
+    if (fields.unlisted !== undefined)
+        await set('unlisted', fields.unlisted ? 1 : 0);
+    if (fields.lintIgnore !== undefined)
+        await set('lint_ignore_json', fields.lintIgnore === null ? null : JSON.stringify(fields.lintIgnore));
+    if (fields.extensions !== undefined)
+        await set('extensions_json', fields.extensions === null ? null : JSON.stringify(fields.extensions));
+    const current = (await getById(db, doc.id));
+    if (fields.rules !== undefined)
+        await replaceRules(db, current, fields.rules);
+    return current;
+}
+async function createDocument(db, spec, reposFn, writtenBy = 'crtr') {
+    if (spec.owner.deleted_at)
+        throw usage(`${spec.owner.name} is deleted`);
+    if (spec.relations?.length && spec.schemaType === undefined) {
+        throw new PermissionError(400, 'schema_type_required', 'relations need a schemaType: they are facts about a typed resource', { field: 'relations' });
+    }
+    if (spec.preview.trim() === '')
+        throw usage('a document needs a preview', { field: 'preview' });
+    await assertPublicInRepo(db, spec.owner, spec.privacy);
+    await assertNameFree(db, spec.owner, spec.name);
+    const doc = await createObject(db, {
+        ...(spec.id ? { id: spec.id } : {}), type: 'document', kind: spec.kind, owner: spec.owner.id,
+        privacy: spec.privacy, name: spec.name, preview: spec.preview, ...(spec.schemaType !== undefined ? { schema_type: spec.schemaType } : {}),
+    });
+    for (const { relation, subject } of spec.relations ?? []) {
+        await writeFact(db, { resourceType: spec.schemaType, resourceId: doc.id, relation, subject: parseSubject(subject), writtenBy });
+    }
+    await db.prepare(`INSERT INTO documents (object, heads_key, revision) VALUES (?, '', 0)`).run(doc.id);
+    const created = await applyDocumentFields(db, doc, { ...spec, preview: undefined, privacy: undefined, rules: spec.rules ?? [] });
+    await linkNewlyNamed(db, created, reposFn);
+    return created;
+}
+async function setHeads(db, doc) {
+    const current = await heads(db, doc);
+    const heads_key = headsKeyOf(current);
+    const revision = Math.max(0, ...current.map((h) => h.number));
+    await db.prepare('UPDATE documents SET heads_key = ?, revision = ? WHERE object = ?').run(heads_key, revision, doc.id);
+    return { heads_key, revision, headCount: current.length };
+}
+// ── write and edit ─────────────────────────────────────────────────────────
+/** Create a document with its first revision. The actor becomes a watcher whose read base is
+ *  the new revision; `created` is published. Returns the names that stayed text. */
+export async function writeDocument(db, reader, spec, body, reposFn) {
+    return await withCanvasWrite(async () => {
+        const hash = await putBody(db, body);
+        const actor = actorOf(reader);
+        const missing = await missingMemoryScope(db, reader, spec.owner.id, 'rw', true);
+        if (missing !== null)
+            throw scopeMissing(missing);
+        const acting = await actingOf(db, reader);
+        const doc = await createDocument(db, spec, reposFn, acting.app ?? acting.for);
+        // A document made directly under an app is kept for the person the call acts for; a schema-typed one is read through its app's schema instead.
+        if (spec.owner.type === 'app' && spec.schemaType === undefined)
+            await writeActsFor(db, doc.id, await userOf(db, reader));
+        const rev = await insertRevision(db, doc, { number: 1, body_hash: hash, author: actor, rationale: null, parents: [], acting });
+        // After the first revision, so the ceiling's first-revision author rule sees this caller; a refusal rolls the savepoint back.
+        if (!await check(db, reader, 'edit', doc.id))
+            throw notFound(`no owner ${spec.owner.name} you can write to`);
+        const { heads_key } = await setHeads(db, doc);
+        const unresolved = await setRevisionLinks(db, reader, doc, body);
+        await recordActedOn(db, actor, doc);
+        await recordWatch(db, actor, doc, 'write', { readHeadsKey: heads_key });
+        await publish(db, { event: 'created', object: doc, actor, attrs: { revision: 1 }, pointer: rev.rev_id }, reposFn);
+        return { object: doc, revision: 1, unresolved };
+    }, { savepoint: true });
+}
+/** The base of the reader's next edit: the heads it last read or wrote, or null when it never has. */
+export async function readBase(db, reader, doc) {
+    const row = await db.prepare('SELECT read_heads_key FROM watches WHERE watcher = ? AND object = ?')
+        .get(actorOf(reader).id, doc.id);
+    return row?.read_heads_key ?? null;
+}
+/** Apply exact-text replacements to one head's body; each `old` must occur exactly once. */
+export function applyReplacements(body, replace) {
+    let out = body;
+    for (const [index, { old, new: next }] of replace.entries()) {
+        if (old === '')
+            throw usage(`block ${index + 1}: a replacement needs non-empty old text`, { field: 'replace' });
+        const first = out.indexOf(old);
+        if (first < 0)
+            throw usage(`block ${index + 1}: old text not found: ${JSON.stringify(old.slice(0, 120))}`, { field: 'replace', old });
+        if (out.indexOf(old, first + 1) >= 0)
+            throw usage(`block ${index + 1}: old text occurs more than once: ${JSON.stringify(old.slice(0, 120))}`, { field: 'replace', old });
+        out = out.slice(0, first) + next + out.slice(first + old.length);
+    }
+    return out;
+}
+/**
+ * Commit a new revision made from `base` — the editor's read heads captured when it computed
+ * the change. No base → `read_first`. The commit is CAS on `documents.heads_key`: a base that is
+ * no longer current returns `{stale}` and writes nothing. The new revision's parents are every
+ * head, so an edit from a read that showed several heads merges them. `fields` are record
+ * changes applied with the edit.
+ */
+export async function editDocument(db, reader, doc, change, rationale, base, fields = {}, reposFn) {
+    assertDocument(doc);
+    await changeable(db, reader, doc);
+    if (doc.deleted_at)
+        throw usage(`${doc.name} is deleted`);
+    if (base === null) {
+        throw new CrtrError('read_first', `read ${doc.name} before editing it`, ExitCode.GENERAL, { id: doc.id });
+    }
+    if (rationale.trim() === '')
+        throw usage('an edit needs a rationale', { field: 'rationale' });
+    const before = await documentRecord(db, doc);
+    if (before.heads_key !== base)
+        return { stale: { heads_key: before.heads_key, revision: before.revision } };
+    const current = await heads(db, doc);
+    let body;
+    if ('body' in change)
+        body = change.body;
+    else {
+        if (current.length !== 1)
+            throw usage(`${doc.name} has ${current.length} heads and needs a merge; pass the whole merged body`, { heads: current.length });
+        // Replacements apply to the text as read, which shows links under their current names.
+        body = applyReplacements(await withCurrentNames(db, doc, await getBody(db, current[0].body_hash)), change.replace);
+    }
+    try {
+        return await withCanvasWrite(async () => {
+            const hash = await putBody(db, body);
+            const actor = actorOf(reader);
+            const number = 1 + Math.max(0, ...current.map((h) => h.number));
+            const rev = await insertRevision(db, doc, {
+                number, body_hash: hash, author: actor, rationale, verbatim: change.verbatim === true, parents: current.map((h) => h.rev_id),
+                acting: await actingOf(db, reader),
+            });
+            const heads_key = rev.rev_id;
+            const cas = await db.prepare('UPDATE documents SET heads_key = ?, revision = ? WHERE object = ? AND heads_key = ?')
+                .run(heads_key, number, doc.id, base);
+            if (Number(cas.changes) === 0) {
+                const now = await documentRecord(db, doc);
+                throw new StaleEdit(now.heads_key, now.revision);
+            }
+            const updated = await applyDocumentFields(db, doc, fields);
+            const unresolved = await setRevisionLinks(db, reader, updated, body);
+            await recordActedOn(db, actor, updated);
+            await recordWatch(db, actor, updated, 'write', { readHeadsKey: heads_key });
+            await publish(db, {
+                event: 'edited', object: updated, actor, pointer: rev.rev_id,
+                attrs: { revision: number, from_revision: before.revision, rationale },
+            }, reposFn);
+            return { revision: number, heads_key, unresolved };
+        }, { savepoint: true });
+    }
+    catch (error) {
+        if (error instanceof StaleEdit)
+            return { stale: { heads_key: error.heads_key, revision: error.revision } };
+        throw error;
+    }
+}
+/** Lost CAS race inside the savepoint; rolled back and reported as `{stale}`. */
+class StaleEdit extends Error {
+    heads_key;
+    revision;
+    constructor(heads_key, revision) {
+        super('stale');
+        this.heads_key = heads_key;
+        this.revision = revision;
+    }
+}
+/** Change record fields (preview, summary, privacy, rules, …). A null reader is repo sync, which carries no reader, checks no access and
+ *  records no history. Any other caller's change is recorded as a revision with the current body, so `history` attributes it (author,
+ *  `acting_app`, `acting_for`) with the rationale. It descends from the highest head only, so a document that needs a merge still does. A caller
+ *  that held the heads before keeps holding them; one that had not read the body does not gain a read base it never earned. */
+export async function setDocumentRecord(db, reader, doc, fields, rationale) {
+    assertDocument(doc);
+    if (reader) {
+        await changeable(db, reader, doc);
+        if (rationale === undefined || rationale.trim() === '')
+            throw usage('an edit needs a rationale', { field: 'rationale' });
+    }
+    return await withCanvasWrite(async () => {
+        const updated = await applyDocumentFields(db, doc, fields);
+        if (reader) {
+            const actor = actorOf(reader);
+            const before = await documentRecord(db, doc);
+            const base = await readBase(db, reader, doc);
+            const current = await heads(db, doc);
+            const head = current[0];
+            await insertRevision(db, doc, {
+                number: 1 + Math.max(...current.map((h) => h.number)), body_hash: head.body_hash, author: actor, rationale: rationale, parents: [head.rev_id],
+                acting: await actingOf(db, reader),
+            });
+            const { heads_key } = await setHeads(db, doc);
+            await recordActedOn(db, actor, updated);
+            await recordWatch(db, actor, doc, 'write', base === before.heads_key ? { readHeadsKey: heads_key } : {});
+        }
+        return updated;
+    }, { savepoint: true });
+}
+// ── read and history ───────────────────────────────────────────────────────
+/** Record that the reader holds the document's current heads: a `read` watch with that read
+ *  base, and a `read` push. Delivery's content load calls this without reading the body. */
+export async function recordRead(db, reader, doc, reposFn) {
+    const actor = actorOf(reader);
+    const { heads_key } = await documentRecord(db, doc);
+    await recordWatch(db, actor, doc, 'read', { readHeadsKey: heads_key });
+    await publish(db, { event: 'read', object: doc, actor, attrs: {} }, reposFn);
+}
+/** The document's record, each head with its body (several = needs merge) and its links under
+ *  their current names; records the read. */
+export async function readDocument(db, reader, doc, reposFn) {
+    assertDocument(doc);
+    await readable(db, reader, doc);
+    return await withCanvasWrite(async () => {
+        const record = await documentRecord(db, doc);
+        const headRows = await heads(db, doc);
+        const texts = await getBodies(db, headRows.map((h) => h.body_hash));
+        const current = await mapAsync(headRows, async (h) => ({ ...h, body: await withCurrentNames(db, doc, texts.get(h.body_hash)) }));
+        const read = await readableOrDeleted(db, await resolveReader(db, reader), 'o');
+        const linked = await db.prepareUncached(`SELECT e.written_as AS _written_as, o.* FROM edges e JOIN objects o ON o.id = e.dst
+      WHERE e.type = 'links-to' AND e.src = ? AND (${read.sql}) ORDER BY e.written_as`).all(doc.id, ...read.params);
+        const links = linked.map(({ _written_as, ...object }) => ({ written_as: _written_as ?? '', object: object, deleted: object.deleted_at !== null }));
+        if (!doc.deleted_at)
+            await recordRead(db, reader, doc, reposFn);
+        return { object: doc, record, heads: current, needsMerge: current.length > 1, links };
+    }, { savepoint: true });
+}
+/** Every revision, newest first, with authors, rationales and parents. Records nothing. */
+export async function history(db, reader, doc) {
+    assertDocument(doc);
+    await readable(db, reader, doc);
+    const raws = await db.prepare('SELECT * FROM revisions WHERE document = ? ORDER BY number DESC, created_at DESC, seq DESC')
+        .all(doc.id);
+    return (await mapAsync(raws, async (r) => await toRevision(db, r)));
+}
+// ── move and delete ────────────────────────────────────────────────────────
+/** Rename and/or re-own a document. Only `objects` changes: links point at the id, so no body is
+ *  rewritten. A null actor is repo sync, which carries no reader and checks no access. */
+export async function moveDocument(db, reader, doc, to, reposFn) {
+    assertDocument(doc);
+    if (doc.deleted_at)
+        throw usage(`${doc.name} is deleted`);
+    if (reader)
+        await changeable(db, reader, doc);
+    return await withCanvasWrite(async () => {
+        const owner = to.owner ?? (await getById(db, doc.owner));
+        const name = to.name ?? doc.name;
+        await assertNameFree(db, owner, name, doc);
+        await assertPublicInRepo(db, owner, doc.privacy);
+        await db.prepare('UPDATE objects SET name = ?, owner = ? WHERE id = ?').run(name, owner.id, doc.id);
+        const moved = (await getById(db, doc.id));
+        if (owner.id !== doc.owner) {
+            await setRulesOwner(db, moved);
+            if (reader && !await check(db, reader, 'edit', moved.id))
+                throw notFound(`no owner ${owner.name} you can move documents to`);
+        }
+        if (reader)
+            await recordActedOn(db, actorOf(reader), moved);
+        if (name !== doc.name || owner.id !== doc.owner)
+            await linkNewlyNamed(db, moved, reposFn);
+        return moved;
+    }, { savepoint: true });
+}
+/** Mark the document deleted; the row stays with its last preview. Publishes `deleted`
+ *  (level 8), then ends the watches on it and drops its rules. A null actor is repo sync or
+ *  node deletion; `deletedAt` is the tombstone's own time when sync imports one. What it linked to is re-checked by {@link collectUnlinked}. */
+export async function deleteDocument(db, reader, doc, reposFn, deletedAt) {
+    assertDocument(doc);
+    if (doc.deleted_at)
+        return doc;
+    if (reader)
+        await changeable(db, reader, doc);
+    return await withCanvasWrite(async () => {
+        const deleted = await markDeleted(db, reader, doc, reposFn, deletedAt);
+        await deleteFactsOf(db, doc);
+        await collectUnlinked(db, await linkTargets(db, doc.id), reposFn);
+        return deleted;
+    }, { savepoint: true });
+}
+/** Remove every fact about a typed document — it as the resource, and it as a subject (`subject_type = schema_type`) — through facts.ts, the only writer of `relations`. */
+async function deleteFactsOf(db, doc) {
+    if (doc.schema_type == null)
+        return;
+    const rows = await db.prepare(`SELECT resource_type, resource_id, relation, subject_type, subject_id, subject_relation FROM relations
+    WHERE (resource_type = ? AND resource_id = ?) OR (subject_type = ? AND subject_id = ?)`)
+        .all(doc.schema_type, doc.id, doc.schema_type, doc.id);
+    for (const r of rows) {
+        await deleteFact(db, { resourceType: r.resource_type, resourceId: r.resource_id, relation: r.relation, subject: { type: r.subject_type, id: r.subject_id, relation: r.subject_relation } });
+    }
+}
+/** Repo sync: bring a deleted document back under `name` (checked free first). Revisions, record
+ *  and links are untouched; the watches and rules deletion dropped are not recreated here. */
+export async function restoreDocument(db, doc, name, reposFn) {
+    assertDocument(doc);
+    if (!doc.deleted_at)
+        return doc;
+    return await withCanvasWrite(async () => {
+        await assertNameFree(db, (await getById(db, doc.owner)), name, doc);
+        await db.prepare('UPDATE objects SET deleted_at = NULL, name = ? WHERE id = ?').run(name, doc.id);
+        const restored = (await getById(db, doc.id));
+        await linkNewlyNamed(db, restored, reposFn);
+        return restored;
+    }, { savepoint: true });
+}
+/** The owner's undelete: bring a deleted document back under its own name inside the 30-day window (past it the purge pass may take the
+ *  row). Its owner must be live. Revisions, record and links are untouched; the rules, watches and facts deletion dropped are not
+ *  recreated (as {@link restoreDocument}). */
+export async function undeleteDocument(db, reader, doc, now = Date.now()) {
+    assertDocument(doc);
+    if (!doc.deleted_at)
+        return doc;
+    if (Date.parse(doc.deleted_at) < now - PURGE_RETENTION_MS)
+        throw usage(`${doc.name} was deleted over 30 days ago and can no longer be undeleted`, { id: doc.id, deleted_at: doc.deleted_at });
+    const owner = doc.owner === null ? null : await getById(db, doc.owner);
+    if (owner === null || owner.deleted_at)
+        throw usage(`${doc.name} cannot be undeleted while its owner is deleted`, { id: doc.id });
+    // The permission check refuses a deleted document, so the reader's right to change it is checked once it is back, inside a savepoint that undoes the restore on refusal.
+    return await withCanvasWrite(async () => {
+        const restored = await restoreDocument(db, doc, doc.name);
+        if (reader)
+            await changeable(db, reader, restored);
+        return restored;
+    }, { savepoint: true });
+}
+async function markDeleted(db, reader, doc, reposFn, deletedAt) {
+    await db.prepare('UPDATE objects SET deleted_at = ? WHERE id = ?').run(deletedAt ?? new Date().toISOString(), doc.id);
+    const deleted = (await getById(db, doc.id));
+    const actor = reader ? actorOf(reader) : null;
+    if (actor)
+        await recordActedOn(db, actor, deleted);
+    await publish(db, { event: 'deleted', object: deleted, actor, attrs: {} }, reposFn);
+    await db.prepare('DELETE FROM watches WHERE object = ?').run(doc.id);
+    await replaceRules(db, deleted, []);
+    return deleted;
+}
+async function linkTargets(db, src) {
+    return (await db.prepare(`SELECT dst FROM edges WHERE type = 'links-to' AND src = ?`).all(src))
+        .map(({ dst }) => dst);
+}
+/** Delete each of `targets` that is a kept document nothing links to any more: a live document
+ *  whose owner is deleted (node deletion kept it because a live document linked to it) and that
+ *  no other live document links to. Each one deleted re-checks what it linked to, so chains of
+ *  kept documents collapse; a cycle of kept documents keeps itself. Call it after a document
+ *  stops linking to `targets` — it was deleted, or an edit dropped the links. */
+export async function collectUnlinked(db, targets, reposFn) {
+    const unlinkedKept = db.prepare(`SELECT 1 FROM objects d JOIN objects w ON w.id = d.owner
+    WHERE d.id = ? AND d.type = 'document' AND d.deleted_at IS NULL AND w.deleted_at IS NOT NULL
+      AND NOT EXISTS (SELECT 1 FROM edges e JOIN objects s ON s.id = e.src
+        WHERE e.type = 'links-to' AND e.dst = d.id AND e.src != d.id AND s.deleted_at IS NULL)`);
+    const queue = [...targets];
+    while (queue.length > 0) {
+        const id = queue.pop();
+        if (await unlinkedKept.get(id) === undefined)
+            continue;
+        await markDeleted(db, null, (await getById(db, id)), reposFn);
+        queue.push(...await linkTargets(db, id));
+    }
+}
+/** Migration: a document with its linear history (oldest first; bodies already in the body
+ *  store). Explicit authors and times; records no edge or watch and publishes nothing — the
+ *  caller adds links (`setRevisionLinks`), acted-on edges and watches. */
+export async function importDocument(db, spec, reposFn) {
+    if (spec.revisions.length === 0)
+        throw usage(`import of ${spec.name}: no revisions`);
+    return await withCanvasWrite(async () => {
+        const doc = await createDocument(db, spec, reposFn);
+        await db.prepare('UPDATE objects SET created_at = ? WHERE id = ?').run(spec.revisions[0].created_at, doc.id);
+        let parent = null;
+        (await forEachAsync(spec.revisions, async (rev, i) => {
+            parent = (await insertRevision(db, doc, { ...rev, number: i + 1, parents: parent === null ? [] : [parent] })).rev_id;
+        }));
+        await setHeads(db, doc);
+        return (await getById(db, doc.id));
+    }, { savepoint: true });
+}
+/** Repo sync: add revisions that arrived from another runtime, skipping known `rev_id`s. No
+ *  CAS, author NULL, publishes nothing; the caller publishes `edited` (with `needs_merge`
+ *  when `headCount > 1`) and re-derives links from the head it trusts. */
+export async function insertImportedRevisions(db, doc, revs) {
+    assertDocument(doc);
+    if (doc.privacy !== 'public' && await spaceType(db, doc) === 'repo')
+        throw usage(`a repo owns only public documents; refusing revisions of ${doc.name}`);
+    return await withCanvasWrite(async () => {
+        const revisionOf = db.prepare('SELECT rev_id, number, document, body_hash FROM revisions WHERE rev_id = ?');
+        const parentsOf = db.prepare('SELECT parent FROM revision_parents WHERE child = ?');
+        // A known revision id is skipped only when it is the same revision: the same document, canonical body hash and parents. Anything else is an id collision.
+        let pending = (await filterAsync(revs, async (r) => {
+            const held = await revisionOf.get(r.rev_id);
+            if (held === undefined)
+                return true;
+            const heldParents = (await parentsOf.all(r.rev_id)).map((p) => p.parent).sort().join(',');
+            if (held.document !== doc.id || held.body_hash !== r.body_hash || heldParents !== [...r.parents].sort().join(',')) {
+                throw usage(`revision ${r.rev_id} already exists with different content (document, body hash or parents); refusing to overwrite it`);
+            }
+            return false;
+        }));
+        while (pending.length > 0) {
+            const next = [];
+            for (const rev of pending) {
+                const parents = (await mapAsync(rev.parents, async (p) => await revisionOf.get(p)));
+                if (parents.some((p) => p === undefined)) {
+                    next.push(rev);
+                    continue;
+                }
+                const known = parents;
+                if (known.some((p) => p.document !== doc.id))
+                    throw usage(`revision ${rev.rev_id} names a parent of another document`);
+                await insertRevision(db, doc, {
+                    ...rev, author: null, number: 1 + Math.max(0, ...known.map((p) => p.number)), parents: known.map((p) => p.rev_id),
+                });
+            }
+            if (next.length === pending.length)
+                throw usage(`revisions of ${doc.name} name unknown parents: ${next.map((r) => r.rev_id).join(', ')}`);
+            pending = next;
+        }
+        const { heads_key, headCount } = await setHeads(db, doc);
+        return { heads_key, headCount };
+    }, { savepoint: true });
+}
+/** Look up a live document by id (convenience for handlers and importers). */
+export async function documentById(db, id) {
+    const doc = await getById(db, id);
+    if (!doc || doc.type !== 'document')
+        throw notFound(`no document ${id}`);
+    return doc;
+}