@omgbase/core 0.7.1 → 0.10.0

package/dist/src/oqx-js/store-index.js

@@ -0,0 +1,193 @@
+// Store-backed equality indexes for the OQX engine (`DataContext.indexFor`):
+// when a nested block's receiver is a ROOT SCAN (`^docs`, `^edges`,
+// a bare `docs` at the root scope) and its correlated or constant equality is on
+// a column or property SQLite can look up — `where $path == ^^$path`,
+// `where customer == ^$path`, `where $dst == ^$id`, `where type == "order"` —
+// the probe runs ONE prepared statement against the store's indexes instead of
+// materializing every row of the target and hashing it. The rows come back
+// exactly as the root scan constructs them (same columns, same `__path`, same
+// target tag, same `(path, id)` order) under the same live-row and repo guards
+// (`sql/scan.ts`), so every intrinsic and relation keeps working downstream and
+// the result cannot differ from the scan — only the work does.
+//
+// Typed equality (OQX SEMANTICS §5) is preserved by probing per VALUE KIND:
+//
+//   • a text column (`doc_id`, `path`, `type`, `kind`, `name`, `src_doc`, …)
+//     matches a string probe by `= ?` (TEXT = TEXT, exact); a number, boolean,
+//     object or any other non-string probe matches NO row (the column holds
+//     strings or NULL and `5 == "5"` is false); an absent probe (`null`,
+//     `undefined`: `name == null`) is answered by the in-memory fallback below;
+//   • a document property (`customer`, `$title`) matches a string probe only on
+//     a `type = 'string'` row (`val_text = ?`), a number probe only on a
+//     `type = 'number'` row (`val_num = ?`), a boolean only on a `type = 'bool'`
+//     row (`val_bool = ?`), each under the scalar-in-scope rule the in-memory
+//     `docProp` applies (exactly one live row for the key on the document and it
+//     is `card = 'scalar'`; a list-valued, repeated or nested key is an array or
+//     object in memory and equals no scalar). An object/array probe equals
+//     nothing (decoded values are fresh objects; §5 compares them by
+//     reference), `NaN` equals nothing; an absent probe (`key == null`: a `null`
+//     scalar OR a document lacking the key) is an anti-join SQLite has no index
+//     for, so it is answered by the fallback.
+//
+// The fallback — a probe value no statement covers — reads the collection once
+// (the same lazy root scan the engine would have walked) and filters it with
+// the context's own `get`, under `semantics.equals`: the engine's own hash
+// index could do no better, and the answer is by construction the scan's.
+//
+// `lookup(value)` (positions into the collection) is implemented for the seam's
+// contract but the engine never calls it for these indexes: it probes
+// `lookupRows` first and so never reads the root whole.
+import { semantics } from "@omgbase/oqx";
+import { NON_PROPERTY_NAMES, RESERVED_DOC_BASENAMES } from "./sql/translate.js";
+import { COLS, FROM, FROM_BY_DOC, ORDER, guards, guardsByDoc } from "./sql/scan.js";
+import { storagePath } from "../core/paths.js";
+// ---- which paths SQLite answers ------------------------------------------------
+/** The indexed TEXT column (or an equivalent indexed test) a one-segment local
+ * path reads, per target — the paths a probe pushes to SQLite. `?` is the
+ * probe value. Each is served by a primary key, a `UNIQUE`, or an index of
+ * `spec/store/schema.sql`: docs `doc_id` (PK) and `(repo_id, path)`; blocks
+ * `block_id` (PK), `idx_blocks_doc (doc_id, …)`, `idx_blocks_type (repo_id,
+ * type)`; nodes `node_id` (PK), `idx_nodes_doc`, `idx_nodes_kind`,
+ * `idx_nodes_name`; edges `edge_id` (PK), `idx_edges_src (src_doc, …)`,
+ * `idx_edges_dst (dst_node, …)`; `$path` on a joined target reaches the docs
+ * `(repo_id, path)` key and then the target's `doc_id`/`src_doc` index. */
+const COLUMN_PROBES = {
+    docs: { $id: "d.doc_id = ?", $path: "d.path = ?" },
+    blocks: { $id: "b.block_id = ?", $doc: "b.doc_id = ?", type: "b.type = ?", $path: "d.path = ?" },
+    nodes: { $id: "n.node_id = ?", $node_id: "n.node_id = ?", $doc_id: "n.doc_id = ?", kind: "n.kind = ?", name: "n.name = ?", $path: "d.path = ?" },
+    edges: {
+        $id: "e.edge_id = ?", $src: "e.src_doc = ?", $dst: "e.dst_node = ?", $path: "d.path = ?",
+        // `$dst_path` is the destination document's path (deleted or not — the
+        // intrinsic reads `docs` by id without a liveness guard). A destination is
+        // resolved within the edge's repo (spec/graph §3), where `(repo_id, path)`
+        // is UNIQUE, so the probe is that one document; `?r` is the repo id.
+        $dst_path: "e.dst_node IN (SELECT doc_id FROM docs WHERE repo_id = ?r AND path = ?)",
+    },
+};
+/** How a one-segment path on `target` is probed, or null when SQLite has no
+ * index for it (the engine then builds its own over the materialized scan). */
+function probeFor(target, path) {
+    if (path.length !== 1)
+        return null;
+    const key = path[0];
+    const column = COLUMN_PROBES[target][key];
+    if (column)
+        return { kind: "column", sql: column };
+    if (target !== "docs")
+        return null;
+    // A docs property: any bare name the context reads through `docProp` — not a
+    // relation / handle (`out`, `frontmatter`, …), not a reserved basename (a loud
+    // error in memory, left to the scan to raise), not the `format` column (not
+    // indexed), and of the intrinsics only `$title` (a computed scalar property).
+    if (key === "$title")
+        return { kind: "property", key: "$title", source: "computed" };
+    if (key.startsWith("$") || key === "format")
+        return null;
+    if (NON_PROPERTY_NAMES.docs.has(key) || RESERVED_DOC_BASENAMES.has(key))
+        return null;
+    return { kind: "property", key, source: null };
+}
+// ---- the index ---------------------------------------------------------------------
+class StoreIndex {
+    target;
+    path;
+    probe;
+    deps;
+    statements = new Map();
+    positions = null;
+    constructor(target, path, probe, deps) {
+        this.target = target;
+        this.path = path;
+        this.probe = probe;
+        this.deps = deps;
+    }
+    lookupRows(value) {
+        const v = value === undefined ? null : value;
+        if (v === null)
+            return this.fallback(null);
+        if (this.probe.kind === "column") {
+            if (typeof v !== "string")
+                return [];
+            // `$path` / `$dst_path` are the reference form in memory (`/a.md`,
+            // spec/surface §1 "Paths"); the column holds the storage form. A rooted
+            // probe is de-rooted; a bare one can equal no rooted path — no row.
+            if (this.path === "$path" || this.path === "$dst_path")
+                return v.startsWith("/") ? this.column(storagePath(v)) : [];
+            return this.column(v);
+        }
+        switch (typeof v) {
+            case "string": return this.property("p.type = 'string' AND p.val_text = ?", v);
+            case "number": return Number.isNaN(v) ? [] : this.property("p.type = 'number' AND p.val_num = ?", v);
+            case "boolean": return this.property("p.type = 'bool' AND p.val_bool = ?", v ? 1 : 0);
+            default: return []; // object, array, range, bigint, symbol: equals no decoded scalar
+        }
+    }
+    lookup(value) {
+        if (!this.positions) {
+            this.positions = new Map();
+            this.deps.rows().forEach((r, i) => this.positions.set(this.deps.identity(r), i));
+        }
+        const out = [];
+        for (const r of this.lookupRows(value)) {
+            const pos = this.positions.get(this.deps.identity(r));
+            if (pos !== undefined)
+                out.push(pos);
+        }
+        return out.sort((a, b) => a - b);
+    }
+    // A `$path` probe on a joined target drives from the document (`FROM_BY_DOC`),
+    // every other column probe from the target's own index. `?r` in a probe is
+    // the repo id, bound ahead of the value.
+    column(value) {
+        const t = this.target;
+        const probe = this.probe.sql;
+        const byDoc = t !== "docs" && this.path === "$path";
+        const g = byDoc ? guardsByDoc(t, this.deps.repoId) : guards(t, this.deps.repoId);
+        const from = byDoc ? FROM_BY_DOC[t] : FROM[t];
+        const params = probe.includes("?r") ? [this.deps.repoId, value] : [value];
+        const sql = `SELECT ${COLS[t]} FROM ${from} WHERE ${g.sql} AND ${probe.replace("?r", "?")} ORDER BY ${ORDER[t]}`;
+        return this.run(sql, [...g.params, ...params]);
+    }
+    // The scalar-in-scope rule as SQL: the document has exactly one live row for
+    // the key (within the source, for a sourced read) and that row is a scalar of
+    // the probe's type with the probe's value. The loop is driven from the
+    // properties index (`CROSS JOIN`: `idx_props_key_text` / `idx_props_key_num`,
+    // `(repo_id, key, val_*)`) and reaches the document by primary key; the count
+    // runs per candidate only, and with it at one no document repeats.
+    property(typed, bound) {
+        const { key, source } = this.probe;
+        const src = source === null ? "" : " AND p.source = ?";
+        const src2 = source === null ? "" : " AND p2.source = ?";
+        const g = guards("docs", this.deps.repoId);
+        const sql = `SELECT d.* FROM properties p CROSS JOIN docs d ON d.doc_id = p.doc_id
+      WHERE p.repo_id = ? AND p.key = ? AND ${typed} AND p.card = 'scalar' AND p.deleted_commit IS NULL${src}
+        AND ${g.sql}
+        AND (SELECT COUNT(*) FROM properties p2 WHERE p2.doc_id = d.doc_id AND p2.key = ? AND p2.deleted_commit IS NULL${src2}) = 1
+      ORDER BY ${ORDER.docs}`;
+        const params = [this.deps.repoId, key, bound, ...(source === null ? [] : [source]), ...g.params, key, ...(source === null ? [] : [source])];
+        return this.run(sql, params);
+    }
+    run(sql, params) {
+        let stmt = this.statements.get(sql);
+        if (!stmt)
+            this.statements.set(sql, (stmt = this.deps.db.prepare(sql)));
+        return this.deps.tag(stmt.all(...params), this.target);
+    }
+    // The scan's own answer for a probe no statement covers.
+    fallback(value) {
+        return this.deps.rows().filter((r) => semantics.equals(this.deps.get(r, this.path), value));
+    }
+}
+/** A store-backed `RowIndex` for the root scan of `target` on `path`, or
+ * `undefined` when SQLite has no index for the path (per-target table above;
+ * multi-segment paths; `format`, edge `predicate`/`src_field`, `$tags`, …). */
+export function storeIndexFor(target, path, deps) {
+    const probe = probeFor(target, path);
+    return probe ? new StoreIndex(target, path[0], probe, deps) : undefined;
+}
+/** The paths `storeIndexFor` answers from SQLite, per target (for tests and docs). */
+export function indexablePaths(target) {
+    const cols = Object.keys(COLUMN_PROBES[target]);
+    return target === "docs" ? [...cols, "$title", "<property key>"] : cols;
+}
+//# sourceMappingURL=store-index.js.map

package/dist/src/spec-versions.d.ts

@@ -1,5 +1,5 @@
 export declare const SPEC_VERSIONS: {
-    readonly oqx: "0.14";
+    readonly oqx: "0.18";
     readonly format: "0.2";
     readonly reconcile: "2.3";
     readonly store: "13.5";
@@ -8,7 +8,7 @@ export declare const SPEC_VERSIONS: {
     readonly search: "1.2";
     readonly mutate: "1.3";
     readonly sync: "1.3";
-    readonly surface: "1.4";
-    readonly cli: "1.2";
+    readonly surface: "2.0";
+    readonly cli: "2.0";
 };
 export type SpecName = keyof typeof SPEC_VERSIONS;

package/dist/src/spec-versions.js

@@ -19,7 +19,7 @@ export const SPEC_VERSIONS = {
     search: "1.2",
     mutate: "1.3",
     sync: "1.3",
-    surface: "1.4",
-    cli: "1.2",
+    surface: "2.0",
+    cli: "2.0",
 };
 //# sourceMappingURL=spec-versions.js.map

package/dist/src/surface-paths.d.ts

@@ -0,0 +1,33 @@
+import type { ApplyResult } from "./mutate/apply.js";
+import type { DocOpResult, DocMoveResult } from "./mutate/docs.js";
+import type { RetargetHit } from "./mutate/macros.js";
+import type { Opset } from "./mutate/opset.js";
+import type { DocsUpdateResult } from "./mutate/plan-update.js";
+import type { ObserveResult, ObserveDeleteResult } from "./sync/observe.js";
+import type { SweepResult } from "./sync/freshness.js";
+import type { TextSearchResult } from "./search/text.js";
+import type { ResolveHit } from "./search/resolve.js";
+/** `spec/mutate` §4's result: `revisions[].path` and the dry-run `diffs` keys. */
+export declare function surfaceApplyResult<T extends ApplyResult>(res: T): T;
+/** `docs_create` / `docs_delete` / `docs_set_meta`: `path` and the `diffs` keys. */
+export declare function surfaceDocOpResult<T extends DocOpResult>(res: T): T;
+/** `docs_move`: the document-op fields plus each dangling link's source `path`
+ *  (its `target` stays as authored — that is what the link says). */
+export declare function surfaceDocMoveResult(res: DocMoveResult): DocMoveResult;
+/** `observe` / `observe_many` outcomes. */
+export declare function surfaceObserveResult<T extends ObserveResult>(res: T): T;
+/** `observe_delete`. */
+export declare function surfaceObserveDeleteResult(res: ObserveDeleteResult): ObserveDeleteResult;
+/** `text_search` hits. */
+export declare function surfaceTextSearch(res: TextSearchResult): TextSearchResult;
+/** `resolve` hits: the locator is `<path>#<type>[<ordinal>]`; its path half is
+ *  rooted (a locator without `#` names no path and is left alone). */
+export declare function surfaceResolveHits(hits: ResolveHit[]): ResolveHit[];
+/** `links_retarget` / `links_repair` hits (`path` is the block's document). */
+export declare function surfaceRetargetHits(hits: RetargetHit[]): RetargetHit[];
+/** A whole-document update plan: `target.path` and `precondition.path`. */
+export declare function surfaceOpset(opset: Opset): Opset;
+/** `docs_update`: the opset and, when committed, the apply result. */
+export declare function surfaceDocsUpdate(res: DocsUpdateResult): DocsUpdateResult;
+/** `omg sync`'s one-shot sweep: the ingested / suppressed / deleted / conflicted paths. */
+export declare function surfaceSweepResult(res: SweepResult): SweepResult;

package/dist/src/surface-paths.js

@@ -0,0 +1,75 @@
+// The surface's path rule applied at its boundary (spec/surface §1 "Paths",
+// 2.0): every path a tool or verb returns is `/`-rooted. The surface-owned
+// readers (`core/read`, `graph/history`, `graph/link-health`, the query
+// binding) root their own output; the results that belong to another spec —
+// `spec/mutate`'s apply and document-operation results and opsets,
+// `spec/store`'s observe outcomes, `spec/search`'s hits, `spec/sync`'s sweep —
+// keep their storage-form paths in the library (their own fixtures pin them)
+// and are re-shaped HERE, by the MCP server and the `omg` verbs alike, so the
+// two clients cannot drift. Each function returns a new value; the input is
+// not mutated.
+import { referencePath, referenceKeyed } from "./core/paths.js";
+/** `spec/mutate` §4's result: `revisions[].path` and the dry-run `diffs` keys. */
+export function surfaceApplyResult(res) {
+    return {
+        ...res,
+        revisions: res.revisions.map((r) => ({ ...r, path: referencePath(r.path) })),
+        ...(res.diffs ? { diffs: referenceKeyed(res.diffs) } : {}),
+    };
+}
+/** `docs_create` / `docs_delete` / `docs_set_meta`: `path` and the `diffs` keys. */
+export function surfaceDocOpResult(res) {
+    return { ...res, path: referencePath(res.path), ...(res.diffs ? { diffs: referenceKeyed(res.diffs) } : {}) };
+}
+/** `docs_move`: the document-op fields plus each dangling link's source `path`
+ *  (its `target` stays as authored — that is what the link says). */
+export function surfaceDocMoveResult(res) {
+    return { ...surfaceDocOpResult(res), dangling: res.dangling.map((l) => ({ ...l, path: referencePath(l.path) })) };
+}
+/** `observe` / `observe_many` outcomes. */
+export function surfaceObserveResult(res) {
+    return { ...res, path: referencePath(res.path) };
+}
+/** `observe_delete`. */
+export function surfaceObserveDeleteResult(res) {
+    return { ...res, path: referencePath(res.path) };
+}
+/** `text_search` hits. */
+export function surfaceTextSearch(res) {
+    return { ...res, hits: res.hits.map((h) => ({ ...h, path: referencePath(h.path) })) };
+}
+/** `resolve` hits: the locator is `<path>#<type>[<ordinal>]`; its path half is
+ *  rooted (a locator without `#` names no path and is left alone). */
+export function surfaceResolveHits(hits) {
+    return hits.map((h) => {
+        const i = h.locator.indexOf("#");
+        return i < 0 ? h : { ...h, locator: referencePath(h.locator.slice(0, i)) + h.locator.slice(i) };
+    });
+}
+/** `links_retarget` / `links_repair` hits (`path` is the block's document). */
+export function surfaceRetargetHits(hits) {
+    return hits.map((h) => ({ ...h, path: referencePath(h.path) }));
+}
+/** A whole-document update plan: `target.path` and `precondition.path`. */
+export function surfaceOpset(opset) {
+    return {
+        ...opset,
+        target: { ...opset.target, path: referencePath(opset.target.path) },
+        precondition: { ...opset.precondition, path: referencePath(opset.precondition.path) },
+    };
+}
+/** `docs_update`: the opset and, when committed, the apply result. */
+export function surfaceDocsUpdate(res) {
+    return { opset: surfaceOpset(res.opset), result: res.result ? surfaceApplyResult(res.result) : null };
+}
+/** `omg sync`'s one-shot sweep: the ingested / suppressed / deleted / conflicted paths. */
+export function surfaceSweepResult(res) {
+    return {
+        ...res,
+        ingested: res.ingested.map(referencePath),
+        suppressed: res.suppressed.map(referencePath),
+        deleted: res.deleted.map(referencePath),
+        conflicted: res.conflicted.map(referencePath),
+    };
+}
+//# sourceMappingURL=surface-paths.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/core",
-  "version": "0.7.1",
+  "version": "0.10.0",
   "description": "Open Markdown Graph Base — embedded engine",
   "license": "MIT",
   "repository": {
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@omgbase/oqx": "^0.14.1",
+    "@omgbase/oqx": "^0.18.0",
     "better-sqlite3": "^13.0.3",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-frontmatter": "^2.0.1",