@omgbase/core 0.28.0 → 0.29.2

package/dist/src/search/external.d.ts

@@ -11,6 +11,16 @@ export interface ExternalProvider {
  * failure. Callers must call close() when done.
  */
 export declare function createExternalProvider(settings: EmbeddingSettings): Promise<ExternalProvider | null>;
+/**
+ * The hint appended to a spawn failure when the command names a JavaScript file
+ * (`.js`/`.mjs`/`.cjs`) and the OS refused it with EACCES or ENOENT: a built
+ * `bin.js` carries a `#!/usr/bin/env node` shebang but not always the executable
+ * bit, and the engine spawns the provider directly, so the fix is to run it through
+ * node. Empty for any other command or error. The Rust twin
+ * (`crates/omgbase-search/src/external.rs`, `spawn_hint`) emits the same text
+ * byte for byte; the tests of both pin it.
+ */
+export declare function spawnHint(provider: string, code: string | undefined): string;
 /**
  * The environment a stdio embedder is spawned with: our own env, with the
  * repo's explicit `embedding.model` / `dim` / `maxInputTokens` settings laid over

package/dist/src/search/external.js

@@ -70,7 +70,7 @@ async function connectStdio(settings) {
         child = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"], env: embedderEnv(settings) });
     }
     catch (err) {
-        throw new Error(`embedding command '${settings.provider}' failed to spawn: ${err.message}`);
+        throw new Error(`embedding command '${settings.provider}' failed to spawn: ${err.message}${spawnHint(settings.provider, err.code)}`);
     }
     child.stderr.pipe(process.stderr);
     // Don't let a still-running embedder keep our own event loop alive on exit.
@@ -78,7 +78,7 @@ async function connectStdio(settings) {
     const rl = createInterface({ input: child.stdout });
     const lines = lineQueue(rl);
     const spawnFailed = new Promise((_, reject) => {
-        child.once("error", (err) => reject(new Error(`embedding command '${cmd}' failed to spawn: ${err.message}`)));
+        child.once("error", (err) => reject(new Error(`embedding command '${cmd}' failed to spawn: ${err.message}${spawnHint(settings.provider, err.code)}`)));
         child.once("exit", (code) => reject(new Error(`embedding command '${cmd}' exited early (code ${code ?? "?"})`)));
     });
     // The race consumers below observe this rejection; guard the reference itself
@@ -153,6 +153,24 @@ async function connectStdio(settings) {
     };
     return { provider, close };
 }
+/**
+ * The hint appended to a spawn failure when the command names a JavaScript file
+ * (`.js`/`.mjs`/`.cjs`) and the OS refused it with EACCES or ENOENT: a built
+ * `bin.js` carries a `#!/usr/bin/env node` shebang but not always the executable
+ * bit, and the engine spawns the provider directly, so the fix is to run it through
+ * node. Empty for any other command or error. The Rust twin
+ * (`crates/omgbase-search/src/external.rs`, `spawn_hint`) emits the same text
+ * byte for byte; the tests of both pin it.
+ */
+export function spawnHint(provider, code) {
+    const spec = provider.trim();
+    const cmd = spec.split(/\s+/)[0] ?? "";
+    if (!/\.[cm]?js$/i.test(cmd))
+        return "";
+    if (code !== "EACCES" && code !== "ENOENT")
+        return "";
+    return ` Hint: the command names a JavaScript file; run it through node — set embedding.provider to \`node ${spec}\` — or give the file the executable bit`;
+}
 /**
  * The environment a stdio embedder is spawned with: our own env, with the
  * repo's explicit `embedding.model` / `dim` / `maxInputTokens` settings laid over

package/dist/src/search/resolve.d.ts

@@ -1,8 +1,8 @@
 import type { Store } from "../core/store/store.js";
-/** A resolve hit (spec/search §4): the block's `id` (spec/surface §1.2, 3.0),
+/** A resolve hit (spec/search §4): the block's `_id` (spec/surface §1.2, 5.0),
  *  its `locator`, a `preview` and the fusion `evidence`. */
 export interface ResolveHit {
-    id: string;
+    _id: string;
     locator: string;
     preview: string;
     evidence: unknown;

package/dist/src/search/resolve.js

@@ -18,6 +18,6 @@ export function resolve(store, input) {
     if (input.vector)
         hi.vector = input.vector;
     const hits = hybridSearch(store, hi);
-    return hits.map((h) => ({ id: h.blockId, locator: locatorFor(store, h.blockId), preview: previewFor(store, h.blockId), evidence: h.evidence }));
+    return hits.map((h) => ({ _id: h.blockId, locator: locatorFor(store, h.blockId), preview: previewFor(store, h.blockId), evidence: h.evidence }));
 }
 //# sourceMappingURL=resolve.js.map

package/dist/src/search/rrf.js

@@ -43,8 +43,8 @@ export function hybridSearch(store, input) {
     const ftsRanks = new Map();
     if (input.text) {
         textSearch(store, input.repoId, input.text, { limit: 200 }).hits.forEach((h, i) => {
-            if (!ftsRanks.has(h.id))
-                ftsRanks.set(h.id, i + 1);
+            if (!ftsRanks.has(h._id))
+                ftsRanks.set(h._id, i + 1);
         });
     }
     const vecRanks = new Map();

package/dist/src/search/text.d.ts

@@ -1,10 +1,10 @@
 import type { Store } from "../core/store/store.js";
 export interface TextHit {
-    id: string;
-    doc_id: string;
-    path: string;
-    type: string;
-    text: string;
+    _id: string;
+    _doc_id: string;
+    _path: string;
+    _type: string;
+    _text: string;
     score: number;
 }
 export interface TextSearchResult {

package/dist/src/search/text.js

@@ -5,8 +5,8 @@ export function textSearch(store, repoId, queryStr, opts = {}) {
     if (match === "")
         return { hits: [], truncated: false };
     const rows = store.db
-        .prepare(`SELECT b.block_id AS "id", b.doc_id AS doc_id, d.path AS "path", b.type AS type,
-              b.text AS text, bm25(blocks_fts) AS score
+        .prepare(`SELECT b.block_id AS "_id", b.doc_id AS _doc_id, d.path AS "_path", b.type AS _type,
+              b.text AS _text, bm25(blocks_fts) AS score
        FROM blocks_fts
        JOIN blocks b ON b.rowid = blocks_fts.rowid
        JOIN docs d ON d.doc_id = b.doc_id

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

@@ -1,14 +1,14 @@
 export declare const SPEC_VERSIONS: {
-    readonly oqx: "0.25";
+    readonly oqx: "0.26";
     readonly format: "0.2";
     readonly reconcile: "2.3";
     readonly store: "16.0";
     readonly properties: "1.2";
-    readonly graph: "1.1";
-    readonly search: "2.0";
-    readonly mutate: "3.6";
-    readonly sync: "2.2";
-    readonly surface: "4.11";
-    readonly cli: "4.6";
+    readonly graph: "2.0";
+    readonly search: "3.0";
+    readonly mutate: "4.0";
+    readonly sync: "3.0";
+    readonly surface: "5.1";
+    readonly cli: "5.0";
 };
 export type SpecName = keyof typeof SPEC_VERSIONS;

package/dist/src/spec-versions.js

@@ -15,11 +15,11 @@ export const SPEC_VERSIONS = {
     reconcile: "2.3",
     store: "16.0",
     properties: "1.2",
-    graph: "1.1",
-    search: "2.0",
-    mutate: "3.6",
-    sync: "2.2",
-    surface: "4.11",
-    cli: "4.6",
+    graph: "2.0",
+    search: "3.0",
+    mutate: "4.0",
+    sync: "3.0",
+    surface: "5.1",
+    cli: "5.0",
 };
 //# sourceMappingURL=spec-versions.js.map

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

@@ -6,40 +6,41 @@ 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 kernel result (the library's `apply`; no tool returns it since 4.0): `revisions[].path` and the dry-run `diffs` keys. */
+/** `spec/mutate` §4's kernel result (the library's `apply`; no tool returns it since 4.0): `revisions[]._path` and the dry-run `diffs` keys. */
 export declare function surfaceApplyResult<T extends ApplyResult>(res: T): T;
 /** An inbound link on the wire (`docs_move.dangling[]`, `omg mv`): a link row
- *  under the `links` target's names (spec/surface §1.2) — `doc_id`, `path`
- *  (rooted), `block_id`, `target` (as authored), `anchor`, `field?`. */
+ *  under the `links` target's names (spec/surface §1.2, 5.0) — `_doc_id`,
+ *  `_path` (rooted), `_block_id`, `target` (as authored; a role), `_anchor`,
+ *  `_field?`. */
 export interface SurfaceInboundLink {
-    doc_id: string;
-    path: string;
-    block_id: string | null;
+    _doc_id: string;
+    _path: string;
+    _block_id: string | null;
     target: string;
-    anchor: string | null;
-    field?: string;
+    _anchor: string | null;
+    _field?: string;
 }
 export declare function surfaceInboundLink(l: InboundLink): SurfaceInboundLink;
-/** An observe outcome on the wire (spec/surface §4, 3.0): `spec/store` §5's
+/** An observe outcome on the wire (spec/surface §4, 5.0): `spec/store` §5's
  *  `{ docId, path, … }` (unchanged there) renamed to the document's row
- *  attributes `id`/`path`, the path rooted. */
+ *  attributes `_id`/`_path`, the path rooted. */
 export type SurfaceObserveResult<T extends {
     docId: string | null;
     path: string;
 }> = Omit<T, "docId" | "path"> & {
-    id: T["docId"];
-    path: string;
+    _id: T["docId"];
+    _path: string;
 };
 /** `observe` / `observe_many` outcomes. */
 export declare function surfaceObserveResult<T extends ObserveResult>(res: T): SurfaceObserveResult<T>;
 /** `observe_delete`. */
 export declare function surfaceObserveDeleteResult(res: ObserveDeleteResult): SurfaceObserveResult<ObserveDeleteResult>;
-/** `blocks_search` hits (`path` rooted). */
+/** `blocks_search` hits (`_path` rooted). */
 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). */
+/** `links_retarget` / `links_repair` hits (`_path` is the block's document). */
 export declare function surfaceRetargetHits(hits: RetargetHit[]): RetargetHit[];
 /**
  * A Plan on the wire (spec/surface §4, 3.1): the executable core — `effects`,
@@ -47,11 +48,11 @@ export declare function surfaceRetargetHits(hits: RetargetHit[]): RetargetHit[];
  * storage form, because `plan_id` digests exactly those bytes and the client
  * hands the object back to `execute` (spec/mutate §11.5; the one result the
  * path rule exempts, like `dangling[].target`). Only the un-digested `preview`
- * is rooted: its `revisions[].path`, `diffs` keys and `retarget[].hits[].path`
- * (3.0; `identity` is keyed by document id and carries no path).
+ * is rooted: its `revisions[]._path`, `diffs` keys and `retarget[].hits[]._path`
+ * (`identity` is keyed by document id and carries no path).
  */
 export declare function surfacePlan(plan: Plan): Plan;
-/** A Receipt on the wire: `revisions[].path` rooted (the same shape as an apply revision). */
+/** A Receipt on the wire: `revisions[]._path` rooted (the same shape as an apply revision). */
 export declare function surfaceReceipt(receipt: Receipt): Receipt;
 /** `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

@@ -8,41 +8,43 @@
 // `spec/sync`'s sweep — keep their storage-form paths in the library (their
 // own fixtures pin them) and are re-shaped HERE.
 //
-// Row names (spec/surface §1.2, 3.0): a result that renders a document, block
-// or edge row spells it the way the query binding does — `id`, `path`,
-// `hash`, `raw`, `updated_at`, plain `doc_id`/`block_id` foreign keys. The
-// shapes other specs own under their own names — `spec/store`'s observe
-// outcome, a move's dangling inbound links — are re-shaped HERE too
-// (`SurfaceObserveResult`, `surfaceInboundLink`, …).
+// Row names (spec/surface §1.2, 5.0 "underscore = engine"): a result that
+// renders a document, block or link row spells it the way the query binding
+// does — `_id`, `_path`, `_hash`, `_raw`, `_updated_at`, the foreign keys
+// `_doc_id`/`_block_id`; a key naming a ROLE (`rev`, `target`, `locator`,
+// `commitId`, `oldRaw`/`newRaw`) keeps its name. The shapes other specs own
+// under their own names — `spec/store`'s observe outcome, a move's dangling
+// inbound links — are re-shaped HERE too (`SurfaceObserveResult`,
+// `surfaceInboundLink`, …).
 //
 // Both the MCP server and the `omg` verbs call these, 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 kernel result (the library's `apply`; no tool returns it since 4.0): `revisions[].path` and the dry-run `diffs` keys. */
+/** `spec/mutate` §4's kernel result (the library's `apply`; no tool returns it since 4.0): `revisions[]._path` and the dry-run `diffs` keys. */
 export function surfaceApplyResult(res) {
     return {
         ...res,
-        revisions: res.revisions.map((r) => ({ ...r, path: referencePath(r.path) })),
+        revisions: res.revisions.map((r) => ({ ...r, _path: referencePath(r._path) })),
         ...(res.diffs ? { diffs: referenceKeyed(res.diffs) } : {}),
     };
 }
 export function surfaceInboundLink(l) {
-    const { path, ...rest } = l;
-    return { doc_id: rest.doc_id, path: referencePath(path), block_id: rest.block_id, target: rest.target, anchor: rest.anchor, ...(rest.field !== undefined ? { field: rest.field } : {}) };
+    const { _path, ...rest } = l;
+    return { _doc_id: rest._doc_id, _path: referencePath(_path), _block_id: rest._block_id, target: rest.target, _anchor: rest._anchor, ...(rest._field !== undefined ? { _field: rest._field } : {}) };
 }
 /** `observe` / `observe_many` outcomes. */
 export function surfaceObserveResult(res) {
     const { docId, path, ...rest } = res;
-    return { id: docId, path: referencePath(path), ...rest };
+    return { _id: docId, _path: referencePath(path), ...rest };
 }
 /** `observe_delete`. */
 export function surfaceObserveDeleteResult(res) {
     const { docId, path, ...rest } = res;
-    return { id: docId, path: referencePath(path), ...rest };
+    return { _id: docId, _path: referencePath(path), ...rest };
 }
-/** `blocks_search` hits (`path` rooted). */
+/** `blocks_search` hits (`_path` rooted). */
 export function surfaceTextSearch(res) {
-    return { ...res, hits: res.hits.map((h) => ({ ...h, path: referencePath(h.path) })) };
+    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). */
@@ -52,9 +54,9 @@ export function surfaceResolveHits(hits) {
         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). */
+/** `links_retarget` / `links_repair` hits (`_path` is the block's document). */
 export function surfaceRetargetHits(hits) {
-    return hits.map((h) => ({ ...h, path: referencePath(h.path) }));
+    return hits.map((h) => ({ ...h, _path: referencePath(h._path) }));
 }
 /**
  * A Plan on the wire (spec/surface §4, 3.1): the executable core — `effects`,
@@ -62,8 +64,8 @@ export function surfaceRetargetHits(hits) {
  * storage form, because `plan_id` digests exactly those bytes and the client
  * hands the object back to `execute` (spec/mutate §11.5; the one result the
  * path rule exempts, like `dangling[].target`). Only the un-digested `preview`
- * is rooted: its `revisions[].path`, `diffs` keys and `retarget[].hits[].path`
- * (3.0; `identity` is keyed by document id and carries no path).
+ * is rooted: its `revisions[]._path`, `diffs` keys and `retarget[].hits[]._path`
+ * (`identity` is keyed by document id and carries no path).
  */
 export function surfacePlan(plan) {
     if (!plan.preview)
@@ -72,15 +74,15 @@ export function surfacePlan(plan) {
         ...plan,
         preview: {
             ...plan.preview,
-            revisions: plan.preview.revisions.map((r) => ({ ...r, path: referencePath(r.path) })),
+            revisions: plan.preview.revisions.map((r) => ({ ...r, _path: referencePath(r._path) })),
             diffs: referenceKeyed(plan.preview.diffs),
             ...(plan.preview.retarget !== undefined ? { retarget: plan.preview.retarget.map((r) => ({ ...r, hits: surfaceRetargetHits(r.hits) })) } : {}),
         },
     };
 }
-/** A Receipt on the wire: `revisions[].path` rooted (the same shape as an apply revision). */
+/** A Receipt on the wire: `revisions[]._path` rooted (the same shape as an apply revision). */
 export function surfaceReceipt(receipt) {
-    return { ...receipt, revisions: receipt.revisions.map((r) => ({ ...r, path: referencePath(r.path) })) };
+    return { ...receipt, revisions: receipt.revisions.map((r) => ({ ...r, _path: referencePath(r._path) })) };
 }
 /** `omg sync`'s one-shot sweep: the ingested / suppressed / deleted / conflicted paths. */
 export function surfaceSweepResult(res) {

package/dist/src/sync/admin.d.ts

@@ -10,8 +10,8 @@ export interface DiskStatus extends DiskDrift {
     checked: boolean;
 }
 export interface RepoStatus {
-    /** the repository's own id (spec/surface §1.2, 3.0: every row names its identity `id`) */
-    id: string;
+    /** the repository's own id (spec/surface §1.2, 5.0: the root row's `_id`) */
+    _id: string;
     slug: string;
     rootPath: string;
     docs: number;

package/dist/src/sync/admin.js

@@ -18,7 +18,7 @@ export function reposStatus(store, repoId, rootPath) {
         ? { ...detectDiskDrift(store, repoId, rootPath), checked: true }
         : { changed: 0, deleted: 0, untracked: 0, checked: false };
     return {
-        id: repoId,
+        _id: repoId,
         slug: repo?.slug ?? "",
         rootPath: rootPath ?? "",
         docs: count("SELECT count(*) c FROM docs WHERE repo_id = ? AND deleted_commit IS NULL"),

package/package.json

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