@omgbase/core 0.8.0 → 0.10.0

package/dist/src/oqx-js/sql/translate.js

@@ -39,6 +39,8 @@
 // translated (that is the only context `partitionPushable` pushes into). `||`,
 // `!`, `in`, `matches` (needs a regexp UDF), and bare content-property routing
 // are deliberately declined here and left residual for now.
+import { storagePath } from "../../core/paths.js";
+import { TARGETS } from "../root-row.js";
 // ---- names that are never property reads ------------------------------------
 /**
  * Per target, the bare identifiers (and `doc.<k>` keys, via the docs set) that
@@ -59,7 +61,15 @@ export const NON_PROPERTY_NAMES = {
 // A `$`-namespaced intrinsic → a param-free SQL scalar, per target, with its kind.
 // Anything not mapped (e.g. docs `$body`, reconstructed; `$title`/`$tags`,
 // computed) returns null → residual. `$updated_at`/`$dst_path`/`$dst_uri` are
-// correlated subqueries.
+// correlated subqueries. `$path` and `$dst_path` are the REFERENCE form on the
+// surface (spec/surface §1 "Paths", 2.0) — `'/' || <storage column>` in SQL —
+// so every comparison, `startsWith`, `contains`, `lower()`… sees exactly the
+// string the in-memory intrinsic yields; `pathColumn` keeps the bare indexed
+// column at hand for the equality fast path.
+/** The rooted path read over a storage path column. */
+export function pathColumn(col) {
+    return { sql: `('/' || ${col})`, params: [], kind: "text", pathCol: col };
+}
 function intrinsicSql(name, ctx) {
     const { self, doc, target } = ctx;
     const text = (sql) => ({ sql, params: [], kind: "text" });
@@ -67,7 +77,7 @@ function intrinsicSql(name, ctx) {
     if (target === "docs")
         switch (name) {
             case "$id": return text(`${self}.doc_id`);
-            case "$path": return text(`${doc}.path`);
+            case "$path": return pathColumn(`${doc}.path`);
             case "$content_hash": return text(`lower(hex(${self}.file_hash))`);
             case "$updated_at": return text(`(SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = ${self}.current_rev)`);
         }
@@ -75,7 +85,7 @@ function intrinsicSql(name, ctx) {
         switch (name) {
             case "$id": return text(`${self}.block_id`);
             case "$doc": return text(`${self}.doc_id`);
-            case "$path": return text(`${doc}.path`);
+            case "$path": return pathColumn(`${doc}.path`);
             case "$ordinal": return int(`${self}.ordinal`);
             case "$depth": return int(`${self}.depth`);
             case "$body": return text(`${self}.text`);
@@ -87,7 +97,7 @@ function intrinsicSql(name, ctx) {
             case "$node_id": return text(`${self}.node_id`);
             case "$doc_id": return text(`${self}.doc_id`);
             case "$block_id": return text(`${self}.block_id`);
-            case "$path": return text(`${doc}.path`);
+            case "$path": return pathColumn(`${doc}.path`);
         }
     else if (target === "edges")
         switch (name) {
@@ -97,8 +107,8 @@ function intrinsicSql(name, ctx) {
             case "$src_block": return text(`${self}.src_block`);
             case "$via": return text(`${self}.via_node`);
             case "$from_commit": return text(`${self}.from_commit`);
-            case "$path": return text(`${doc}.path`);
-            case "$dst_path": return text(`(SELECT dd.path FROM docs dd WHERE dd.doc_id = ${self}.dst_node)`);
+            case "$path": return pathColumn(`${doc}.path`);
+            case "$dst_path": return text(`(SELECT '/' || dd.path FROM docs dd WHERE dd.doc_id = ${self}.dst_node)`);
             case "$dst_uri": return text(`(SELECT xn.uri FROM external_nodes xn WHERE xn.node_id = ${self}.dst_node)`);
         }
     return null;
@@ -177,8 +187,9 @@ export function translateOperand(e, ctx) {
             if (e.name.startsWith("$"))
                 return intrinsicSql(e.name, ctx);
             // A relation, reach-through, source handle or the whole attrs object is not a
-            // scalar read (decline (b)).
-            if (NON_PROPERTY_NAMES[target].has(e.name))
+            // scalar read (decline (b)); a bare target name is a relation or a loud
+            // error (root-row.ts), never a property.
+            if (NON_PROPERTY_NAMES[target].has(e.name) || TARGETS.has(e.name))
                 return null;
             // Bare field per target.
             if (target === "docs") {
@@ -224,15 +235,15 @@ export function translateOperand(e, ctx) {
                     return null;
                 const k = rest[0];
                 if (k === "$path")
-                    return text(`${doc}.path`);
+                    return pathColumn(`${doc}.path`);
                 if (k === "format")
                     return text(`${doc}.format`);
                 if (k.startsWith("$"))
                     return null;
                 if (RESERVED_DOC_BASENAMES.has(k))
                     return null;
-                if (NON_PROPERTY_NAMES.docs.has(k))
-                    return null; // `doc.nodes`, `doc.frontmatter`, … (decline (b))
+                if (NON_PROPERTY_NAMES.docs.has(k) || TARGETS.has(k))
+                    return null; // `doc.nodes`, `doc.frontmatter`, `doc.docs` … (decline (b))
                 return propScalar(doc, k);
             }
             // block.type / block.text reach-through from a node.
@@ -372,6 +383,9 @@ function translateComparison(e, ctx) {
     const r = translateOperand(e.right, ctx);
     if (!l || !r)
         return null;
+    const fast = pathEquality(e.op, l, r);
+    if (fast)
+        return fast;
     if (plainComparable(e.op, l.kind, r.kind)) {
         // `==`/`!=` → null-safe IS / IS NOT (absence-normalized equality, faithful in
         // any context). Relational ops → plain SQL: a NULL operand yields NULL, which
@@ -387,6 +401,23 @@ function translateComparison(e, ctx) {
     return side === "right" ? typedComparison(e.op, l, r) : typedComparison(FLIP[e.op] ?? e.op, r, l);
 }
 const FLIP = { "<": ">", "<=": ">=", ">": "<", ">=": "<=" };
+/**
+ * The path equality fast path: `$path == "/a.md"` (or `!=`, either side) against
+ * a rooted text constant is `d.path IS ?` with the constant's storage form, so
+ * the `(repo_id, path)` index serves it; `'/' || d.path IS ?` — what the general
+ * form would emit — is the same predicate without the index. Only a constant
+ * that IS rooted qualifies (run.ts roots every literal compared with a path
+ * read, so that is every literal); a bare binding stays on the general form,
+ * where `'/' || d.path` can never equal it — exactly the in-memory answer.
+ */
+function pathEquality(op, l, r) {
+    if (op !== "==" && op !== "!=")
+        return null;
+    const [col, konst] = l.pathCol ? [l, r] : r.pathCol ? [r, l] : [null, null];
+    if (!col || !konst || konst.kind !== "text" || typeof konst.value !== "string" || !konst.value.startsWith("/"))
+        return null;
+    return { sql: `(${col.pathCol} ${IS_OP[op]} ?)`, params: [storagePath(konst.value)] };
+}
 /**
  * The typed push (spec/surface §1, 1.2 patch): `read <op> constant` where the
  * read is a JSON or property read and the constant a bool or num literal/binding.

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

@@ -1,5 +1,5 @@
 // Store-backed equality indexes for the OQX engine (`DataContext.indexFor`):
-// when a nested block's receiver is a ROOT SCAN (`$repo.docs`, `$repo.edges`,
+// 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"` —
@@ -40,6 +40,7 @@
 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
@@ -104,8 +105,16 @@ class StoreIndex {
         const v = value === undefined ? null : value;
         if (v === null)
             return this.fallback(null);
-        if (this.probe.kind === "column")
-            return typeof v === "string" ? this.column(v) : [];
+        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);

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

@@ -1,5 +1,5 @@
 export declare const SPEC_VERSIONS: {
-    readonly oqx: "0.15";
+    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.8.0",
+  "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.15.0",
+    "@omgbase/oqx": "^0.18.0",
     "better-sqlite3": "^13.0.3",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-frontmatter": "^2.0.1",