@omgbase/core 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,172 @@
+# @omgbase/core
+
+**Open Markdown Graph Base — the embedded engine.**
+
+`@omgbase/core` is a versioned, addressable graph layer over ordinary Markdown, YAML,
+and JSON files. The files stay the human source of truth for *content*; an embedded
+SQLite database (one per workspace, under `.omgbase/`) owns *identity, history, and
+derived indexes*: stable block ids that survive edits, block-grain commit history,
+a typed link/property graph, full-text + vector retrieval, and a six-op structural
+mutation kernel with content-hash CAS. At quiescence, `sha256(file)` equals the
+current revision's rendered hash for every tracked document. This package is the
+library; the `omg` CLI ([`omgbase`](https://www.npmjs.com/package/omgbase)) and the
+MCP server (`omg mcp`) are thin clients over it. The full as-built design lives in
+the [monorepo README](https://github.com/omgbase/omgbase#readme) and
+[`docs/`](https://github.com/omgbase/omgbase/tree/main/docs).
+
+## Install
+
+```bash
+npm install @omgbase/core
+```
+
+- **Node ≥ 22.** ESM only (`"type": "module"`; no CommonJS build).
+- SQLite is [`better-sqlite3`](https://www.npmjs.com/package/better-sqlite3), which
+  ships prebuilt binaries for common platforms; a compiler is only needed where no
+  prebuild exists.
+- No ML dependency. Semantic search is optional and talks to an external embedder
+  process/URL (e.g. `@omgbase/embedder`) over a small stdio/HTTP protocol.
+
+## Quick start
+
+Everything below was run as written against a scratch directory. A **workspace** is
+a directory holding `.omgbase/omgbase.db`; a **repo** is a set of documents whose
+bytes come from an attached source — here, a directory of Markdown.
+
+```js
+import { mkdirSync, writeFileSync } from "node:fs";
+import {
+  Workspace, ensureRepo, freshnessSweep,
+  oqxRun, findDoc, docsRead,
+  apply, tasksComplete, historyNode,
+} from "@omgbase/core";
+
+const wsDir = "/tmp/omg-demo";
+const root = `${wsDir}/notes`;
+mkdirSync(root, { recursive: true });
+writeFileSync(`${root}/todo.md`, "# Todo\n\n- [ ] write the README\n- [x] ship 0.1\n");
+
+const ws = Workspace.open(wsDir);                     // creates .omgbase/ + the SQLite db
+const repoId = ensureRepo(ws.store, "notes", root);   // repo row + an `fs` source rooted at `root`
+const sweep = freshnessSweep(ws.store, repoId, root); // ingest new/changed *.md as one checkpoint
+sweep.ingested;                                       // ["todo.md"]
+
+// Query with OQX. Nodes are projections of blocks; $block_id is the anchor block.
+const open = oqxRun(ws.store, repoId,
+  'select block: $block_id from nodes where kind == "md:task" && !attrs.checked');
+open.hits;  // [{ id: "n_…", path: "todo.md", block: "b_…" }]
+
+// Read a whole document back byte-exact, with block ids + CAS hashes.
+const doc = findDoc(ws.store, { repoId, path: "todo.md" });
+const read = docsRead(ws.store, doc.docId, { includeIds: true });
+read.content;  // "# Todo\n\n- [ ] write the README\n- [x] ship 0.1\n"
+read.ids;      // ["b_…", "b_…", "b_…", "b_…"]   read.hashes[id] → content_hash
+
+// Mutate. The macro expands to kernel `update` ops pinned by content_hash;
+// apply() renders, writes the file, and commits a new revision.
+const result = apply(ws.store, {
+  repoId,
+  rootPath: root,
+  omgbaseDir: ws.omgbaseDir,   // take the cross-process writer lock
+  ops: tasksComplete(ws.store, open.hits.map((h) => h.block)),
+  origin: { actor: "agent:quickstart", reason: "demo" },
+});
+result;  // { results: [{ ids: ["b_…"] }], revisions: [{ doc: "d_…", path: "todo.md" }], committed: true }
+// todo.md on disk now reads "- [x] write the README"
+
+historyNode(ws.store, open.hits[0].block);  // [{ origin: "import", kind: "edited", … }, { origin: "observed", kind: "inserted", … }]
+ws.close();
+```
+
+Raw kernel ops take the same route. An `update` whose `expect.content_hash` no
+longer matches throws a `MutationError` with `code: "stale_expectation"`:
+
+```js
+apply(ws.store, {
+  repoId, rootPath: root, omgbaseDir: ws.omgbaseDir,
+  ops: [{ op: "update", block: read.ids[1], markdown: "hello, world",
+          expect: { content_hash: read.hashes[read.ids[1]] } }],
+  origin: { actor: "agent:quickstart" },
+});
+```
+
+No filesystem at all? `new Store({ path: ":memory:" })`, `ensureRepo(store, slug, null)`,
+feed bytes with `observeFile(store, repoId, "a.md", text)`, and pass
+`docStore: new NullDocStore()` to `apply` — the DB is then the canonical artifact.
+
+## Surface map
+
+All of these are named exports of `@omgbase/core` (`src/index.ts`). Functions take
+the `Store` first and are synchronous unless noted.
+
+| Group | What it does | Key exports |
+| --- | --- | --- |
+| Store / workspace | Open the SQLite store (WAL, migrations to `SCHEMA_VERSION`); find a workspace by walking up for `.omgbase/`; list/select repos; layered settings | `Store`, `Workspace.open/find`, `Workspace#repos/selectRepo/close`, `ensureRepo`, `resolveSettings`, `workspaceSettings`, `writeWorkspaceSettings` |
+| Ingest / sync | Get file bytes into the repo as observed commits: one-shot sweep, batch checkpoint, headless observe, directory walk, external stdio adapters, live watcher, writer lock | `freshnessSweep`, `processCheckpoint`, `observeFile/observeMany/observeDelete`, `ingestDirectory`, `createSource/attachSourceToRepo/listSources`, `createExternalSource`, `reconcileChanges`, `Watcher`, `WatchLease`, `withWriterLock`, `reposStatus`, `syncStatus` |
+| Read | Byte-exact document read, outlines, block/node hydration, listings, ref resolution, cursors | `docsRead`, `docsOutline`, `nodesGet/nodesGetMany`, `findDoc`, `loadDocBlocks`, `blockRaw`, `docsList`, `docsTree`, `resolveRef`, `encodeCursor/decodeCursor` |
+| Mutate — kernel | The six ops (`insert/update/move/remove/split/merge`) applied atomically as one changeset with CAS; write target is pluggable | `apply`, `Op`, `ApplyRequest`, `Expect`, `To`, `DocStore`, `FsDocStore`, `NullDocStore`, `MutationError` |
+| Mutate — macros + doc ops | Op builders for common intents; whole-document create/move/delete/frontmatter; whole-document update planner | `tasksComplete`, `sectionsAppend`, `sectionsRename`, `sectionsMove`, `listsInsertItem`, `nodeSet`, `linksRetarget`, `docsCreate`, `docsMove`, `docsDelete`, `docsSetMeta`, `planUpdate`, `applyOpset`, `docsUpdate` |
+| OQX | Run an OQX query over the store (`docs`/`blocks`/`nodes`/`edges`); async variant embeds `semantic("…")` phrases first | `oqxRun`, `oqxRunAsync`, `parseOqx`, `collectSemanticPhrases`, `OqxResult`, `FilterInvalid` |
+| Graph / history | Block history, unified diffs between revisions, commit digests since a cursor, link edges | `historyNode`, `diffUnified`, `changesSince`, `docLinks`, `inboundLinksTo` |
+| Search | Ranked "what does the caller mean" resolution; RRF fusion of FTS + vectors; raw vector search | `resolve`, `hybridSearch`, `vectorSearch`, `docVectorSearch` |
+| Embeddings | Out-of-process embedder client, batching worker, post-mutation drainer, task builders | `createExternalProvider`, `EmbeddingWorker`, `EmbedDrainer`, `buildEmbedTasks`, `embeddingSettings`, `SemanticUnavailable` |
+| Format adapters | Register/lookup the parsers that turn a file into blocks + nodes + edges | `registerAdapter`, `adapterForPath`, `detectFormat`, `markdownAdapter`, `yamlAdapter`, `jsonAdapter` |
+| MCP server | Build the full tool surface (45 tools: `docs_read`, `query`, `apply`, `observe`, `changes_since`, …) as an `McpServer`; wire it to stdio | `buildServer({ store, repoId, rootPath?, embedQuery?, onMutation? })`, `serveStdio(ctx)` |
+| Admin | Rebuild derived indexes; garbage-collect unreferenced blobs | `rebuildIndex`, `runGc`, `VERSION`, `EngineError` |
+
+`omg mcp` is just a host for `serveStdio`: it opens the workspace, primes with
+`freshnessSweep`, optionally starts a `Watcher` and `EmbedDrainer`, then calls
+`serveStdio({ store, repoId, rootPath, embedQuery, onMutation })`. Embed the same
+server in your own process with `buildServer(ctx)` and any MCP SDK transport.
+
+## Data model in 10 lines
+
+1. A **repo** (`rp_`) owns identity and history; its bytes come from attached sources (a directory, or nothing).
+2. A **doc** (`d_`) is one file at a repo-relative path, in a format (`markdown`, `yaml`, `json`).
+3. A doc is an ordered tree of **blocks** (`b_`): paragraphs, headings, list items, fences, YAML entries, JSON properties…
+4. Block ids are minted once and threaded through re-ingests by the reconciler, so they survive edits and moves.
+5. Blocks are the **mutation anchors**: every kernel op addresses `b_` ids; `expect.content_hash` (sha256 of the block's raw bytes) is the CAS token.
+6. **Nodes** (`n_`) are semantic projections of blocks — `md:task`, `md:heading`, `md:section`, `md:link`, `md:wikilink`, `md:anchor`, `md:inline_field` — queryable but derived; `$block_id` points back at the anchor.
+7. **Edges** are typed links between blocks/docs (wikilinks, `$ref`, frontmatter relations) with commit intervals.
+8. Every ingest or mutation appends a **commit** (`c_`) and a per-doc **revision** (`r_`) whose rendered hash equals the file's bytes.
+9. Commits carry `origin` (`observed` from disk, `import` from `apply`) and an actor; `historyNode`/`changesSince` read them back.
+10. Indexes (FTS, properties table, sections, embeddings) are derived and rebuildable; the schema is `SCHEMA_VERSION = 13`.
+
+## Query language
+
+OQX is the standalone [`@omgbase/oqx`](https://www.npmjs.com/package/@omgbase/oqx)
+engine bound to the store (`src/oqx-js/`): omgbase supplies a `DataContext` over
+`docs`/`blocks`/`nodes`/`edges` and a SQLite pushdown planner, and the library
+supplies the language (`select … from … where … follow … order by … limit … offset …`, in that fixed order,
+consumers `collect/count/exists/none/first/single`, nested blocks, `^` outer
+references, `entries()`, `values`). Row-scoped predicates like `text("…")` (FTS)
+and `semantic("…")` (embedding score) are omgbase additions.
+
+```js
+oqxRun(ws.store, repoId, `
+  select $path, $title, open: nodes collect { select $block_id where kind == "md:task" && !attrs.checked }
+  from docs where nodes count { where kind == "md:task" && !attrs.checked } >= 2
+  order by $path limit 10
+`);
+// hits: [{ id: "d_…", path: "more.md", $path: "more.md", $title: "More", open: [{ $block_id: "b_…" }, …] }]
+```
+
+See [`docs/query-language.md`](https://github.com/omgbase/omgbase/blob/main/docs/query-language.md)
+for the omgbase surface (targets, fields, scoping, execution model) and the
+[`@omgbase/oqx` README](https://github.com/omgbase/omgbase/blob/main/packages/oqx/README.md)
+for the language itself.
+
+## Where the truth lives
+
+Code wins over prose. When in doubt, read these in the monorepo:
+
+- `packages/core/src/index.ts` — the exported surface (this README's tables are derived from it).
+- `packages/core/src/mcp/server.ts` — every MCP tool, its schema, and its inline description.
+- `packages/core/src/core/store/schema.ts` — the SQLite DDL, `SCHEMA_VERSION`, and migrations.
+- `packages/core/src/mutate/` — the six kernel ops, CAS, macros, and the whole-document planner.
+- `packages/core/src/oqx-js/` — the OQX `DataContext` + planner; `corpus/oqx/README.md` has runnable query examples.
+- `docs/` — as-built design references (`architecture.md`, `data-model.md`, `mutation-and-concurrency.md`, `graph-and-query.md`, `mcp-api.md`, `surface-map.md`); the repo-root `AGENTS.md` indexes them.
+
+## License
+
+MIT

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

@@ -1,8 +1,13 @@
-import { runEval } from "../reconcile/eval/metrics.js";
+import { runEval, type EvalMode } from "../reconcile/eval/metrics.js";
 export interface EvalCliOptions {
     n?: number;
     size?: number;
     intensity?: number;
+    mode?: EvalMode;
+    itemWords?: number;
+    contextSimFloor?: number;
+    thetaAccept?: number;
+    thetaSmall?: number;
 }
 export declare function formatReport(report: ReturnType<typeof runEval>): string;
 /** Run the eval and return the report + a pass/fail against release gates. */

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

@@ -2,7 +2,8 @@ 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}`);
+    const mode = report.mode === "structured" ? `  mode=structured` : "";
+    lines.push(`matcher_v=${report.config.matcherV}  cases=${report.cases}${mode}`);
     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));
@@ -12,13 +13,24 @@ export function formatReport(report) {
 }
 /** Run the eval and return the report + a pass/fail against release gates. */
 export function evalMatcher(opts = {}) {
-    const runOpts = { config: DEFAULT_CONFIG };
+    const overrides = {};
+    if (opts.contextSimFloor !== undefined)
+        overrides.contextSimFloor = opts.contextSimFloor;
+    if (opts.thetaAccept !== undefined)
+        overrides.thetaAccept = opts.thetaAccept;
+    if (opts.thetaSmall !== undefined)
+        overrides.thetaSmall = opts.thetaSmall;
+    const runOpts = { config: DEFAULT_CONFIG, configOverrides: overrides };
     if (opts.n !== undefined)
         runOpts.n = opts.n;
     if (opts.size !== undefined)
         runOpts.size = opts.size;
     if (opts.intensity !== undefined)
         runOpts.intensity = opts.intensity;
+    if (opts.mode !== undefined)
+        runOpts.mode = opts.mode;
+    if (opts.itemWords !== undefined)
+        runOpts.itemWords = opts.itemWords;
     const report = runEval(runOpts);
     const gatesPass = checkGates(report);
     return { report, text: formatReport(report), gatesPass };

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

@@ -5,7 +5,31 @@ 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;
+/** The minimal tree shape visibleText() needs; RawBlock, TreeInputBlock and FlatSource all satisfy it. */
+export interface VisibleTextBlock {
+    type: string;
+    raw: string;
+    children: readonly VisibleTextBlock[];
+}
+/** Container blocks compose their text from children (spec/format §4.1). */
+export declare function isTextContainer(type: string, hasChildren: boolean): boolean;
+/** Blockquote depth of a block's children given the block's own depth. */
+export declare function childQuoteDepth(type: string, quoteDepth: number): number;
+/** Container rule: children's texts in order, joined by one space, empties skipped. */
+export declare function joinVisibleTexts(texts: readonly string[]): string;
+/**
+ * `text` for a block in its tree. `quoteDepth` is the number of blockquote
+ * ancestors of `block` itself (0 at the top level).
+ */
+export declare function visibleText(block: VisibleTextBlock, quoteDepth?: number): string;
+/**
+ * Leaf rule (spec/format §4.1 steps 1–7): strip up to `quoteDepth` blockquote
+ * markers from every line after the first, then the kind's own syntax, then
+ * normalize whitespace (trim each line with the JS trim set, collapse `[ \t]+`,
+ * drop empty lines, join with one space, NFC). Inline syntax is content.
+ * Call this only for leaves — containers go through visibleText().
+ */
+export declare function normalizeVisibleText(raw: string, type: string, quoteDepth?: number): 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;

package/dist/src/core/hash.js

@@ -29,18 +29,118 @@ export function normalizeText(raw) {
         .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]*$/, "");
+/** Container blocks compose their text from children (spec/format §4.1). */
+export function isTextContainer(type, hasChildren) {
+    return type === "list" || type === "blockquote" || type === "table" || ((type === "list_item" || type === "task") && hasChildren);
+}
+/** Blockquote depth of a block's children given the block's own depth. */
+export function childQuoteDepth(type, quoteDepth) {
+    return type === "blockquote" ? quoteDepth + 1 : quoteDepth;
+}
+/** Container rule: children's texts in order, joined by one space, empties skipped. */
+export function joinVisibleTexts(texts) {
+    return texts.filter((t) => t.length > 0).join(" ");
+}
+/**
+ * `text` for a block in its tree. `quoteDepth` is the number of blockquote
+ * ancestors of `block` itself (0 at the top level).
+ */
+export function visibleText(block, quoteDepth = 0) {
+    if (isTextContainer(block.type, block.children.length > 0)) {
+        const inner = childQuoteDepth(block.type, quoteDepth);
+        return joinVisibleTexts(block.children.map((c) => visibleText(c, inner)));
+    }
+    return normalizeVisibleText(block.raw, block.type, quoteDepth);
+}
+const LINE_ENDING = /\r\n|\r|\n/;
+const FENCE_OPEN = /^ {0,3}(`{3,}|~{3,})/;
+const QUOTE_MARKER = /^[ \t]*> ?/;
+// A `|` is escaped iff preceded by an odd number of backslashes (GFM: `\|` is
+// content, `\\|` is an escaped backslash followed by a delimiter).
+function isEscapedAt(line, i) {
+    let n = 0;
+    for (let j = i - 1; j >= 0 && line[j] === "\\"; j--)
+        n++;
+    return n % 2 === 1;
+}
+// table_row: one leading `|`, one trailing unescaped `|` (each with surrounding
+// spaces/tabs), then every remaining unescaped `|` becomes a space.
+function stripTableRow(line) {
+    let s = line.replace(/^[ \t]*\|/, "");
+    const trimmedEnd = s.replace(/[ \t]+$/, "");
+    if (trimmedEnd.endsWith("|") && !isEscapedAt(trimmedEnd, trimmedEnd.length - 1))
+        s = trimmedEnd.slice(0, -1);
+    let out = "";
+    for (let i = 0; i < s.length; i++) {
+        out += s[i] === "|" && !isEscapedAt(s, i) ? " " : s[i];
+    }
+    return out;
+}
+/**
+ * Leaf rule (spec/format §4.1 steps 1–7): strip up to `quoteDepth` blockquote
+ * markers from every line after the first, then the kind's own syntax, then
+ * normalize whitespace (trim each line with the JS trim set, collapse `[ \t]+`,
+ * drop empty lines, join with one space, NFC). Inline syntax is content.
+ * Call this only for leaves — containers go through visibleText().
+ */
+export function normalizeVisibleText(raw, type, quoteDepth = 0) {
+    let lines = raw.split(LINE_ENDING);
+    // 1. Blockquote markers on continuation lines (the first line starts at content).
+    if (quoteDepth > 0) {
+        for (let i = 1; i < lines.length; i++) {
+            let line = lines[i];
+            for (let q = 0; q < quoteDepth; q++) {
+                const m = QUOTE_MARKER.exec(line);
+                if (!m)
+                    break;
+                line = line.slice(m[0].length);
+            }
+            lines[i] = line;
+        }
     }
-    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]+/, "");
+    // 2. Kind syntax.
+    switch (type) {
+        case "heading": {
+            if (lines.length > 1) {
+                lines.pop(); // setext: content lines + the underline
+            }
+            else {
+                // ATX: the opening run (which may be the whole line), then a closing
+                // run of `#` that is the entire remainder or follows a space/tab.
+                lines[0] = (lines[0] ?? "").replace(/^ {0,3}#{1,6}[ \t]*/, "").replace(/(?:^|[ \t]+)#+[ \t]*$/, "");
+            }
+            break;
+        }
+        case "frontmatter":
+            lines = lines.slice(1, -1);
+            break;
+        case "code_fence": {
+            const open = FENCE_OPEN.exec(lines[0] ?? "");
+            if (open) {
+                lines = lines.slice(1);
+                const fence = open[1];
+                const closer = new RegExp(`^ {0,3}\\${fence[0]}{${fence.length},}[ \\t]*$`);
+                if (lines.length > 0 && closer.test(lines[lines.length - 1]))
+                    lines.pop();
+            }
+            break;
+        }
+        case "list_item":
+        case "task": {
+            lines[0] = (lines[0] ?? "").replace(/^[ \t]*([-*+]|[0-9]+[.)])[ \t]+/, "").replace(/^\[[ xX]\][ \t]+/, "");
+            break;
+        }
+        case "table_row":
+            lines = lines.map(stripTableRow);
+            break;
+        case "thematic_break":
+            lines = [];
+            break;
+        default:
+            break; // paragraph, html_block, opaque: nothing
     }
-    return normalizeText(s);
+    // 3–7.
+    return normalizeText(lines.join("\n"));
 }
 /** norm_hash — sha256 of the normalized text (02 §1, §5.2). */
 export function normHash(normalizedText) {

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

@@ -1,5 +1,17 @@
 export type IdPrefix = "d" | "b" | "c" | "r" | "x" | "col" | "cp" | "e" | "rp" | "v" | "src";
 export declare function randomSuffix(len?: number): string;
+/** A replacement id generator (spec/store §2.2): given a prefix, return the whole id. */
+export type IdMinter = (prefix: IdPrefix) => string;
+/** Install a replacement minter (null restores the CSPRNG default). */
+export declare function setIdMinter(minter: IdMinter | null): void;
+/** Run `body` with `minter` installed, restoring the previous minter afterwards (also on throw). */
+export declare function withIdMinter<T>(minter: IdMinter, body: () => T): T;
+/**
+ * The fixture minter (spec/store §2.2): a sequential per-prefix counter —
+ * `d_0, d_1, …`, `b_0, …`, each prefix counting from 0 independently. A fresh
+ * instance per case resets every counter.
+ */
+export declare function sequentialMinter(): IdMinter;
 /** 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;

package/dist/src/core/ids.js

@@ -8,11 +8,53 @@ export function randomSuffix(len = ID_LEN) {
         s += ALPHABET[randomInt(ALPHABET.length)];
     return s;
 }
+// The installed minter, or null for production (CSPRNG). spec/store §2.2: the
+// store's tree hashes contain block ids, so a fixture runner installs a
+// deterministic per-prefix counter here to make ids comparable across
+// implementations. Every mint in the engine — documents, blocks (including
+// the reconcile module's phase 7 mints), commits, revisions, repos, sources —
+// goes through `mintId`, so one seam covers them all.
+let installed = null;
+/** Install a replacement minter (null restores the CSPRNG default). */
+export function setIdMinter(minter) {
+    installed = minter;
+}
+/** Run `body` with `minter` installed, restoring the previous minter afterwards (also on throw). */
+export function withIdMinter(minter, body) {
+    const previous = installed;
+    installed = minter;
+    try {
+        return body();
+    }
+    finally {
+        installed = previous;
+    }
+}
+/**
+ * The fixture minter (spec/store §2.2): a sequential per-prefix counter —
+ * `d_0, d_1, …`, `b_0, …`, each prefix counting from 0 independently. A fresh
+ * instance per case resets every counter.
+ */
+export function sequentialMinter() {
+    const counters = new Map();
+    return (prefix) => {
+        const n = counters.get(prefix) ?? 0;
+        counters.set(prefix, n + 1);
+        return `${prefix}_${n}`;
+    };
+}
 /** Mint an ID with the given prefix. Collision checking is the store's job. */
 export function mintId(prefix) {
+    if (installed)
+        return installed(prefix);
     return `${prefix}_${randomSuffix()}`;
 }
-const ID_RE = new RegExp(`^([a-z]+)_([${ALPHABET}]{${ID_LEN}})$`);
+// Production ids carry exactly ID_LEN suffix characters; the fixture minter
+// (spec/store §2.2) mints `d_0`, `b_12`, … — one to seven alphabet characters.
+// The id-or-path dispatch (`findDocByRef`, `insert.doc`, history) must treat
+// both as ids: nothing else in the system is spelled `<prefix>_<alnum>` (paths
+// carry an extension), so accepting the shorter suffix loses no path.
+const ID_RE = new RegExp(`^([a-z]+)_([${ALPHABET}]{1,${ID_LEN}})$`);
 export function isValidId(id, prefix) {
     const m = ID_RE.exec(id);
     if (!m)

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

@@ -1,6 +1,6 @@
 import { Store } from "./store/store.js";
 import { type TreeInputBlock } from "./store/writers.js";
-import type { RawBlock } from "./parse/types.js";
+import type { RawBlock, BlockTree } from "./parse/types.js";
 export interface DispositionRow {
     blockId: string;
     kind: string;
@@ -24,8 +24,22 @@ export type IdResolver = (rest: RawBlock[], docId: string | null) => {
     dispositions: DispositionRow[];
     deleted: string[];
     consumedPool?: string[];
+    /** Ids carried INTO this document from another one in the same checkpoint
+     * (cross-document moves, reconciliation-spec §8). The other doc may still hold
+     * a `blocks` row for them (it commits later in the batch, or was tombstoned);
+     * ingest evicts those rows so the id can be re-homed regardless of order. */
+    crossDocIds?: string[];
     extractEdges?: (docId: string, frontmatter: Record<string, unknown>) => ResolvedEdgeRow[];
 };
+/** The parse step of ingest, exported so a batch caller can parse + reconcile
+ * every document of a checkpoint BEFORE committing any (the cross-document
+ * phase needs all per-doc results first) and hand the tree back via
+ * `opts.parsed`. Frontmatter is split off: `rest` is what the IdResolver sees. */
+export declare function parseForIngest(path: string, content: string): {
+    tree: BlockTree;
+    fmBlock: RawBlock | null;
+    rest: RawBlock[];
+};
 export interface IngestResult {
     docId: string;
     commitId: string;
@@ -37,7 +51,13 @@ export interface IngestResult {
 /** 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";
+    /** Commit provenance. `observed` = a file edit picked up by sync; `api` = an intent write (apply/docs_*), which should also carry `actor`/`reason`; `import` = bulk ingest with no retro history. */
+    origin?: "observed" | "import" | "api";
+    actor?: string | null;
+    reason?: string | null;
     resolveIds?: IdResolver;
     format?: string;
+    /** A tree already parsed from `content` (via `parseForIngest`) — skips the
+     * re-parse. The caller guarantees it is the parse of these exact bytes. */
+    parsed?: BlockTree;
 }): IngestResult;