@omgbase/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan Baldwin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/cli/eval-matcher.d.ts

@@ -0,0 +1,13 @@
+import { runEval } from "../reconcile/eval/metrics.js";
+export interface EvalCliOptions {
+    n?: number;
+    size?: number;
+    intensity?: number;
+}
+export declare function formatReport(report: ReturnType<typeof runEval>): string;
+/** Run the eval and return the report + a pass/fail against release gates. */
+export declare function evalMatcher(opts?: EvalCliOptions): {
+    report: ReturnType<typeof runEval>;
+    text: string;
+    gatesPass: boolean;
+};

package/dist/src/cli/eval-matcher.js

@@ -0,0 +1,36 @@
+import { runEval } from "../reconcile/eval/metrics.js";
+import { DEFAULT_CONFIG } from "../reconcile/types.js";
+export function formatReport(report) {
+    const lines = [];
+    lines.push(`matcher_v=${DEFAULT_CONFIG.matcherV}  cases=${report.cases}`);
+    lines.push("");
+    const row = (name, m) => `${name.padEnd(10)} precision=${m.precision.toFixed(4)} recall=${m.recall.toFixed(4)} true=${m.truePairs} carried=${m.carriedPairs}`;
+    lines.push(row("OVERALL", report.overall));
+    for (const [cls, m] of Object.entries(report.perClass))
+        lines.push(row(cls, m));
+    return lines.join("\n");
+}
+/** Run the eval and return the report + a pass/fail against release gates. */
+export function evalMatcher(opts = {}) {
+    const runOpts = { config: DEFAULT_CONFIG };
+    if (opts.n !== undefined)
+        runOpts.n = opts.n;
+    if (opts.size !== undefined)
+        runOpts.size = opts.size;
+    if (opts.intensity !== undefined)
+        runOpts.intensity = opts.intensity;
+    const report = runEval(runOpts);
+    const gatesPass = checkGates(report);
+    return { report, text: formatReport(report), gatesPass };
+}
+function checkGates(report) {
+    if (report.overall.precision < 0.995)
+        return false;
+    for (const cls of ["edit", "move", "reorder"]) {
+        const m = report.perClass[cls];
+        if (m && m.recall < 0.95)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=eval-matcher.js.map

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

@@ -0,0 +1,5 @@
+import { Store } from "./store/store.js";
+/** Create (or reuse) a repo row for `slug`, returning its id. When `rootPath` is
+ *  given it is registered as an `fs` source + attachment, not stored on the repo.
+ *  Pass null for a sourceless/headless repo. */
+export declare function ensureRepo(store: Store, slug: string, rootPath?: string | null): string;

package/dist/src/core/attach.js

@@ -0,0 +1,38 @@
+import { Store } from "./store/store.js";
+import { mintId } from "./ids.js";
+// Repo identity + fs-source registration (ADR-014). A repo owns identity +
+// history, NOT a filesystem: `ensureRepo` mints the repo row, and when given a
+// filesystem root it registers that as an `fs` source + attachment (the durable
+// "where its bytes come from"). Ingesting a directory's files is a separate
+// concern — `ingestDirectory` (sync/attach.ts) for the reconciling walk, or the
+// freshness sweep / `observeOne` on the live path. The CLI entry point is
+// `omg source add <dir>`; there is no `omg attach` verb.
+/** Create (or reuse) a repo row for `slug`, returning its id. When `rootPath` is
+ *  given it is registered as an `fs` source + attachment, not stored on the repo.
+ *  Pass null for a sourceless/headless repo. */
+export function ensureRepo(store, slug, rootPath = null) {
+    const existing = store.db.prepare("SELECT repo_id FROM repos WHERE slug = ?").get(slug);
+    if (existing)
+        return existing.repo_id;
+    const repoId = mintId("rp");
+    store.db.prepare("INSERT INTO repos (repo_id, slug) VALUES (?, ?)").run(repoId, slug);
+    if (rootPath)
+        registerFsSource(store, repoId, slug, rootPath);
+    return repoId;
+}
+/** Register (idempotently) an `fs` source at `root` and attach it to a repo.
+ *  Inline raw SQL — kept here rather than calling sync/sources to avoid a
+ *  core→sync import cycle; the source shape matches sync/sources exactly. */
+function registerFsSource(store, repoId, slug, root) {
+    const db = store.db;
+    db.prepare("INSERT OR IGNORE INTO adapters (name, command, args) VALUES ('fs', 'omgbase-fs-adapter', '[]')").run();
+    const name = `${slug}-fs`;
+    let source = db.prepare("SELECT source_id FROM sources WHERE name = ?").get(name);
+    if (!source) {
+        const sourceId = mintId("src");
+        db.prepare("INSERT INTO sources (source_id, name, adapter, config, env) VALUES (?, ?, 'fs', ?, '{}')").run(sourceId, name, JSON.stringify({ root }));
+        source = { source_id: sourceId };
+    }
+    db.prepare("INSERT OR IGNORE INTO attachments (repo_id, source_id) VALUES (?, ?)").run(repoId, source.source_id);
+}
+//# sourceMappingURL=attach.js.map

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

@@ -0,0 +1,11 @@
+/** A cursor this surface did not issue (malformed / tampered / from another
+ *  tool). The MCP layer maps it to `filter_invalid`. */
+export declare class CursorInvalid extends Error {
+    readonly surface: string;
+    constructor(surface: string);
+}
+/** Encode a keyset position as an opaque cursor. */
+export declare function encodeCursor(parts: readonly string[]): string;
+/** Decode a cursor issued by `encodeCursor`, requiring exactly `arity` string
+ *  parts. `surface` names the caller for the error. */
+export declare function decodeCursor(cursor: string, surface: string, arity: number): string[];

package/dist/src/core/cursor.js

@@ -0,0 +1,35 @@
+// Keyset cursors for every paged list surface (mcp-api §1: "truncated + cursor").
+// One encoding — base64url of a JSON tuple of strings — shared by the OQX
+// collect page (`[path, id]`) and the docs_list / docs_tree pages (`[path]`),
+// so there is exactly one place a cursor can be malformed and one error for it.
+// Kernel-owned: the query layer and the read layer both consume this; neither
+// defines its own.
+/** A cursor this surface did not issue (malformed / tampered / from another
+ *  tool). The MCP layer maps it to `filter_invalid`. */
+export class CursorInvalid extends Error {
+    surface;
+    constructor(surface) {
+        super("invalid cursor");
+        this.surface = surface;
+        this.name = "CursorInvalid";
+    }
+}
+/** Encode a keyset position as an opaque cursor. */
+export function encodeCursor(parts) {
+    return Buffer.from(JSON.stringify(parts), "utf8").toString("base64url");
+}
+/** Decode a cursor issued by `encodeCursor`, requiring exactly `arity` string
+ *  parts. `surface` names the caller for the error. */
+export function decodeCursor(cursor, surface, arity) {
+    let parts;
+    try {
+        parts = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new CursorInvalid(surface);
+    }
+    if (!Array.isArray(parts) || parts.length !== arity || !parts.every((p) => typeof p === "string"))
+        throw new CursorInvalid(surface);
+    return parts;
+}
+//# sourceMappingURL=cursor.js.map

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

@@ -0,0 +1,23 @@
+export declare function sha256(input: string | Uint8Array): Buffer;
+export declare function hashHex(input: string | Uint8Array): string;
+/** Display form: first 16 hex chars (02 §1). */
+export declare function shortHash(hash: Buffer | string): string;
+/** raw_hash — sha256 of the exact raw source bytes (02 §1). */
+export declare function rawHash(raw: string): Buffer;
+export declare function normalizeText(raw: string): string;
+export declare function normalizeVisibleText(raw: string, type: string): string;
+/** norm_hash — sha256 of the normalized text (02 §1, §5.2). */
+export declare function normHash(normalizedText: string): Buffer;
+export declare function canonicalAttrs(attrs: Record<string, unknown>): string;
+export interface TreeEntry {
+    blockId: string;
+    rawHashHex: string;
+    childTreeHashHex: string | null;
+    type: string;
+    attrs: Record<string, unknown>;
+    triviaHashHex: string | null;
+}
+/** Canonical serialization of a tree node's entries (UTF-8, no whitespace). */
+export declare function serializeTreeEntries(entries: TreeEntry[]): string;
+/** Tree-node hash: sha256 over the canonical entries serialization (02 §5.1). */
+export declare function treeHash(entries: TreeEntry[]): Buffer;

package/dist/src/core/hash.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+// Hashing & canonical serialization — 02 §5.
+// Content hashes are sha256 of UTF-8 bytes, stored as 32-byte buffers and
+// displayed truncated to 16 hex chars.
+export function sha256(input) {
+    const h = createHash("sha256");
+    h.update(typeof input === "string" ? Buffer.from(input, "utf8") : input);
+    return h.digest();
+}
+export function hashHex(input) {
+    return sha256(input).toString("hex");
+}
+/** Display form: first 16 hex chars (02 §1). */
+export function shortHash(hash) {
+    const hex = typeof hash === "string" ? hash : hash.toString("hex");
+    return hex.slice(0, 16);
+}
+/** raw_hash — sha256 of the exact raw source bytes (02 §1). */
+export function rawHash(raw) {
+    return sha256(raw);
+}
+// Normalized text (02 §5.2): per-line trim + internal whitespace-run collapse,
+// drop blank lines, NFC. Inline Markdown characters are preserved as content.
+export function normalizeText(raw) {
+    return raw
+        .split(/\r\n|\r|\n/)
+        .map((line) => line.trim().replace(/[ \t]+/g, " "))
+        .filter((line) => line.length > 0)
+        .join(" ")
+        .normalize("NFC");
+}
+// Type-aware visible text (02 §5.2). Strips block-level syntax markers that are
+// not content: ATX heading hashes and list/task markers. Inline markers stay.
+export function normalizeVisibleText(raw, type) {
+    let s = raw;
+    if (type === "heading") {
+        s = s.replace(/^[ \t]*#{1,6}[ \t]+/, "").replace(/[ \t]+#*[ \t]*$/, "");
+    }
+    else if (type === "list_item" || type === "task") {
+        // Strip the list marker and an optional GFM checkbox on the first line.
+        s = s.replace(/^[ \t]*([-*+]|\d+[.)])[ \t]+/, "").replace(/^\[[ xX]\][ \t]+/, "");
+    }
+    return normalizeText(s);
+}
+/** norm_hash — sha256 of the normalized text (02 §1, §5.2). */
+export function normHash(normalizedText) {
+    return sha256(normalizedText);
+}
+// Canonical attrs JSON: object with lexicographically sorted keys, no
+// whitespace (02 §5.1). Values are emitted with JSON.stringify (stable for
+// scalars/arrays/nested objects we use).
+export function canonicalAttrs(attrs) {
+    const keys = Object.keys(attrs).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalValue(attrs[k])}`);
+    return `{${parts.join(",")}}`;
+}
+function canonicalValue(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(canonicalValue).join(",")}]`;
+    const obj = v;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalValue(obj[k])}`).join(",")}}`;
+}
+/** Canonical serialization of a tree node's entries (UTF-8, no whitespace). */
+export function serializeTreeEntries(entries) {
+    const rows = entries.map((e) => [
+        JSON.stringify(e.blockId),
+        JSON.stringify(e.rawHashHex),
+        e.childTreeHashHex === null ? "null" : JSON.stringify(e.childTreeHashHex),
+        JSON.stringify(e.type),
+        canonicalAttrs(e.attrs),
+        e.triviaHashHex === null ? "null" : JSON.stringify(e.triviaHashHex),
+    ].join(","));
+    return `[${rows.map((r) => `[${r}]`).join(",")}]`;
+}
+/** Tree-node hash: sha256 over the canonical entries serialization (02 §5.1). */
+export function treeHash(entries) {
+    return sha256(serializeTreeEntries(entries));
+}
+//# sourceMappingURL=hash.js.map

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

@@ -0,0 +1,6 @@
+export type IdPrefix = "d" | "b" | "c" | "r" | "x" | "col" | "cp" | "e" | "rp" | "v" | "src";
+export declare function randomSuffix(len?: number): string;
+/** Mint an ID with the given prefix. Collision checking is the store's job. */
+export declare function mintId(prefix: IdPrefix): string;
+export declare function isValidId(id: string, prefix?: IdPrefix): boolean;
+export declare function prefixOf(id: string): string | null;

package/dist/src/core/ids.js

@@ -0,0 +1,26 @@
+import { randomInt } from "node:crypto";
+// Crockford base32 alphabet, lowercased (no i, l, o, u).
+const ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+const ID_LEN = 7;
+export function randomSuffix(len = ID_LEN) {
+    let s = "";
+    for (let i = 0; i < len; i++)
+        s += ALPHABET[randomInt(ALPHABET.length)];
+    return s;
+}
+/** Mint an ID with the given prefix. Collision checking is the store's job. */
+export function mintId(prefix) {
+    return `${prefix}_${randomSuffix()}`;
+}
+const ID_RE = new RegExp(`^([a-z]+)_([${ALPHABET}]{${ID_LEN}})$`);
+export function isValidId(id, prefix) {
+    const m = ID_RE.exec(id);
+    if (!m)
+        return false;
+    return prefix === undefined || m[1] === prefix;
+}
+export function prefixOf(id) {
+    const m = ID_RE.exec(id);
+    return m ? m[1] : null;
+}
+//# sourceMappingURL=ids.js.map

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

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0";

package/dist/src/core/index.js

@@ -0,0 +1,2 @@
+export const VERSION = "0.1.0";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,43 @@
+import { Store } from "./store/store.js";
+import { type TreeInputBlock } from "./store/writers.js";
+import type { RawBlock } from "./parse/types.js";
+export interface DispositionRow {
+    blockId: string;
+    kind: string;
+    confidence: number | null;
+    reason: string | null;
+    matcherV: string | null;
+    detail: Record<string, unknown>;
+}
+export interface ResolvedEdgeRow {
+    srcDoc: string;
+    srcBlock: string | null;
+    srcField: string | null;
+    predicate: string;
+    dstKind: "document" | "block" | "external" | "collection";
+    dstNode: string;
+    anchor: string | null;
+    provenance: string;
+}
+export type IdResolver = (rest: RawBlock[], docId: string | null) => {
+    assigned: TreeInputBlock[];
+    dispositions: DispositionRow[];
+    deleted: string[];
+    consumedPool?: string[];
+    extractEdges?: (docId: string, frontmatter: Record<string, unknown>) => ResolvedEdgeRow[];
+};
+export interface IngestResult {
+    docId: string;
+    commitId: string;
+    revId: string;
+    blockCount: number;
+    /** convergence: sha256(file bytes) === revision.rendered_hash */
+    converged: boolean;
+}
+/** Ingest a single file's content into the store as one observed commit. */
+export declare function ingestFile(store: Store, repoId: string, path: string, content: string, opts?: {
+    ts?: string;
+    origin?: "observed" | "import";
+    resolveIds?: IdResolver;
+    format?: string;
+}): IngestResult;

package/dist/src/core/ingest.js

@@ -0,0 +1,287 @@
+import { Store } from "./store/store.js";
+import { parseTree } from "./parse/tree.js";
+import { render } from "./parse/render.js";
+import { reconstructContent } from "./read/document.js";
+import { assignIds, writeBlockTree, putBlob, newCommit, writeRevision } from "./store/writers.js";
+import { sha256, normalizeVisibleText } from "./hash.js";
+import { mintId } from "./ids.js";
+import { keyBetween } from "./order-key.js";
+import { ftsDeleteDoc, ftsIndexDoc } from "./store/fts.js";
+import { rebuildSections } from "./store/sections.js";
+import { writeDocNodes, projectSectionNodes } from "./store/nodes.js";
+import { flattenFrontmatter, flattenComputed, writeDocProperties } from "./store/properties.js";
+import { maintainEdges, adoptPhantoms } from "./store/edges.js";
+import { parse as parseYaml } from "yaml";
+import { adapterForPath } from "../format/index.js";
+function extractFrontmatter(blocks) {
+    if (blocks.length > 0 && blocks[0].type === "frontmatter") {
+        return { fmBlock: blocks[0], rest: blocks.slice(1) };
+    }
+    return { fmBlock: null, rest: blocks };
+}
+// Parse a frontmatter block's raw (incl. --- fences) into a JSON-safe object.
+// Malformed YAML yields {} — frontmatter is queryable metadata, not load-bearing.
+function parseFrontmatter(fmBlock) {
+    if (!fmBlock)
+        return {};
+    const body = fmBlock.raw.replace(/^---\r?\n/, "").replace(/\r?\n?---\s*$/, "");
+    try {
+        const parsed = parseYaml(body);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function flatten(blocks, parent, depth, ancestorPath, out) {
+    let prevKey = null;
+    blocks.forEach((b, ordinal) => {
+        const orderKey = keyBetween(prevKey, null);
+        prevKey = orderKey;
+        const visible = normalizeVisibleText(b.raw, b.type);
+        out.push({
+            blockId: b.blockId,
+            parentBlock: parent,
+            orderKey,
+            ordinal,
+            depth,
+            ancestorPath,
+            type: b.type,
+            attrs: JSON.stringify(b.attrs),
+            text: visible,
+            rawHash: sha256(b.raw),
+            normHash: sha256(visible),
+            triviaHash: b.trivia.length > 0 ? sha256(b.trivia) : null,
+        });
+        if (b.children.length > 0) {
+            flatten(b.children, b.blockId, depth + 1, `${ancestorPath}${b.blockId}/`, out);
+        }
+    });
+}
+/** Ingest a single file's content into the store as one observed commit. */
+export function ingestFile(store, repoId, path, content, opts = {}) {
+    const ts = opts.ts ?? new Date().toISOString();
+    const origin = opts.origin ?? "observed";
+    const adapter = adapterForPath(path);
+    const format = opts.format ?? adapter?.format ?? "markdown";
+    return store.write((db) => {
+        const tree = adapter ? adapter.parse(content) : parseTree(content);
+        const { fmBlock, rest } = extractFrontmatter(tree.children);
+        // Frontmatter blob (markdown-specific) preserved for revision history.
+        const fmBlobHex = fmBlock ? putBlob(db, fmBlock.raw) : null;
+        // The exact separator bytes between the frontmatter block and the first body
+        // block (the frontmatter block's trailing trivia). Persisted so the body
+        // reconstructs byte-for-byte instead of assuming a canonical blank line.
+        // NULL when there is no frontmatter.
+        const fmTrivia = fmBlock ? fmBlock.trivia : null;
+        // Document property bag: adapter-provided for non-markdown formats,
+        // frontmatter-parsed for markdown. Flattened into the properties table
+        // below (source=frontmatter); also drives frontmatter edge extraction.
+        const metadata = (adapter?.extractMetadata)
+            ? (adapter.extractMetadata(content) ?? parseFrontmatter(fmBlock))
+            : parseFrontmatter(fmBlock);
+        // Upsert the document row.
+        let doc = db.prepare("SELECT doc_id FROM docs WHERE repo_id = ? AND path = ?").get(repoId, path);
+        const docId = doc?.doc_id ?? mintId("d");
+        const isNew = !doc;
+        if (!doc) {
+            db.prepare("INSERT INTO docs (doc_id, repo_id, path, format, leading_trivia, frontmatter_trivia) VALUES (?, ?, ?, ?, ?, ?)").run(docId, repoId, path, format, tree.leadingTrivia, fmTrivia);
+            doc = { doc_id: docId };
+            // Adopt phantom edges that pointed at this path so backlinks re-point.
+            adoptPhantoms(db, path, docId);
+        }
+        else {
+            db.prepare("UPDATE docs SET format = ?, leading_trivia = ?, frontmatter_trivia = ? WHERE doc_id = ?").run(format, tree.leadingTrivia, fmTrivia, docId);
+        }
+        // Assign block ids via the resolver when supplied (it reconciles against
+        // the prior revision — for a new doc that's an empty old tree, so all blocks
+        // mint — and also drives edge extraction). Without a resolver, fresh-mint.
+        const resolved = opts.resolveIds
+            ? opts.resolveIds(rest, isNew ? null : docId)
+            : { assigned: assignIds(rest), dispositions: [], deleted: [] };
+        const assigned = resolved.assigned;
+        const rootTreeHex = writeBlockTree(db, assigned);
+        const commit = newCommit(db, { repoId, ts, origin });
+        const renderedHash = sha256(content);
+        const rev = writeRevision(db, {
+            docId,
+            rootTreeHex,
+            frontmatterBlobHex: fmBlobHex,
+            renderedHash,
+            path,
+            commitId: commit.commitId,
+        });
+        // Snapshot deleted blocks into the resurrection pool BEFORE dropping the
+        // doc's rows (the ingest rebuilds current-state blocks wholesale).
+        if (resolved.deleted.length > 0) {
+            const expires = new Date(Date.parse(ts) + 30 * 24 * 3600 * 1000).toISOString();
+            const pool = db.prepare(`INSERT OR REPLACE INTO resurrection_pool (block_id, repo_id, doc_id, raw_hash, norm_hash, type, deleted_commit, expires_ts)
+         SELECT block_id, repo_id, doc_id, raw_hash, norm_hash, type, ?, ? FROM blocks WHERE block_id = ? AND doc_id = ?`);
+            for (const id of resolved.deleted)
+                pool.run(commit.commitId, expires, id, docId);
+        }
+        // Refresh current-state blocks (clear + repopulate with carried/minted ids).
+        // FTS is external-content: delete old index rows before dropping blocks.
+        ftsDeleteDoc(db, docId);
+        db.prepare("DELETE FROM blocks WHERE doc_id = ?").run(docId);
+        const rows = [];
+        flatten(assigned, null, 0, "/", rows);
+        const insert = db.prepare(`INSERT INTO blocks
+         (block_id, repo_id, doc_id, parent_block, order_key, ordinal, depth,
+          ancestor_path, type, attrs, text, raw_hash, norm_hash, trivia_hash, created_commit)
+       VALUES
+         (@blockId, @repoId, @docId, @parentBlock, @orderKey, @ordinal, @depth,
+          @ancestorPath, @type, @attrs, @text, @rawHash, @normHash, @triviaHash, @createdCommit)`);
+        for (const r of rows) {
+            insert.run({ ...r, repoId, docId, createdCommit: commit.commitId });
+        }
+        ftsIndexDoc(db, docId);
+        rebuildSections(db, docId);
+        // Node projection: adapter-provided semantic features from parsed blocks,
+        // plus engine-derived `md:section` nodes from the (just-rebuilt) sections
+        // table. Written together in one pass (writeDocNodes clears + repopulates).
+        const propertyRows = [];
+        const sectionNodes = projectSectionNodes(db, docId);
+        if (adapter?.projectNodes) {
+            // Zip assigned block ids onto the parsed blocks so projectNodes can anchor
+            // each node to its own block (the parsed RawBlocks are pre-identity).
+            const rawBlocks = zipAssignedIds(rest, assigned);
+            const projected = adapter.projectNodes(rawBlocks);
+            // Keep only nodes anchored to a real assigned block id.
+            const idSet = collectBlockIds(assigned);
+            const withIds = projected.map((n) => ({
+                ...n,
+                blockId: n.blockId && idSet.has(n.blockId) ? n.blockId : "",
+            }));
+            writeDocNodes(db, repoId, docId, [...withIds, ...sectionNodes]);
+            // Inline properties (key:: value) → property rows (source=inline). The
+            // authored shape within the inline source drives `card`: a key that occurs
+            // exactly once in the document is `scalar` (so `element == "fire"` can
+            // match a lone `element:: fire`); a key that repeats is `list`. Repeats
+            // accumulate as ord-indexed rows in document order (block ordinal, then
+            // in-block position — the order withIds already carries). Effective bare-
+            // key cardinality (a frontmatter+inline collision) is decided at query
+            // time by the single-value gate on scalar comparisons (see compile.ts),
+            // not here — each source stays honest to its own authored shape.
+            const inlineFields = withIds.filter((n) => n.kind === "md:inline_field" && n.name);
+            const inlineCounts = new Map();
+            for (const n of inlineFields)
+                inlineCounts.set(n.name, (inlineCounts.get(n.name) ?? 0) + 1);
+            const inlineOrd = new Map();
+            for (const n of inlineFields) {
+                const ord = inlineOrd.get(n.name) ?? 0;
+                inlineOrd.set(n.name, ord + 1);
+                propertyRows.push({
+                    source: "inline",
+                    blockId: n.blockId || null,
+                    key: n.name,
+                    card: (inlineCounts.get(n.name) ?? 0) > 1 ? "list" : "scalar",
+                    ord,
+                    ...typedInlineValue(n.value),
+                });
+            }
+        }
+        else if (sectionNodes.length > 0) {
+            // No adapter node projection, but the document still has sections.
+            writeDocNodes(db, repoId, docId, sectionNodes);
+        }
+        // Frontmatter → property rows (source=frontmatter). Flatten nested maps to
+        // dotted keys, arrays to ord-indexed list rows, scalars to a scalar row.
+        for (const r of flattenFrontmatter(metadata)) {
+            propertyRows.push({ source: "frontmatter", blockId: null, ...r });
+        }
+        // Computed → property rows (source=computed). Engine-derived $-intrinsics
+        // ($title, $tags) from the adapter; never claim authored keys.
+        if (adapter?.computeProperties) {
+            const computed = adapter.computeProperties(rest, metadata);
+            for (const r of flattenComputed(computed)) {
+                propertyRows.push({ source: "computed", blockId: null, ...r });
+            }
+        }
+        writeDocProperties(db, repoId, docId, commit.commitId, propertyRows);
+        // Edge extraction + interval maintenance (05 §2), if the resolver supplies
+        // an extractor. Runs in this commit transaction.
+        if (resolved.extractEdges) {
+            const extracted = resolved.extractEdges(docId, metadata);
+            maintainEdges(db, repoId, docId, commit.commitId, extracted);
+        }
+        // Persist dispositions + block-history projection. With a resolver, use the
+        // real reconciliation dispositions; otherwise record every block as inserted.
+        const dispositions = resolved.dispositions.length > 0 || opts.resolveIds
+            ? resolved.dispositions
+            : rows.map((r) => ({ blockId: r.blockId, kind: "inserted", confidence: null, reason: null, matcherV: null, detail: {} }));
+        const insDisp = db.prepare(`INSERT OR IGNORE INTO dispositions (commit_id, block_id, kind, confidence, reason, matcher_v, detail)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`);
+        const bc = db.prepare("INSERT OR IGNORE INTO block_changes (block_id, commit_id, kind) VALUES (?, ?, ?)");
+        for (const d of dispositions) {
+            insDisp.run(commit.commitId, d.blockId, d.kind, d.confidence, d.reason, d.matcherV, JSON.stringify(d.detail));
+            bc.run(d.blockId, commit.commitId, d.kind);
+        }
+        // Consumed pool rows (resurrected) are removed.
+        for (const id of resolved.consumedPool ?? []) {
+            db.prepare("DELETE FROM resurrection_pool WHERE block_id = ?").run(id);
+        }
+        // Update document current pointers + convergence hash.
+        const fileHash = sha256(content);
+        db.prepare("UPDATE docs SET current_rev = ?, file_hash = ? WHERE doc_id = ?").run(rev.revId, fileHash, docId);
+        // Convergence check (01 §2): file bytes vs rendered revision. Two independent
+        // round-trips must both reproduce the source exactly:
+        //   1. the freshly-parsed in-memory tree (validates the parser), and
+        //   2. a reload from storage (validates that persisted blocks + trivia +
+        //      frontmatter separator tile the source — the fidelity a plain read or
+        //      an `apply` write actually depends on). Rendering only the in-memory
+        //      tree hid store→reload separator loss; reconstructContent closes that.
+        const renderFn = adapter?.render ?? render;
+        const converged = fileHash.equals(renderedHash) &&
+            renderFn(tree) === content &&
+            reconstructContent(db, docId) === content;
+        return {
+            docId,
+            commitId: commit.commitId,
+            revId: rev.revId,
+            blockCount: rows.length,
+            converged,
+        };
+    });
+}
+// Zip assigned block ids onto the parsed RawBlocks for node projection. The
+// parsed `rest` and `assigned` trees are the same blocks in the same order and
+// nesting (assigned is a 1:1 id-carrying projection of rest), so we walk them in
+// lockstep and stamp each RawBlock's blockId. Returns fresh RawBlocks (originals
+// untouched — blockId is a projection-only field).
+function zipAssignedIds(parsed, assigned) {
+    return parsed.map((b, i) => {
+        const a = assigned[i];
+        return {
+            ...b,
+            ...(a ? { blockId: a.blockId } : {}),
+            children: a ? zipAssignedIds(b.children, a.children) : b.children,
+        };
+    });
+}
+// Inline field values arrive as captured strings; coerce to a typed column so
+// numeric/bool inline props (priority:: 3) compare like their frontmatter kin.
+// A value that isn't cleanly numeric/bool stays a string.
+function typedInlineValue(raw) {
+    const v = (raw ?? "").trim();
+    if (v === "true" || v === "false")
+        return { valText: null, valNum: null, valBool: v === "true" ? 1 : 0, valJson: null, type: "bool" };
+    if (v !== "" && Number.isFinite(Number(v)))
+        return { valText: null, valNum: Number(v), valBool: null, valJson: null, type: "number" };
+    return { valText: v, valNum: null, valBool: null, valJson: null, type: "string" };
+}
+function collectBlockIds(blocks) {
+    const ids = new Set();
+    const walk = (list) => {
+        for (const b of list) {
+            ids.add(b.blockId);
+            if (b.children.length > 0)
+                walk(b.children);
+        }
+    };
+    walk(blocks);
+    return ids;
+}
+//# sourceMappingURL=ingest.js.map

package/dist/src/core/order-key.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare function keyBetween(a: string | null, b: string | null): string;
+/** Generate n sequential append keys starting from scratch. */
+export declare function sequentialKeys(n: number): string[];