@omgbase/core 0.1.0

package/dist/src/core/order-key.js

@@ -0,0 +1,72 @@
+// Fractional order keys (02 §5.3). Base-62; key_between(a,b) returns a key
+// strictly between its arguments. Keys sort lexicographically among siblings
+// and are never exposed via the API (ordinals are).
+//
+// v1 scope: ingest appends sequentially, so keyBetween(last, null) is the hot
+// path. A midpoint algorithm covers arbitrary insertion for the mutation stage.
+const DIGITS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+const BASE = DIGITS.length; // 62
+function digitVal(c) {
+    const v = DIGITS.indexOf(c);
+    if (v < 0)
+        throw new Error(`invalid order-key digit: ${c}`);
+    return v;
+}
+/**
+ * Return a key strictly between a and b (exclusive). null bounds mean
+ * open-ended (a=null → before b; b=null → after a). Amortized O(1) growth for
+ * sequential appends.
+ */
+export function keyBetween(a, b) {
+    if (a !== null && b !== null && a >= b) {
+        throw new Error(`keyBetween: a must be < b (got ${a}, ${b})`);
+    }
+    if (a === null && b === null)
+        return DIGITS[Math.floor(BASE / 2)]; // midpoint digit
+    if (b === null) {
+        // append after a: increment the last digit, or extend.
+        const last = a.charCodeAt(a.length - 1);
+        const lastDigit = digitVal(a[a.length - 1]);
+        if (lastDigit + 1 < BASE) {
+            return a.slice(0, -1) + DIGITS[lastDigit + 1];
+        }
+        void last;
+        return a + DIGITS[Math.floor(BASE / 2)]; // extend deeper
+    }
+    if (a === null) {
+        // before b: midpoint between "" and b.
+        const firstDigit = digitVal(b[0]);
+        if (firstDigit > 0)
+            return DIGITS[Math.floor(firstDigit / 2)];
+        return "0" + keyBetween(null, b.slice(1) || null);
+    }
+    // both present: find midpoint digit-by-digit.
+    let i = 0;
+    let prefix = "";
+    for (;;) {
+        const da = i < a.length ? digitVal(a[i]) : 0;
+        const db = i < b.length ? digitVal(b[i]) : BASE;
+        if (da === db) {
+            prefix += DIGITS[da];
+            i++;
+            continue;
+        }
+        if (db - da > 1) {
+            return prefix + DIGITS[da + Math.floor((db - da) / 2)];
+        }
+        // adjacent digits: take a's digit and recurse deeper on the fractional part.
+        prefix += DIGITS[da];
+        return prefix + keyBetween(a.slice(i + 1) || null, null);
+    }
+}
+/** Generate n sequential append keys starting from scratch. */
+export function sequentialKeys(n) {
+    const keys = [];
+    let prev = null;
+    for (let i = 0; i < n; i++) {
+        prev = keyBetween(prev, null);
+        keys.push(prev);
+    }
+    return keys;
+}
+//# sourceMappingURL=order-key.js.map

package/dist/src/core/parse/parse.d.ts

@@ -0,0 +1,3 @@
+import type { RawBlock } from "./types.js";
+/** Parse Markdown source into a flat list of top-level blocks with byte spans. */
+export declare function parseBlocks(source: string): RawBlock[];

package/dist/src/core/parse/parse.js

@@ -0,0 +1,104 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfm } from "micromark-extension-gfm";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { frontmatter } from "micromark-extension-frontmatter";
+import { frontmatterFromMarkdown } from "mdast-util-frontmatter";
+import { normalizeVisibleText } from "../hash.js";
+// Nodes whose children nest as blocks (03 §1: parser nesting only).
+// Everything else at block level maps to a leaf block; unknown → opaque.
+function mapType(node) {
+    switch (node.type) {
+        case "yaml":
+            return "frontmatter";
+        case "heading":
+            return "heading";
+        case "paragraph":
+            return "paragraph";
+        case "list":
+            return "list";
+        case "listItem":
+            return node.checked === null || node.checked === undefined ? "list_item" : "task";
+        case "blockquote":
+            return "blockquote";
+        case "code":
+            return "code_fence";
+        case "table":
+            return "table";
+        case "tableRow":
+            return "table_row";
+        case "thematicBreak":
+            return "thematic_break";
+        case "html":
+            return "html_block";
+        default:
+            return null; // opaque fallback
+    }
+}
+function attrsFor(node) {
+    switch (node.type) {
+        case "heading":
+            return { level: node.depth };
+        case "list": {
+            const attrs = { ordered: node.ordered ?? false };
+            if (node.start !== null && node.start !== undefined)
+                attrs.start = node.start;
+            return attrs;
+        }
+        case "listItem":
+            return node.checked === null || node.checked === undefined ? {} : { checked: node.checked };
+        case "code": {
+            const attrs = {};
+            if (node.lang)
+                attrs.lang = node.lang;
+            if (node.meta)
+                attrs.info = node.meta;
+            return attrs;
+        }
+        default:
+            return {};
+    }
+}
+// Which mdast container types expose block-level children we descend into.
+const CONTAINER_TYPES = new Set(["list", "listItem", "blockquote", "table"]);
+function childrenOf(node) {
+    if (!CONTAINER_TYPES.has(node.type))
+        return [];
+    const kids = node.children;
+    return Array.isArray(kids) ? kids : [];
+}
+function buildBlock(node, source) {
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+    if (start === undefined || end === undefined) {
+        throw new Error(`node ${node.type} missing position offsets`);
+    }
+    const raw = source.slice(start, end);
+    const mapped = mapType(node);
+    const type = mapped ?? "opaque";
+    let children = mapped === null ? [] : childrenOf(node).map((c) => buildBlock(c, source));
+    // Fold a tight list item's lone paragraph: the item block carries the text
+    // directly (frozen outline format, 06 §6). Loose/multi-block items keep them.
+    if ((type === "list_item" || type === "task") && children.length === 1 && children[0].type === "paragraph") {
+        children = [];
+    }
+    return {
+        type,
+        span: { start, end },
+        raw,
+        text: normalizeVisibleText(raw, type),
+        attrs: mapped === null ? {} : attrsFor(node),
+        children,
+        trivia: "",
+        anchors: [],
+        outLinks: [],
+    };
+}
+/** Parse Markdown source into a flat list of top-level blocks with byte spans. */
+export function parseBlocks(source) {
+    const tree = fromMarkdown(source, {
+        extensions: [gfm(), frontmatter(["yaml"])],
+        mdastExtensions: [gfmFromMarkdown(), frontmatterFromMarkdown(["yaml"])],
+    });
+    return tree.children.map((c) => buildBlock(c, source));
+}
+//# sourceMappingURL=parse.js.map

package/dist/src/core/parse/render.d.ts

@@ -0,0 +1,3 @@
+import type { BlockTree, RawBlock } from "./types.js";
+export declare function render(tree: BlockTree): string;
+export declare function serializeNew(block: RawBlock): string;

package/dist/src/core/parse/render.js

@@ -0,0 +1,20 @@
+// Splice renderer — 03 §2.2. Untouched blocks emit their retained raw bytes
+// verbatim; only dirty blocks (op-supplied markdown) are serialized. The
+// renderer MUST NOT re-serialize untouched content from an AST (README
+// invariant #1 — remark-stringify is banned by lint).
+export function render(tree) {
+    const out = [tree.leadingTrivia];
+    for (const block of tree.children) {
+        out.push(block.dirty ? serializeNew(block) : block.raw);
+        out.push(block.trivia);
+    }
+    return out.join("");
+}
+// Minimal normalization only (03 §2.2): the op supplies the block's markdown as
+// `raw`; we do not reformat it. Separation between siblings is owned by trivia,
+// so serialization here is the identity on the supplied text. (Container-aware
+// indentation and blank-line insertion arrive with the mutation kernel.)
+export function serializeNew(block) {
+    return block.raw;
+}
+//# sourceMappingURL=render.js.map

package/dist/src/core/parse/tree.d.ts

@@ -0,0 +1,8 @@
+import type { BlockTree } from "./types.js";
+export declare function parseTree(source: string): BlockTree;
+/**
+ * Coverage assertion (03 §2.1 invariant #2): every byte of the source is owned
+ * by exactly one top-level block's raw or trivia — no gaps, no overlaps.
+ * Returns true iff the tree tiles the source exactly.
+ */
+export declare function assertFullCoverage(tree: BlockTree): boolean;

package/dist/src/core/parse/tree.js

@@ -0,0 +1,43 @@
+import { parseBlocks } from "./parse.js";
+// Trivia attachment (03 §2.3): inter-block bytes attach to the PRECEDING block
+// (trailing-attach). Bytes before the first block are document-leading trivia.
+//
+// As-built scope: trivia is tiled at the top level, which is what the splice
+// renderer (03 §2.2) walks. `leadingTrivia + Σ(block.raw + block.trivia)`
+// reconstructs the source byte-for-byte. Nested children retain their `raw`
+// (a substring of the parent's raw) for structure/identity; splicing *inside* a
+// container is deferred to the mutation stage and does not affect round-trip.
+export function parseTree(source) {
+    const children = parseBlocks(source);
+    const leadingTrivia = children.length === 0 ? source : source.slice(0, children[0].span.start);
+    for (let i = 0; i < children.length; i++) {
+        const block = children[i];
+        const next = children[i + 1];
+        const triviaEnd = next ? next.span.start : source.length;
+        block.trivia = source.slice(block.span.end, triviaEnd);
+    }
+    return { source, leadingTrivia, children };
+}
+/**
+ * Coverage assertion (03 §2.1 invariant #2): every byte of the source is owned
+ * by exactly one top-level block's raw or trivia — no gaps, no overlaps.
+ * Returns true iff the tree tiles the source exactly.
+ */
+export function assertFullCoverage(tree) {
+    let cursor = 0;
+    if (tree.leadingTrivia !== tree.source.slice(0, tree.leadingTrivia.length))
+        return false;
+    cursor = tree.leadingTrivia.length;
+    for (const block of tree.children) {
+        if (block.span.start !== cursor)
+            return false; // gap or overlap
+        if (block.raw !== tree.source.slice(block.span.start, block.span.end))
+            return false;
+        cursor = block.span.end;
+        if (block.trivia !== tree.source.slice(cursor, cursor + block.trivia.length))
+            return false;
+        cursor += block.trivia.length;
+    }
+    return cursor === tree.source.length;
+}
+//# sourceMappingURL=tree.js.map

package/dist/src/core/parse/types.d.ts

@@ -0,0 +1,52 @@
+/** General block kind — format-qualified string (e.g. "md:heading", "yaml:mapping_entry"). */
+export type BlockKind = string;
+/** Markdown-specific block types. Subset of BlockKind used by the markdown parser. */
+export type BlockType = "heading" | "paragraph" | "list" | "list_item" | "task" | "blockquote" | "code_fence" | "table" | "table_row" | "thematic_break" | "html_block" | "frontmatter" | "opaque";
+/** Half-open [start, end) offsets into the source string. */
+export interface Span {
+    start: number;
+    end: number;
+}
+export interface RawBlock {
+    type: BlockKind;
+    span: Span;
+    /** Exact source slice for this block's content (excludes trailing trivia). */
+    raw: string;
+    /** Normalized visible text (02 §5.2 — refined in Stage 1). */
+    text: string;
+    /** Typed attributes: level, ordered, checked, lang, info, … */
+    attrs: Record<string, unknown>;
+    /** Parser nesting only (lists, list items, blockquotes, tables). */
+    children: RawBlock[];
+    /** Trailing inter-block trivia attached to this block (03 §2.3). */
+    trivia: string;
+    /**
+     * Set by mutation ops: this block's `raw` is op-supplied markdown and must be
+     * serialized (03 §2.2) rather than spliced verbatim. Absent/false = untouched.
+     */
+    dirty?: boolean;
+    /** Authored ^block-ref anchors (Stage 4). */
+    anchors: string[];
+    /** Extracted outgoing links for edge extraction (Stage 4). */
+    outLinks: ExtractedLink[];
+    /**
+     * Assigned block id, populated ONLY for node projection (ingest zips the
+     * assigned tree onto the parsed blocks before calling projectNodes) so an
+     * adapter can anchor each node to its own block. Absent during parse/reconcile.
+     */
+    blockId?: string;
+}
+export interface ExtractedLink {
+    kind: "link" | "wikilink" | "image" | "inline_field" | "url";
+    target: string;
+    anchor?: string;
+    field?: string;
+}
+export interface BlockTree {
+    /** The decoded source string this tree was parsed from. */
+    source: string;
+    /** Bytes before the first block (document-leading trivia, 03 §2.3). */
+    leadingTrivia: string;
+    /** Top-level blocks in document order (flat containment). */
+    children: RawBlock[];
+}

package/dist/src/core/parse/types.js

@@ -0,0 +1,9 @@
+// Block model — architecture §3.3, reconciliation-spec §1.
+//
+// As-built note: the design (03 §1) types spans as byte offsets and `raw` as
+// Uint8Array. We work in string space instead — mdast/micromark positions are
+// offsets into the decoded source string, and byte-identity round-trip follows
+// from deterministic UTF-8 encoding of equal strings. Hashing (02 §5) encodes
+// UTF-8 at hash time. This keeps offset handling robust and simple.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/core/read/document.d.ts

@@ -0,0 +1,107 @@
+import type { Database } from "better-sqlite3";
+import type { Store } from "../store/store.js";
+export interface DocsReadResult {
+    path: string;
+    docId: string;
+    rev: string | null;
+    /** Properties grouped by source: { frontmatter, inline, computed }. */
+    properties: Record<string, Record<string, unknown>>;
+    content: string;
+    /** Block ids in document order, for follow-up edits (include_ids). */
+    ids?: string[];
+    /**
+     * Block id → current content hash (raw-bytes hash, hex) for every id in
+     * `ids` (include_ids). This is the exact value the raw `apply` kernel wants in
+     * an update/split/merge/remove op's `expect.content_hash`, so a single read
+     * yields both the stable ids AND the CAS tokens to mutate them — no follow-up
+     * nodes_get_many(resolution:"full") hydration round trip.
+     */
+    hashes?: Record<string, string>;
+    /**
+     * Block id → parent block id (null = top level) for every id in `ids`
+     * (include_ids). `ids` is a flat pre-order walk, so without this a caller
+     * cannot tell a top-level block from a nested one (a list from its items)
+     * without a second outline read — this makes "the top-level blocks of these
+     * sections" a local filter.
+     */
+    parents?: Record<string, string | null>;
+}
+export interface DocsReadOptions {
+    includeIds?: boolean;
+}
+/**
+ * Reconstruct a document's full file bytes from its ordered top-level blocks.
+ * Takes a raw Database handle so it can run inside an ingest transaction (the
+ * convergence check reloads through this) as well as from a Store.
+ */
+export declare function reconstructContent(db: Database, docId: string): string | null;
+/** Read a whole document by id: full file bytes + properties. Null if missing. */
+export declare function docsRead(store: Store, docId: string, opts?: DocsReadOptions): DocsReadResult | null;
+/** Max doc refs honored per docsReadMany call (matches nodesGetMany's cap). */
+export declare const MANY_DOCS_CAP = 100;
+export interface DocsReadManyError {
+    /** The original ref (id or path) that failed to resolve. */
+    ref: string;
+    /** Stable error code — currently always doc_not_found (unresolvable ref). */
+    error: "doc_not_found";
+}
+export interface DocsReadManyResult {
+    /** Full reads, one per resolved (deduped) ref, same shape as docsRead. */
+    items: DocsReadResult[];
+    /** Per-ref misses; present but empty when every ref resolved. */
+    errors: DocsReadManyError[];
+    /** True when refs exceeded the cap or the token budget cut the batch short. */
+    truncated: boolean;
+}
+/**
+ * Read many whole documents by ref (id or path) in one call. Found docs land in
+ * `items` (each a full docsRead projection); unresolvable refs land in `errors`
+ * without failing the call. Duplicate refs collapse first-seen. The raw list is
+ * capped at MANY_DOCS_CAP (excess ⇒ truncated); an optional token budget stops
+ * the batch early (also ⇒ truncated).
+ */
+export declare function docsReadMany(store: Store, repoId: string, refs: string[], opts?: {
+    includeIds?: boolean;
+    budgetTokens?: number;
+}): DocsReadManyResult;
+export interface DocsReadAtResult {
+    path: string;
+    docId: string;
+    /** The revision travelled to (the argument, echoed for confirmation). */
+    rev: string;
+    content: string;
+    /** True when the reconstructed bytes' sha256 matched the revision's stored
+     *  rendered_hash — a byte-faithful round-trip. False flags the fidelity gap
+     *  described below (doc-level trivia may differ for an old revision). */
+    renderedHashMatch: boolean;
+    /**
+     * Properties as they are CURRENTLY (not at `rev`): the properties table is
+     * current-state only (properties-table), so historical property values are
+     * not recoverable. Included as best-effort context, flagged by
+     * `propertiesAreCurrent: true`.
+     */
+    properties: Record<string, Record<string, unknown>>;
+    propertiesAreCurrent: true;
+}
+/**
+ * Whole-document TIME-TRAVEL read: reconstruct a document's full file bytes AS
+ * OF a past revision `revId`, using the SAME assembly order as
+ * `reconstructContent` — leading_trivia + frontmatter (from THAT revision's
+ * frontmatter_blob) + frontmatter_trivia + Σ(top-level block raw + its trivia)
+ * IN ORDER — but sourced from the revision's Merkle `root_tree` instead of the
+ * live `blocks` table. Returns null when the doc is missing, or when `revId`
+ * does not name a revision of this document (so the caller can raise a clean
+ * not-found error).
+ *
+ * FIDELITY CAVEAT: `leading_trivia` and `frontmatter_trivia` are stored ONLY on
+ * the current `docs` row, NOT per-revision (see schema.ts — the `docs` row is
+ * document-level current state). So for the CURRENT revision they are exact and
+ * `renderedHashMatch` is true; for a PAST revision they may be wrong if the
+ * document's leading/frontmatter trivia changed since — in practice these rarely
+ * change, so we use the current doc-row values as a documented best-effort. The
+ * block bytes themselves ARE per-revision and always faithful. `renderedHashMatch`
+ * is the honest signal: true ⇒ the reconstruction is byte-for-byte the file at
+ * that revision; false ⇒ it differs only by those doc-level trivia bytes (block
+ * content still reconstructs correctly).
+ */
+export declare function readDocumentAtRevision(store: Store, docId: string, revId: string): DocsReadAtResult | null;

package/dist/src/core/read/document.js

@@ -0,0 +1,191 @@
+import { findDoc, findDocByRef, loadDocBlocks } from "./reader.js";
+import { docPropertiesGrouped } from "../store/properties.js";
+import { sha256 } from "../hash.js";
+function blob(db, hash) {
+    const row = db.prepare("SELECT bytes FROM blobs WHERE hash = ?").get(hash);
+    return row ? row.bytes.toString("utf8") : "";
+}
+/**
+ * Reconstruct a document's full file bytes from its ordered top-level blocks.
+ * Takes a raw Database handle so it can run inside an ingest transaction (the
+ * convergence check reloads through this) as well as from a Store.
+ */
+export function reconstructContent(db, docId) {
+    const doc = db
+        .prepare("SELECT leading_trivia, frontmatter_trivia, current_rev FROM docs WHERE doc_id = ? AND deleted_commit IS NULL")
+        .get(docId);
+    if (!doc)
+        return null;
+    const out = [doc.leading_trivia];
+    if (doc.current_rev) {
+        const rev = db.prepare("SELECT frontmatter_blob FROM revisions WHERE rev_id = ?").get(doc.current_rev);
+        // Emit the frontmatter block followed by its exact stored separator. Ingest
+        // always captures frontmatter_trivia whenever a frontmatter block exists, so
+        // frontmatter_blob present ⇒ frontmatter_trivia is a real string (possibly
+        // ""); the ?? "" is just a type guard.
+        if (rev?.frontmatter_blob)
+            out.push(blob(db, rev.frontmatter_blob) + (doc.frontmatter_trivia ?? ""));
+    }
+    // Top-level blocks only: a container's `raw` already contains its nested
+    // children verbatim (03 §2.3), so walking roots reconstructs the whole body.
+    const rows = db
+        .prepare(`SELECT raw_hash, trivia_hash FROM blocks
+       WHERE doc_id = ? AND parent_block IS NULL AND deleted_commit IS NULL
+       ORDER BY order_key`)
+        .all(docId);
+    for (const r of rows) {
+        out.push(blob(db, r.raw_hash));
+        if (r.trivia_hash)
+            out.push(blob(db, r.trivia_hash));
+    }
+    return out.join("");
+}
+/** Read a whole document by id: full file bytes + properties. Null if missing. */
+export function docsRead(store, docId, opts = {}) {
+    const info = findDoc(store, { docId });
+    if (!info)
+        return null;
+    const content = reconstructContent(store.db, docId);
+    if (content === null)
+        return null;
+    const result = {
+        path: info.path,
+        docId: info.docId,
+        rev: info.currentRev,
+        properties: docPropertiesGrouped(store.db, docId),
+        content,
+    };
+    if (opts.includeIds) {
+        const ids = [];
+        const hashes = {};
+        const parents = {};
+        const collect = (nodes) => {
+            for (const n of nodes) {
+                ids.push(n.blockId);
+                // The block's raw-bytes hash and parent are already loaded on the node,
+                // so exposing them costs nothing beyond the id walk.
+                hashes[n.blockId] = n.rawHashHex;
+                parents[n.blockId] = n.parentBlock;
+                collect(n.children);
+            }
+        };
+        collect(loadDocBlocks(store, docId));
+        result.ids = ids;
+        result.hashes = hashes;
+        result.parents = parents;
+    }
+    return result;
+}
+// Batch whole-document read (the hydrate half of query→hydrate). The batch
+// analog of docsRead: given several doc refs (each an id OR a path, via the
+// shared findDocByRef dispatch), it returns `items` (the full reads, identical
+// in shape to docsRead) alongside `errors` (per-ref misses). A miss NEVER fails
+// the whole call — mirrors nodes_getMany's tolerance of unknown ids, but made
+// explicit as an errors array so a caller can tell which refs didn't resolve.
+// Duplicate refs collapse first-seen (a repeated ref yields one item). Capped
+// at MANY_DOCS_CAP refs per call (matching nodesGetMany's 100), with the same
+// budget-token truncation and `truncated` flag.
+/** Max doc refs honored per docsReadMany call (matches nodesGetMany's cap). */
+export const MANY_DOCS_CAP = 100;
+/**
+ * Read many whole documents by ref (id or path) in one call. Found docs land in
+ * `items` (each a full docsRead projection); unresolvable refs land in `errors`
+ * without failing the call. Duplicate refs collapse first-seen. The raw list is
+ * capped at MANY_DOCS_CAP (excess ⇒ truncated); an optional token budget stops
+ * the batch early (also ⇒ truncated).
+ */
+export function docsReadMany(store, repoId, refs, opts = {}) {
+    const capped = refs.slice(0, MANY_DOCS_CAP);
+    let truncated = refs.length > MANY_DOCS_CAP;
+    const budget = opts.budgetTokens ?? Infinity;
+    const readOpts = opts.includeIds ? { includeIds: true } : {};
+    const items = [];
+    const errors = [];
+    const seen = new Set();
+    let tokens = 0;
+    for (const ref of capped) {
+        // First-seen wins: a repeated ref (same literal string) is collapsed.
+        if (seen.has(ref))
+            continue;
+        seen.add(ref);
+        const info = findDocByRef(store, repoId, ref);
+        // Unresolvable ref (or a d_-shaped id with no doc) → a per-ref miss, never
+        // a thrown error. reconstructContent returning null is the same miss.
+        const read = info ? docsRead(store, info.docId, readOpts) : null;
+        if (!read) {
+            errors.push({ ref, error: "doc_not_found" });
+            continue;
+        }
+        const cost = Math.ceil(JSON.stringify(read).length / 4);
+        if (tokens + cost > budget) {
+            truncated = true;
+            break;
+        }
+        tokens += cost;
+        items.push(read);
+    }
+    return { items, errors, truncated };
+}
+/**
+ * Whole-document TIME-TRAVEL read: reconstruct a document's full file bytes AS
+ * OF a past revision `revId`, using the SAME assembly order as
+ * `reconstructContent` — leading_trivia + frontmatter (from THAT revision's
+ * frontmatter_blob) + frontmatter_trivia + Σ(top-level block raw + its trivia)
+ * IN ORDER — but sourced from the revision's Merkle `root_tree` instead of the
+ * live `blocks` table. Returns null when the doc is missing, or when `revId`
+ * does not name a revision of this document (so the caller can raise a clean
+ * not-found error).
+ *
+ * FIDELITY CAVEAT: `leading_trivia` and `frontmatter_trivia` are stored ONLY on
+ * the current `docs` row, NOT per-revision (see schema.ts — the `docs` row is
+ * document-level current state). So for the CURRENT revision they are exact and
+ * `renderedHashMatch` is true; for a PAST revision they may be wrong if the
+ * document's leading/frontmatter trivia changed since — in practice these rarely
+ * change, so we use the current doc-row values as a documented best-effort. The
+ * block bytes themselves ARE per-revision and always faithful. `renderedHashMatch`
+ * is the honest signal: true ⇒ the reconstruction is byte-for-byte the file at
+ * that revision; false ⇒ it differs only by those doc-level trivia bytes (block
+ * content still reconstructs correctly).
+ */
+export function readDocumentAtRevision(store, docId, revId) {
+    const db = store.db;
+    const doc = db
+        .prepare("SELECT path, leading_trivia, frontmatter_trivia FROM docs WHERE doc_id = ? AND deleted_commit IS NULL")
+        .get(docId);
+    if (!doc)
+        return null;
+    const rev = db.prepare("SELECT root_tree, frontmatter_blob, rendered_hash, path FROM revisions WHERE rev_id = ? AND doc_id = ?").get(revId, docId);
+    if (!rev)
+        return null;
+    const out = [doc.leading_trivia];
+    // Frontmatter blob for THIS revision (per-revision), then the doc-level
+    // separator (best-effort — see fidelity caveat).
+    if (rev.frontmatter_blob)
+        out.push(blob(db, rev.frontmatter_blob) + (doc.frontmatter_trivia ?? ""));
+    // Top-level blocks in tree order, from THIS revision's Merkle root tree node.
+    // A container's raw already holds its children verbatim, so we deliberately do
+    // NOT recurse into childTreeHashHex (mirrors reconstructContent's
+    // parent_block IS NULL walk). An absent tree node yields empty body bytes.
+    const node = db.prepare("SELECT entries FROM tree_nodes WHERE hash = ?").get(rev.root_tree);
+    if (node) {
+        const entries = JSON.parse(node.entries);
+        for (const [, rawHashHex, , , , triviaHashHex] of entries) {
+            out.push(blob(db, Buffer.from(rawHashHex, "hex")));
+            if (triviaHashHex)
+                out.push(blob(db, Buffer.from(triviaHashHex, "hex")));
+        }
+    }
+    const content = out.join("");
+    const renderedHashMatch = sha256(content).equals(rev.rendered_hash);
+    return {
+        // The revision records the path as of that revision (docs may be moved).
+        path: rev.path,
+        docId,
+        rev: revId,
+        content,
+        renderedHashMatch,
+        properties: docPropertiesGrouped(db, docId),
+        propertiesAreCurrent: true,
+    };
+}
+//# sourceMappingURL=document.js.map

package/dist/src/core/read/nodes.d.ts

@@ -0,0 +1,47 @@
+import type { Store } from "../store/store.js";
+export type Resolution = "skeleton" | "outline" | "text" | "raw" | "full";
+export interface GetNode {
+    id: string;
+    type: string;
+    label?: string;
+    text?: string;
+    raw?: string;
+    /** The block's raw_hash (hex) — the value update/split expect as content_hash. */
+    content_hash?: string;
+    attrs?: Record<string, unknown>;
+    placement?: {
+        parent: string | null;
+        ordinal: number;
+        depth: number;
+    };
+    children?: GetNode[];
+}
+export interface NodesGetOptions {
+    resolution?: Resolution;
+    include?: ("children" | "ancestors")[];
+}
+/** Fetch a single block subtree at a resolution. Returns null if missing. */
+export declare function nodesGet(store: Store, docId: string, blockId: string, opts?: NodesGetOptions): GetNode | null;
+export interface NodesGetManyResult {
+    nodes: GetNode[];
+    truncated: boolean;
+    /**
+     * Requested ids (within the first 100) that name NO live block — or, when a
+     * `docId` scope is given, no live block in THAT document. Ids dropped by the
+     * 100-id cap or the token budget are NOT listed here; they are reported by
+     * `truncated` instead. Never silently dropped.
+     */
+    unresolved: string[];
+}
+/**
+ * Fetch up to 100 blocks by id, with budget truncation (06 §3). Block ids are
+ * globally unique, so `docId` is an optional SCOPE, not a requirement: with
+ * `null` each id is resolved to its owning document (`blocks.doc_id`), the ids
+ * are grouped by doc, each doc's forest is loaded once, and the nodes come back
+ * in request order. With a `docId`, ids from other documents count as
+ * `unresolved` (the caller asked for that doc's blocks).
+ */
+export declare function nodesGetMany(store: Store, docId: string | null, blockIds: string[], opts?: {
+    resolution?: Resolution;
+    budgetTokens?: number;
+}): NodesGetManyResult;