@omgbase/core 0.15.0 → 0.21.0

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

@@ -10,6 +10,8 @@ export interface DispositionRow {
     matcherV: string | null;
     detail: Record<string, unknown>;
 }
+/** spec/store §5.4 step 10 (14.2): which verdicts the store persists — every kind but `same`. */
+export declare function persistsDisposition(kind: string): boolean;
 export interface ResolvedEdgeRow {
     srcDoc: string;
     srcBlock: string | null;

package/dist/src/core/ingest.js

@@ -13,6 +13,10 @@ import { flattenFrontmatter, flattenComputed, writeDocProperties } from "./store
 import { maintainEdges, adoptPhantoms } from "./store/edges.js";
 import { parse as parseYaml } from "yaml";
 import { adapterForPath } from "../format/index.js";
+/** spec/store §5.4 step 10 (14.2): which verdicts the store persists — every kind but `same`. */
+export function persistsDisposition(kind) {
+    return kind !== "same";
+}
 /** 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
@@ -279,10 +283,19 @@ export function ingestInto(db, repoId, path, content, opts) {
     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: {} }));
+    // spec/store §5.4 step 10 (14.2): a `same` verdict is not persisted. The
+    // matcher (and the known-id resolver) still produce one per untouched block
+    // — the outcome counts them — but the table records what CHANGED, so a
+    // block's `updated_at` (MAX commit ts over its `block_changes`) and its
+    // `blocks_history` are the block's own changes, not its siblings'. Every
+    // other kind — the first revision's `inserted` rows the mint oracle (§2.1)
+    // depends on included — is written as before.
     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) {
+        if (!persistsDisposition(d.kind))
+            continue;
         insDisp.run(commitId, d.blockId, d.kind, d.confidence, d.reason, d.matcherV, JSON.stringify(d.detail));
         bc.run(d.blockId, commitId, d.kind);
     }

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

@@ -76,6 +76,15 @@ export declare function docsReadMany(store: Store, repoId: string, refs: string[
     includeIds?: boolean;
     budgetTokens?: number;
 }): DocsReadManyResult;
+/**
+ * `docs_read { at }` / `docs_read_at` (spec/surface §2, 4.7): the document AS
+ * OF a revision. No `properties`: the properties table is current-state only
+ * (`spec/properties`), and recomputing the bag from the reconstructed bytes is
+ * not yet a one-call affair of the format layer (the inline fields come out of
+ * the ingest's node projection) — so the time-travel read carries the bytes
+ * and nothing it would have to guess at (through 4.6 `docs_read_at` returned
+ * the CURRENT bag flagged `propertiesAreCurrent: true`).
+ */
 export interface DocsReadAtResult {
     id: string;
     /** The path as of that revision, in the reference form. */
@@ -88,14 +97,6 @@ export interface DocsReadAtResult {
      *  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

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

@@ -204,8 +204,6 @@ export function readDocumentAtRevision(store, docId, revId) {
         rev: revId,
         raw: content,
         renderedHashMatch,
-        properties: surfaceProperties(docPropertiesGrouped(db, docId)),
-        propertiesAreCurrent: true,
     };
 }
 //# sourceMappingURL=document.js.map

package/dist/src/core/store/gc.d.ts

@@ -2,16 +2,28 @@ import type { Store } from "./store.js";
 export interface GcResult {
     blobsSwept: number;
     treeNodesSwept: number;
+    /** spec/store §7 (14.2): `same` rows a 14.1 store wrote into `dispositions`/`block_changes` — history nothing reads. */
+    sameDispositionsSwept: number;
 }
+/** The `same` rows a store through 14.1 persisted (spec/store §7, 14.2). */
+export declare function countSameDispositions(store: Store): number;
 /**
  * Mark-and-sweep GC (flag-gated; enabled must be true to run — v1.0 ships it
  * off). Removes blobs/tree_nodes unreachable from any revision root. Because
  * revisions are append-only and never pruned in v1, nothing is actually
- * unreachable unless revision pruning ran first — so this is a no-op in a
+ * unreachable unless revision pruning ran first — so that half is a no-op in a
  * default v1 repo, exactly as specified. Rebuild-equivalence is preserved.
+ *
+ * spec/store §7 (14.2): the same sweep deletes every `same` row of
+ * `dispositions` and `block_changes` — what a 14.1 store wrote for every
+ * untouched block of every commit, and nothing reads (`updated_at` and
+ * `blocks_history` are the block's own changes now). Not a migration: a
+ * data-only change needs no `user_version`, and opening a database must never
+ * bulk-delete. `dryRun` counts everything and deletes nothing.
  */
 export declare function runGc(store: Store, opts?: {
     enabled?: boolean;
+    dryRun?: boolean;
 }): GcResult;
 /** Resurrection-pool expiry sweep (02 §7): drop rows past their expires_ts.
  * Runs routinely (lazy, at checkpoint time). */

package/dist/src/core/store/gc.js

@@ -29,24 +29,37 @@ function markReachable(store) {
         walk(r.root_tree.toString("hex"));
     return { trees, blobs };
 }
+/** The `same` rows a store through 14.1 persisted (spec/store §7, 14.2). */
+export function countSameDispositions(store) {
+    return store.db.prepare("SELECT count(*) AS c FROM dispositions WHERE kind = 'same'").get().c;
+}
 /**
  * Mark-and-sweep GC (flag-gated; enabled must be true to run — v1.0 ships it
  * off). Removes blobs/tree_nodes unreachable from any revision root. Because
  * revisions are append-only and never pruned in v1, nothing is actually
- * unreachable unless revision pruning ran first — so this is a no-op in a
+ * unreachable unless revision pruning ran first — so that half is a no-op in a
  * default v1 repo, exactly as specified. Rebuild-equivalence is preserved.
+ *
+ * spec/store §7 (14.2): the same sweep deletes every `same` row of
+ * `dispositions` and `block_changes` — what a 14.1 store wrote for every
+ * untouched block of every commit, and nothing reads (`updated_at` and
+ * `blocks_history` are the block's own changes now). Not a migration: a
+ * data-only change needs no `user_version`, and opening a database must never
+ * bulk-delete. `dryRun` counts everything and deletes nothing.
  */
 export function runGc(store, opts = {}) {
     if (!opts.enabled)
-        return { blobsSwept: 0, treeNodesSwept: 0 };
+        return { blobsSwept: 0, treeNodesSwept: 0, sameDispositionsSwept: 0 };
     return store.write((db) => {
         const { trees, blobs } = markReachable(store);
+        const dry = Boolean(opts.dryRun);
         let treeNodesSwept = 0;
         const allTrees = db.prepare("SELECT hash FROM tree_nodes").all();
         const delTree = db.prepare("DELETE FROM tree_nodes WHERE hash = ?");
         for (const t of allTrees)
             if (!trees.has(t.hash.toString("hex"))) {
-                delTree.run(t.hash);
+                if (!dry)
+                    delTree.run(t.hash);
                 treeNodesSwept++;
             }
         let blobsSwept = 0;
@@ -54,10 +67,16 @@ export function runGc(store, opts = {}) {
         const delBlob = db.prepare("DELETE FROM blobs WHERE hash = ?");
         for (const b of allBlobs)
             if (!blobs.has(b.hash.toString("hex"))) {
-                delBlob.run(b.hash);
+                if (!dry)
+                    delBlob.run(b.hash);
                 blobsSwept++;
             }
-        return { blobsSwept, treeNodesSwept };
+        const sameDispositionsSwept = countSameDispositions(store);
+        if (!dry && sameDispositionsSwept > 0) {
+            db.prepare("DELETE FROM block_changes WHERE kind = 'same'").run();
+            db.prepare("DELETE FROM dispositions WHERE kind = 'same'").run();
+        }
+        return { blobsSwept, treeNodesSwept, sameDispositionsSwept };
     });
 }
 /** Resurrection-pool expiry sweep (02 §7): drop rows past their expires_ts.

package/dist/src/core/store/size.d.ts

@@ -0,0 +1,79 @@
+import type { Store } from "./store.js";
+export declare const SIZE_CATEGORIES: readonly ["content", "history", "search", "sync"];
+export type SizeCategory = (typeof SIZE_CATEGORIES)[number];
+/** spec/store §7: the category of every table `schema.sql` creates. */
+export declare const TABLE_CATEGORY: Readonly<Record<string, SizeCategory>>;
+/** The category of a table: the spec's assignment, `sync` for anything else. */
+export declare function categoryOf(table: string): SizeCategory;
+export interface SizeTable {
+    name: string;
+    /** Pages of the table and its indexes (and shadow tables), in bytes; null without dbstat. */
+    bytes: number | null;
+    /** `bytes` over the total, one decimal; null without dbstat. */
+    share: number | null;
+    rows: number;
+    /** The bytes of the table's indexes alone (included in `bytes`); null without dbstat. */
+    indexes: number | null;
+}
+export interface SizeCategoryReport {
+    name: SizeCategory;
+    bytes: number | null;
+    share: number | null;
+    rows: number;
+    /** By bytes desc then name (rows desc then name without dbstat). */
+    tables: SizeTable[];
+}
+export interface SizeFile {
+    path: string;
+    /** The main file's bytes on disk (`page_count * page_size` for an in-memory database). */
+    bytes: number;
+    /** The `-wal` file's bytes on disk, 0 when absent. */
+    wal_bytes: number;
+    page_size: number;
+    page_count: number;
+    freelist_count: number;
+    /** `freelist_count * page_size`: what `VACUUM` returns to the filesystem. */
+    reclaimable: number;
+}
+export interface SizeReport {
+    file: SizeFile;
+    /** Always the four categories, in the fixed order content, history, search, sync. */
+    categories: SizeCategoryReport[];
+    /** spec/store §7 (14.2): `dispositions` rows with `kind = 'same'` — what a store through 14.1 wrote and `omg gc` removes. */
+    same_dispositions: number;
+    advice: string[];
+    /** Present only when the SQLite build lacks `dbstat` (row counts only). */
+    detail?: "dbstat unavailable";
+}
+/** The advice thresholds (spec/store §7). */
+export declare const VACUUM_ADVICE_MIN_BYTES: number;
+export declare const VACUUM_ADVICE_MIN_SHARE = 10;
+export declare const HISTORY_ADVICE_MIN_SHARE = 50;
+export declare const SAME_ADVICE_MIN_SHARE = 25;
+export declare const EMBEDDINGS_ADVICE_MIN_SHARE = 25;
+/**
+ * `<n> B` under 1024, else one decimal of KB/MB/GB/TB (1024-based), the tenths
+ * rounded half up — `4096` → `4.0 KB`, `13734297` → `13.1 MB`. Both engines
+ * format from the integer tenths so the bytes never differ by a rounding mode.
+ */
+export declare function humanBytes(n: number): string;
+/** A share as `<n>.<d>%` from its one-decimal value (`48.2` → `48.2%`, `50` → `50.0%`). */
+export declare function formatShare(share: number): string;
+/** `bytes / total` in percent, one decimal, rounded half up; 0 when the total is 0. */
+export declare function shareOf(bytes: number, total: number): number;
+/** spec/store §7: the advice lines, in this order; `nothing to reclaim` when none applies. */
+export declare function sizeAdvice(file: SizeFile, categories: SizeCategoryReport[], sameDispositions?: number): string[];
+/** The size report of an open store (spec/store §7 "Size"). */
+export declare function sizeReport(store: Store): SizeReport;
+export interface VacuumResult {
+    /** `freelist_count * page_size` before the `VACUUM`: the bytes it returned. */
+    reclaimable: number;
+}
+/**
+ * `VACUUM` the database (spec/store §7). Not a transaction's work — SQLite
+ * refuses a VACUUM inside one — so it runs on the bare connection; returns the
+ * free-page bytes measured before, which is what the file shrinks by.
+ */
+export declare function vacuum(store: Store): VacuumResult;
+/** `freelist_count * page_size`: the bytes a `VACUUM` would return now. */
+export declare function reclaimableBytes(store: Store): number;

package/dist/src/core/store/size.js

@@ -0,0 +1,232 @@
+import { statSync } from "node:fs";
+// The size report (spec/store §7 "Size", 14.1): what the database is made of,
+// table by table through SQLite's `dbstat` virtual table, grouped into the four
+// categories a reader reasons about — the live state (`content`), the
+// append-only record (`history`), the derived indexes (`search`) and the
+// workspace bookkeeping (`sync`) — plus the file's page accounting and the
+// deterministic advice `omg doctor --size` prints. The categorization is the
+// spec's: every table of `schema.sql` is assigned, an index counts toward its
+// table, an FTS5 virtual table's shadow tables fold into it, and anything the
+// spec does not name (`sqlite_schema`, `sqlite_stat1`, a table from a newer
+// schema) is `sync`.
+export const SIZE_CATEGORIES = ["content", "history", "search", "sync"];
+/** spec/store §7: the category of every table `schema.sql` creates. */
+export const TABLE_CATEGORY = {
+    docs: "content",
+    blocks: "content",
+    sections: "content",
+    nodes: "content",
+    edges: "content",
+    doc_edges: "content",
+    inferred_edges: "content",
+    external_nodes: "content",
+    properties: "content",
+    collections: "content",
+    blobs: "history",
+    tree_nodes: "history",
+    revisions: "history",
+    commits: "history",
+    dispositions: "history",
+    block_changes: "history",
+    resurrection_pool: "history",
+    pending_materializations: "history",
+    blocks_fts: "search",
+    nodes_fts: "search",
+    embeddings: "search",
+    doc_embeddings: "search",
+    repos: "sync",
+    sources: "sync",
+    adapters: "sync",
+    attachments: "sync",
+    checkpoints: "sync",
+    file_stats: "sync",
+    sync_state: "sync",
+    workspace_settings: "sync",
+};
+/** The category of a table: the spec's assignment, `sync` for anything else. */
+export function categoryOf(table) {
+    return TABLE_CATEGORY[table] ?? "sync";
+}
+/** The advice thresholds (spec/store §7). */
+export const VACUUM_ADVICE_MIN_BYTES = 1024 * 1024;
+export const VACUUM_ADVICE_MIN_SHARE = 10;
+export const HISTORY_ADVICE_MIN_SHARE = 50;
+export const SAME_ADVICE_MIN_SHARE = 25;
+export const EMBEDDINGS_ADVICE_MIN_SHARE = 25;
+/**
+ * `<n> B` under 1024, else one decimal of KB/MB/GB/TB (1024-based), the tenths
+ * rounded half up — `4096` → `4.0 KB`, `13734297` → `13.1 MB`. Both engines
+ * format from the integer tenths so the bytes never differ by a rounding mode.
+ */
+export function humanBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let v = n / 1024;
+    let u = 0;
+    while (v >= 1024 && u < units.length - 1) {
+        v /= 1024;
+        u++;
+    }
+    const tenths = Math.round(v * 10);
+    return `${Math.floor(tenths / 10)}.${tenths % 10} ${units[u]}`;
+}
+/** A share as `<n>.<d>%` from its one-decimal value (`48.2` → `48.2%`, `50` → `50.0%`). */
+export function formatShare(share) {
+    const tenths = Math.round(share * 10);
+    return `${Math.floor(tenths / 10)}.${tenths % 10}%`;
+}
+/** `bytes / total` in percent, one decimal, rounded half up; 0 when the total is 0. */
+export function shareOf(bytes, total) {
+    if (total <= 0)
+        return 0;
+    return Math.round((bytes * 1000) / total) / 10;
+}
+/** spec/store §7: the advice lines, in this order; `nothing to reclaim` when none applies. */
+export function sizeAdvice(file, categories, sameDispositions = 0) {
+    const advice = [];
+    const logical = file.page_count * file.page_size;
+    if (file.reclaimable > VACUUM_ADVICE_MIN_BYTES && file.reclaimable * 100 > logical * VACUUM_ADVICE_MIN_SHARE) {
+        advice.push(`run \`omg gc --vacuum\` to return ${humanBytes(file.reclaimable)} of free pages to the filesystem`);
+    }
+    const history = categories.find((c) => c.name === "history");
+    if (history && history.share !== null && history.share > HISTORY_ADVICE_MIN_SHARE) {
+        advice.push(`history dominates (${formatShare(history.share)}): blobs, tree nodes and dispositions grow with every commit — enable gc (\`omg config set gc.enabled true\`) and run \`omg gc --vacuum\``);
+    }
+    // 14.2: `same` rows are what a 14.1 store wrote for every untouched block;
+    // past a quarter of the table they are worth a sweep (the share is over rows,
+    // so it holds with or without dbstat).
+    const dispositionRows = history?.tables.find((t) => t.name === "dispositions")?.rows ?? 0;
+    if (sameDispositions > 0 && sameDispositions * 100 > dispositionRows * SAME_ADVICE_MIN_SHARE) {
+        advice.push(`${sameDispositions} same dispositions are history nothing reads (store 14.2): \`omg gc\` removes them, \`--vacuum\` reclaims the pages`);
+    }
+    const search = categories.find((c) => c.name === "search");
+    if (search && search.bytes !== null) {
+        const total = categories.reduce((n, c) => n + (c.bytes ?? 0), 0);
+        const embBytes = search.tables.filter((t) => t.name === "embeddings" || t.name === "doc_embeddings").reduce((n, t) => n + (t.bytes ?? 0), 0);
+        const embShare = shareOf(embBytes, total);
+        if (embShare > EMBEDDINGS_ADVICE_MIN_SHARE) {
+            advice.push(`embeddings are ${formatShare(embShare)} of the database: a smaller model (\`embedding.model\` / \`embedding.dim\`) or \`omg embed drain --prune\` after a model switch shrinks them`);
+        }
+    }
+    if (advice.length === 0)
+        advice.push("nothing to reclaim");
+    return advice;
+}
+/** The `dbstat` bytes per b-tree name, or null when the build lacks the virtual table. */
+function dbstatBytes(store) {
+    try {
+        const rows = store.db.prepare("SELECT name, sum(pgsize) AS bytes FROM dbstat GROUP BY name").all();
+        return new Map(rows.map((r) => [r.name, Number(r.bytes)]));
+    }
+    catch {
+        return null;
+    }
+}
+/** The size report of an open store (spec/store §7 "Size"). */
+export function sizeReport(store) {
+    const db = store.db;
+    const path = db.name === "" ? ":memory:" : db.name;
+    const page_size = db.pragma("page_size", { simple: true });
+    const page_count = db.pragma("page_count", { simple: true });
+    const freelist_count = db.pragma("freelist_count", { simple: true });
+    const onDisk = path !== ":memory:";
+    const fileBytes = (p) => {
+        try {
+            return statSync(p).size;
+        }
+        catch {
+            return 0;
+        }
+    };
+    const file = {
+        path,
+        bytes: onDisk ? fileBytes(path) : page_count * page_size,
+        wal_bytes: onDisk ? fileBytes(`${path}-wal`) : 0,
+        page_size,
+        page_count,
+        freelist_count,
+        reclaimable: freelist_count * page_size,
+    };
+    const master = db.prepare("SELECT type, name, tbl_name, sql FROM sqlite_master").all();
+    const virtuals = master.filter((r) => r.type === "table" && /^CREATE VIRTUAL TABLE/i.test(r.sql ?? "")).map((r) => r.name);
+    // A shadow table (`blocks_fts_data`, …) folds into its virtual table.
+    const ownerOf = (name) => virtuals.find((v) => name.startsWith(`${v}_`)) ?? name;
+    const stat = dbstatBytes(store);
+    // Every table: sqlite_master's (shadow tables folded into their owner), plus
+    // the schema table itself, which sqlite_master does not list but dbstat does.
+    const tableNames = new Set(["sqlite_schema"]);
+    for (const r of master)
+        if (r.type === "table")
+            tableNames.add(ownerOf(r.name));
+    if (stat)
+        for (const name of stat.keys())
+            if (!master.some((r) => r.name === name && r.type === "index"))
+                tableNames.add(ownerOf(name));
+    const indexBytes = new Map();
+    const tableBytes = new Map();
+    if (stat) {
+        for (const [name, bytes] of stat) {
+            const idx = master.find((r) => r.type === "index" && r.name === name);
+            if (idx) {
+                indexBytes.set(idx.tbl_name, (indexBytes.get(idx.tbl_name) ?? 0) + bytes);
+                tableBytes.set(idx.tbl_name, (tableBytes.get(idx.tbl_name) ?? 0) + bytes);
+            }
+            else {
+                const owner = ownerOf(name);
+                tableBytes.set(owner, (tableBytes.get(owner) ?? 0) + bytes);
+            }
+        }
+    }
+    const total = stat ? [...stat.values()].reduce((n, b) => n + b, 0) : 0;
+    const countRows = (name) => {
+        // An external-content FTS5 table answers `count(*)` from its content table;
+        // the rows it indexes are its `_docsize` shadow's.
+        const from = virtuals.includes(name) ? `${name}_docsize` : name;
+        try {
+            return db.prepare(`SELECT count(*) AS c FROM "${from.replace(/"/g, '""')}"`).get().c;
+        }
+        catch {
+            return 0;
+        }
+    };
+    const byCategory = new Map(SIZE_CATEGORIES.map((c) => [c, []]));
+    for (const name of tableNames) {
+        const bytes = stat ? (tableBytes.get(name) ?? 0) : null;
+        byCategory.get(categoryOf(name)).push({
+            name,
+            bytes,
+            share: bytes === null ? null : shareOf(bytes, total),
+            rows: countRows(name),
+            indexes: stat ? (indexBytes.get(name) ?? 0) : null,
+        });
+    }
+    const byBytesThenName = (a, b) => (b.bytes ?? b.rows) - (a.bytes ?? a.rows) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    const categories = SIZE_CATEGORIES.map((name) => {
+        const tables = byCategory.get(name).sort(byBytesThenName);
+        const bytes = stat ? tables.reduce((n, t) => n + (t.bytes ?? 0), 0) : null;
+        return { name, bytes, share: bytes === null ? null : shareOf(bytes, total), rows: tables.reduce((n, t) => n + t.rows, 0), tables };
+    });
+    const same_dispositions = db.prepare("SELECT count(*) AS c FROM dispositions WHERE kind = 'same'").get().c;
+    const report = { file, categories, same_dispositions, advice: sizeAdvice(file, categories, same_dispositions) };
+    if (!stat)
+        report.detail = "dbstat unavailable";
+    return report;
+}
+/**
+ * `VACUUM` the database (spec/store §7). Not a transaction's work — SQLite
+ * refuses a VACUUM inside one — so it runs on the bare connection; returns the
+ * free-page bytes measured before, which is what the file shrinks by.
+ */
+export function vacuum(store) {
+    const reclaimable = reclaimableBytes(store);
+    store.db.exec("VACUUM");
+    return { reclaimable };
+}
+/** `freelist_count * page_size`: the bytes a `VACUUM` would return now. */
+export function reclaimableBytes(store) {
+    const page_size = store.db.pragma("page_size", { simple: true });
+    const freelist_count = store.db.pragma("freelist_count", { simple: true });
+    return freelist_count * page_size;
+}
+//# sourceMappingURL=size.js.map

package/dist/src/index.d.ts

@@ -28,7 +28,7 @@ export { createExternalSource, type ExternalSourceSpec } from "./sync/external-s
 export { ensureAdapter, listAdapters, createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, renderConfigFlags, type AdapterRow, type SourceRow, } from "./sync/sources.js";
 export { reconcileChanges, attachSource } from "./sync/driver.js";
 export { observeFile, observeMany, observeOne, observeDelete, observeBatch, type ObserveResult, type ObserveOneResult, type ObserveDeleteResult, type BatchItem, type BatchOutcome } from "./sync/observe.js";
-export { buildServer, WRITE_TOOLS, type ServerContext } from "./mcp/server.js";
+export { buildServer, toolDescriptions, toolNames, unknownTool, UNKNOWN_TOOL_CODE, WRITE_TOOLS, MINIMAL_TOOLS, PROFILES, TOOLS_PROFILES, parseToolsProfile, type ServerContext, type ToolsProfile } from "./mcp/server.js";
 export { serveStdio, type ServeStdioHandle } from "./mcp/stdio.js";
 export { processCheckpoint, type CheckpointResult } from "./sync/checkpoint.js";
 export { reposStatus, syncStatus, reposList, type RepoStatus, type SyncStatus, type DiskStatus, type ReposList } from "./sync/admin.js";
@@ -67,9 +67,12 @@ export { canonicalDocPath, composeFile, splitFrontmatter, planInboundRetarget }
 export { createEffects, moveDocEffects, deleteDocEffects, setMetaEffects, updateContentEffects, insertEffects, updateBlockEffects, moveBlocksEffects, removeBlocksEffects, splitEffects, mergeEffects, checkEffects, nodeSetEffects, appendEffects, docsAppendEffects, retargetEffects, guardOf, requireAbsentPath, applySugar, createdDoc, docOutcome, moveLinks, type Sugar, type SugarDoc, type SugarRequest, type DocOpOutcome, type MoveLinks, } from "./mutate/sugar.js";
 export { planEffects, executePlan, executeByDigest, applyEffects, applyEffectsDetailed, substituteSymbols, admitPlan, canonicalJson, planDigest, PLAN_VERSION, PLANNER_V, type Plan, type PlanCore, type PlanOpset, type PlanPreconditions, type PlanPreview, type Receipt, type PlanEffectsRequest, type ExecuteRequest, } from "./mutate/plan.js";
 export { validateEffects, EFFECT_OPS, type Effect, type EffectTarget, type EffectExpect, type ResolvedEffect, type CreateEntry, type RetargetPreview } from "./mutate/effects.js";
+export { compileSelection, selectionQuery, SELECTION_CEILING, type Selection, type SelectionExpect, type CompiledSelection } from "./mutate/select.js";
+export { oqxRunQuery, reservedAlias } from "./oqx-js/run.js";
 export { inboundLinksTo, retargetLinksInRaw, type InboundLink } from "./graph/inbound-links.js";
 export { planUpdate, type PlanUpdateOptions } from "./mutate/plan-update.js";
 export { opsetKernelOps, renderOpsetPlan, renderIdentityPlan, type IdentityPreview, serializeOpset, parseOpset, type Opset, type PlanOp, type OpsetSummary, type OpsetPrecondition, type PlanDisposition, } from "./mutate/opset.js";
 export { rebuildIndex, type RebuildTarget } from "./core/store/rebuild.js";
 export { runGc, type GcResult } from "./core/store/gc.js";
+export { sizeReport, sizeAdvice, vacuum, reclaimableBytes, humanBytes, formatShare, shareOf, categoryOf, TABLE_CATEGORY, SIZE_CATEGORIES, type SizeReport, type SizeCategory, type SizeCategoryReport, type SizeTable, type SizeFile, type VacuumResult, } from "./core/store/size.js";
 export { LIVE_LEAF_SQL, ftsIndexedRowCount, liveLeafCount } from "./core/store/fts.js";

package/dist/src/index.js

@@ -28,7 +28,7 @@ export { createExternalSource } from "./sync/external-source.js";
 export { ensureAdapter, listAdapters, createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, renderConfigFlags, } from "./sync/sources.js";
 export { reconcileChanges, attachSource } from "./sync/driver.js";
 export { observeFile, observeMany, observeOne, observeDelete, observeBatch } from "./sync/observe.js";
-export { buildServer, WRITE_TOOLS } from "./mcp/server.js";
+export { buildServer, toolDescriptions, toolNames, unknownTool, UNKNOWN_TOOL_CODE, WRITE_TOOLS, MINIMAL_TOOLS, PROFILES, TOOLS_PROFILES, parseToolsProfile } from "./mcp/server.js";
 export { serveStdio } from "./mcp/stdio.js";
 export { processCheckpoint } from "./sync/checkpoint.js";
 export { reposStatus, syncStatus, reposList } from "./sync/admin.js";
@@ -78,6 +78,9 @@ export { createEffects, moveDocEffects, deleteDocEffects, setMetaEffects, update
 // The Effect layer (ADR-021, spec/mutate §11): plan / execute / apply { effects } and the plan's shapes.
 export { planEffects, executePlan, executeByDigest, applyEffects, applyEffectsDetailed, substituteSymbols, admitPlan, canonicalJson, planDigest, PLAN_VERSION, PLANNER_V, } from "./mutate/plan.js";
 export { validateEffects, EFFECT_OPS } from "./mutate/effects.js";
+// Query-directed planning (spec/mutate §11.8, 3.1): the selector binding behind `plan`/`apply`/`execute { select }`.
+export { compileSelection, selectionQuery, SELECTION_CEILING } from "./mutate/select.js";
+export { oqxRunQuery, reservedAlias } from "./oqx-js/run.js";
 // Inbound-link discovery + destination-aware rewrite (docs_move's dangling report / retarget_inbound).
 export { inboundLinksTo, retargetLinksInRaw } from "./graph/inbound-links.js";
 // Whole-document update: reconcile → opset (the `set content` effect's internal planner since 3.0; `preview.identity` surfaces it).
@@ -85,5 +88,6 @@ export { planUpdate } from "./mutate/plan-update.js";
 export { opsetKernelOps, renderOpsetPlan, renderIdentityPlan, serializeOpset, parseOpset, } from "./mutate/opset.js";
 export { rebuildIndex } from "./core/store/rebuild.js";
 export { runGc } from "./core/store/gc.js";
+export { sizeReport, sizeAdvice, vacuum, reclaimableBytes, humanBytes, formatShare, shareOf, categoryOf, TABLE_CATEGORY, SIZE_CATEGORIES, } from "./core/store/size.js";
 export { LIVE_LEAF_SQL, ftsIndexedRowCount, liveLeafCount } from "./core/store/fts.js";
 //# sourceMappingURL=index.js.map

package/dist/src/mcp/arguments.d.ts

@@ -4,8 +4,16 @@ import { EngineError } from "./errors.js";
 export type ArgShape = Record<string, z.ZodTypeAny>;
 /** The `(tool takes …)` tail: names in bytewise order, `?` on the optional ones. */
 export declare function argumentsHint(tool: string, shape: ArgShape): string;
-/** A `filter_invalid` for an argument-shape failure: the message plus the tool's shape. */
-export declare function argumentError(tool: string, message: string, shape: ArgShape): EngineError;
+/** A `filter_invalid` for an argument-shape failure: the message plus the tool's shape — and a `fix` (4.5, spec/surface §4) when the corrected call can be spelled. */
+export declare function argumentError(tool: string, message: string, shape: ArgShape, fix?: string): EngineError;
+/** The schema of a string-list argument: an array of strings, or one bare string (normalized to `[s]` by `validateArguments`). */
+export declare function stringList(opts?: {
+    min?: number;
+}): z.ZodType<string[]>;
+/** Is this argument a string list (through `optional`/`nullable`)? */
+export declare function isStringList(schema: z.ZodTypeAny): boolean;
+/** The parts of a comma-joined string: split on `,`, trimmed, empty parts dropped. */
+export declare function commaSplit(s: string): string[];
 /**
  * Validate `raw` against `shape`: unknown names first (in bytewise order), then
  * each declared argument (bytewise order) for presence and type. Returns the

package/dist/src/mcp/arguments.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { EngineError } from "./errors.js";
+import { canonicalJson } from "../mutate/canonical.js";
 /** The `(tool takes …)` tail: names in bytewise order, `?` on the optional ones. */
 export function argumentsHint(tool, shape) {
     const names = Object.keys(shape).sort(cmpBytes);
@@ -7,10 +8,33 @@ export function argumentsHint(tool, shape) {
         return `${tool} takes no arguments`;
     return `${tool} takes ${names.map((n) => (isOptional(shape[n]) ? `${n}?` : n)).join(", ")}`;
 }
-/** A `filter_invalid` for an argument-shape failure: the message plus the tool's shape. */
-export function argumentError(tool, message, shape) {
+/** A `filter_invalid` for an argument-shape failure: the message plus the tool's shape — and a `fix` (4.5, spec/surface §4) when the corrected call can be spelled. */
+export function argumentError(tool, message, shape, fix) {
     const full = `${message} (${argumentsHint(tool, shape)})`;
-    return new EngineError("filter_invalid", full, { data: { reason: full, hint: "arguments" } });
+    return new EngineError("filter_invalid", full, { data: { reason: full, hint: "arguments", ...(fix !== undefined ? { fix } : {}) } });
+}
+// ---- string lists (spec/surface §4 "Arguments", 4.5) ---------------------------------
+//
+// Every list-of-strings argument (`docs`, `ids`, `roots`, `blocks`, `select`,
+// `unset`) also takes ONE bare string as a one-element list — the first guess
+// of a caller who has one ref. A comma-joined string is still "must be an array
+// of strings", but that error carries a `fix`: the same call with the string
+// split on commas (each part trimmed, empty parts dropped), canonical JSON.
+const STRING_LISTS = new WeakSet();
+/** The schema of a string-list argument: an array of strings, or one bare string (normalized to `[s]` by `validateArguments`). */
+export function stringList(opts = {}) {
+    const list = opts.min !== undefined ? z.array(z.string()).min(opts.min) : z.array(z.string());
+    const schema = z.union([list, z.string()]);
+    STRING_LISTS.add(schema);
+    return schema;
+}
+/** Is this argument a string list (through `optional`/`nullable`)? */
+export function isStringList(schema) {
+    return STRING_LISTS.has(unwrap(schema));
+}
+/** The parts of a comma-joined string: split on `,`, trimmed, empty parts dropped. */
+export function commaSplit(s) {
+    return s.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
 }
 /**
  * Validate `raw` against `shape`: unknown names first (in bytewise order), then
@@ -36,6 +60,14 @@ export function validateArguments(tool, shape, raw) {
                 throw argumentError(tool, `\`${key}\` is required`, shape);
             continue;
         }
+        if (isStringList(schema) && typeof value === "string") {
+            // (4.5) one bare string is a one-element list; a comma-joined one is the
+            // array error with the split list as its `fix`.
+            if (value.includes(","))
+                throw argumentError(tool, `\`${key}\` must be an array of strings`, shape, canonicalJson({ ...args, [key]: commaSplit(value) }));
+            out[key] = [value];
+            continue;
+        }
         const parsed = schema.safeParse(value);
         if (!parsed.success)
             throw argumentError(tool, issueMessage(key, schema, parsed.error.issues), shape);
@@ -141,6 +173,8 @@ function unwrap(schema) {
 }
 /** The expected-type phrase of an argument, as the Rust catalog spells it from its JSON schema. */
 export function phraseFor(schema) {
+    if (isStringList(schema))
+        return "an array of strings";
     const d = defOf(unwrap(schema));
     switch (d.type) {
         case "string": return "a string";

package/dist/src/mcp/errors.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = "stale_expectation" | "parent_missing" | "target_missing" | "block_missing" | "doc_missing" | "cycle_move" | "opaque_block" | "not_contiguous" | "type_mismatch" | "conflicted_document" | "path_taken" | "create_conflict" | "ambiguous_locator" | "ambiguous_heading" | "filter_invalid" | "budget_exceeded" | "provider_unavailable" | "embedder_failed" | "sync_conflict" | "repo_not_found" | "node_not_editable" | "seed_unresolved" | "block_not_container" | "stale_plan" | "plan_not_convergent" | "conflicting_effects" | "unsupported_plan_version" | "plan_mismatch";
+export type ErrorCode = "stale_expectation" | "parent_missing" | "target_missing" | "block_missing" | "doc_missing" | "cycle_move" | "opaque_block" | "not_contiguous" | "type_mismatch" | "conflicted_document" | "path_taken" | "create_conflict" | "ambiguous_locator" | "ambiguous_heading" | "filter_invalid" | "budget_exceeded" | "provider_unavailable" | "embedder_failed" | "sync_conflict" | "repo_not_found" | "node_not_editable" | "seed_unresolved" | "block_not_container" | "stale_plan" | "plan_not_convergent" | "conflicting_effects" | "unsupported_plan_version" | "plan_mismatch" | "ambiguous_target" | "selection_too_large";
 export interface EngineErrorBody {
     error: ErrorCode;
     message: string;