@omgbase/core 0.4.1 → 0.6.0

package/dist/src/index.d.ts

@@ -1,4 +1,6 @@
 export { VERSION } from "./core/index.js";
+export { versionInfo, coreVersion, nearestPackageVersion, COMPONENT_PACKAGES, type VersionInfo, type HostInfo } from "./version.js";
+export { SPEC_VERSIONS, type SpecName } from "./spec-versions.js";
 export type { FormatAdapter, AdapterEdge, ProjectedNode, EmbeddingChunk, ReconcileHints } from "./format/adapter.js";
 export { AdapterCapability } from "./format/adapter.js";
 export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat } from "./format/registry.js";

package/dist/src/index.js

@@ -1,4 +1,6 @@
 export { VERSION } from "./core/index.js";
+export { versionInfo, coreVersion, nearestPackageVersion, COMPONENT_PACKAGES } from "./version.js";
+export { SPEC_VERSIONS } from "./spec-versions.js";
 export { AdapterCapability } from "./format/adapter.js";
 export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat } from "./format/registry.js";
 export { markdownAdapter, MARKDOWN_FORMAT } from "./format/markdown.js";

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

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { Store } from "../core/store/store.js";
+import { type HostInfo } from "../version.js";
 export interface ServerContext {
     store: Store;
     /** The DEFAULT repo for calls that omit `repo` (ADR-014). Tools accept an
@@ -26,5 +27,12 @@ export interface ServerContext {
      * embedding happens off it. Absent ⇒ mutations don't auto-drain.
      */
     onMutation?: () => void;
+    /**
+     * The serving binary's identity for the `version` tool (spec/surface §4): its
+     * own version, build info and the module its component packages resolve from.
+     * Set by `omg mcp`; absent for a library embedding (the tool then reports the
+     * engine's own version and whatever components resolve from core).
+     */
+    host?: HostInfo;
 }
 export declare function buildServer(ctx: ServerContext): McpServer;

package/dist/src/mcp/server.js

@@ -23,6 +23,7 @@ import { resolve as resolveThing } from "../search/resolve.js";
 import { reposStatus, syncStatus, reposList } from "../sync/admin.js";
 import { observeFile, observeMany, observeDelete } from "../sync/observe.js";
 import { QUERY_SYNTAX } from "./reference.js";
+import { versionInfo } from "../version.js";
 // Kernel-op schemas (04 §1) published as the `apply` tool's op grammar. Giving
 // each op a real schema (rather than z.any()) makes the required fields
 // discoverable in the tool's JSON schema and turns a malformed op — e.g. an
@@ -808,11 +809,11 @@ export function buildServer(ctx) {
         }
     });
     server.registerTool("docs_move", {
-        description: "Rename a document to a new repo-relative path; block identity and history are preserved. Fails path_taken if the destination exists. Links follow the PATH, not the identity: inbound links written against the old path now dangle (their edges become `phantom:<old path>`, so links_stale reports them), and links already written against the new path start resolving to this doc. The result lists those `dangling` inbound links ({doc, path, block, target, anchor, field?} per occurrence; block null = a frontmatter relation). Pass `retarget_inbound:true` to rewrite them in the same call — a destination-aware rewrite (anchors/link text/code spans preserved, absolute vs relative style kept) applied as one CAS-checked changeset, after which `dangling` holds only what could not be rewritten (frontmatter relations) and `retargeted` lists the touched blocks/docs. dry_run:true validates and returns the plan — `dangling`, `retargeted`, and the per-file `diffs` (the old path emptied, the new path filled, plus any rewritten sources) — without renaming or committing.",
+        description: "Rename a document to a new repo-relative path; block identity and history are preserved, and the inbound links FOLLOW it: every link written against the old path (Markdown links/images, wikilinks, bare-path inline fields — anchors, link text, titles and code spans preserved, absolute vs relative style kept) is rewritten to the new path in the same call as one CAS-checked changeset, so a move never leaves the graph broken. Fails path_taken if the destination exists. The result carries `retargeted` (the touched blocks/docs) and `dangling` — what could NOT be rewritten, i.e. frontmatter relations (block null; fix with docs_set_meta). Pass `retarget_inbound:false` to opt out for the rarer intent that the old path become unbound: the links are left as written, listed in `dangling` ({doc, path, block, target, anchor, field?} per occurrence) and reported by links_stale (their edges become `phantom:<old path>`); links already written against the new path start resolving to this doc either way. dry_run:true validates and returns the plan — `dangling`, `retargeted`, and the per-file `diffs` (the old path emptied, the new path filled, plus the rewritten sources) — without renaming or committing.",
         inputSchema: { doc: z.string(), to_path: z.string(), retarget_inbound: z.boolean().optional(), dry_run: z.boolean().optional(), ...REPO_ARG },
     }, async (args) => {
         try {
-            return docResult(docsMove(store, docCtx(repoScope(args.repo), args.dry_run), args.doc, args.to_path, { retargetInbound: args.retarget_inbound === true }), args.dry_run);
+            return docResult(docsMove(store, docCtx(repoScope(args.repo), args.dry_run), args.doc, args.to_path, { retargetInbound: args.retarget_inbound !== false }), args.dry_run);
         }
         catch (e) {
             return fail(e);
@@ -1069,6 +1070,20 @@ export function buildServer(ctx) {
             return fail(e);
         }
     });
+    // Which engine and which versions (spec/surface §4, 1.4). No repo scope: the
+    // answer is about the binary and its database, not a repo.
+    server.registerTool("version", {
+        description: "Which engine and which versions you are talking to: `{ engine: \"typescript\"|\"rust\", version, components: { <package>: <version> }, specs: { oqx, format, reconcile, store, properties, graph, search, mutate, sync, surface, cli }, schema, mcp: { protocol, sdk? }, runtime, commit, built }`. " +
+            "`version` is the serving binary's own; `components` every omgbase package it is built from; `specs` the spec versions it implements (compile-time constants); `schema` the database's `PRAGMA user_version`; `commit`/`built` the build's git revision and RFC 3339 time (null when unknown). No arguments, no repo scope.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            return ok(versionInfo(store, ctx.host));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
     return server;
 }
 //# sourceMappingURL=server.js.map

package/dist/src/mutate/docs.d.ts

@@ -40,22 +40,30 @@ export interface DocOpResult {
 }
 export interface DocMoveOptions {
     /**
-     * Also rewrite the inbound links that named the OLD path so they point at the
-     * new one — a destination-aware rewrite (anchors, link text, titles, and code
+     * Rewrite the inbound links that named the OLD path so they point at the new
+     * one — a destination-aware rewrite (anchors, link text, titles, and code
      * spans preserved; absolute/relative style kept) applied as a CAS-checked
-     * `update` per source block in one follow-up api changeset. Frontmatter-level
-     * relations are not rewritten (reported in `dangling`).
+     * `update` per source block in one follow-up api changeset. **Default `true`**
+     * (spec/mutate 1.3): a move means "same document, new place", so the authored
+     * links follow it; pass `false` for the rarer intent that the old path become
+     * unbound. Frontmatter-level relations are never rewritten (reported in
+     * `dangling`).
      */
     retargetInbound?: boolean;
 }
 export interface DocMoveResult extends DocOpResult {
     /**
      * Inbound links still pointing at the OLD path after this call — the source
-     * blocks `links_stale` will now report (empty when `retargetInbound` rewrote
-     * them all). Computed from the open edge index before the move.
+     * blocks `links_stale` will now report (with the default retarget: only the
+     * frontmatter relations, which are never rewritten). Computed from the open
+     * edge index before the move.
      */
     dangling: InboundLink[];
-    /** With `retargetInbound`: the source blocks rewritten and the docs re-ingested. */
+    /**
+     * The source blocks rewritten and the docs re-ingested (empty lists when the
+     * rewrite ran but only frontmatter relations linked in); `null` when the
+     * retarget was opted out (`retargetInbound: false`) or nothing linked in.
+     */
     retargeted: {
         blocks: string[];
         docs: string[];
@@ -68,8 +76,10 @@ export declare function docsCreate(store: Store, ctx: DocOpContext, path: string
  * index follows the path, not the identity: links written against the OLD path
  * now dangle (their open edges are re-pointed at `phantom:<old>`, exactly what
  * re-extracting the source would produce, so `links_stale` sees them), and
- * phantom edges already written against the NEW path are adopted. The result
- * lists the dangling inbound links; `retargetInbound` rewrites them.
+ * phantom edges already written against the NEW path are adopted. By default
+ * the dangling inbound links are then rewritten to the new path in one
+ * follow-up changeset (spec/mutate 1.3); `retargetInbound: false` leaves them
+ * as written and the result lists them.
  */
 export declare function docsMove(store: Store, ctx: DocOpContext, docRef: string, toPath: string, opts?: DocMoveOptions): DocMoveResult;
 /** docs_delete: mark a document deleted and remove its file (resurrection-poolable). */

package/dist/src/mutate/docs.js

@@ -60,10 +60,13 @@ export function docsCreate(store, ctx, path, markdown, frontmatter) {
  * index follows the path, not the identity: links written against the OLD path
  * now dangle (their open edges are re-pointed at `phantom:<old>`, exactly what
  * re-extracting the source would produce, so `links_stale` sees them), and
- * phantom edges already written against the NEW path are adopted. The result
- * lists the dangling inbound links; `retargetInbound` rewrites them.
+ * phantom edges already written against the NEW path are adopted. By default
+ * the dangling inbound links are then rewritten to the new path in one
+ * follow-up changeset (spec/mutate 1.3); `retargetInbound: false` leaves them
+ * as written and the result lists them.
  */
 export function docsMove(store, ctx, docRef, toPath, opts = {}) {
+    const retargetInbound = opts.retargetInbound !== false;
     const info = findDocByRef(store, ctx.repoId, docRef);
     if (!info)
         throw new MutationError("doc_missing", `no document ${docRef}`);
@@ -79,7 +82,7 @@ export function docsMove(store, ctx, docRef, toPath, opts = {}) {
         const content = docStore.read(info.path) ?? "";
         const diffs = { [info.path]: { before: content, after: "" }, [toRel]: { before: "", after: content } };
         const planned = { docId: info.docId, path: toRel, committed: false, diffs };
-        if (!opts.retargetInbound || inbound.length === 0)
+        if (!retargetInbound || inbound.length === 0)
             return { ...planned, dangling: inbound, retargeted: null };
         const plan = planInboundRetarget(store, info.docId, info.path, toRel, inbound);
         if (plan.ops.length > 0) {
@@ -134,7 +137,7 @@ export function docsMove(store, ctx, docRef, toPath, opts = {}) {
         }
         return { docId: info.docId, path: toRel, committed: true };
     });
-    if (!opts.retargetInbound || inbound.length === 0)
+    if (!retargetInbound || inbound.length === 0)
         return { ...moved, dangling: inbound, retargeted: null };
     // Rewrite the dangling links block by block (one coalesced update per block,
     // CAS on the block's current hash) and apply as one changeset; the re-ingest

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

@@ -0,0 +1,14 @@
+export declare const SPEC_VERSIONS: {
+    readonly oqx: "0.13";
+    readonly format: "0.2";
+    readonly reconcile: "2.3";
+    readonly store: "13.5";
+    readonly properties: "1.1";
+    readonly graph: "1.1";
+    readonly search: "1.2";
+    readonly mutate: "1.3";
+    readonly sync: "1.3";
+    readonly surface: "1.4";
+    readonly cli: "1.2";
+};
+export type SpecName = keyof typeof SPEC_VERSIONS;

package/dist/src/spec-versions.js

@@ -0,0 +1,25 @@
+import { LANGUAGE_VERSION } from "@omgbase/oqx";
+// The spec versions this reference implements (spec/surface §4, the `version`
+// tool's `specs`): one compile-time constant per `spec/<x>/VERSION`, NOT a file
+// read — a published package has no `spec/` next to it. Hand-maintained; the
+// test beside this module (`spec-versions.test.ts`) asserts every entry equals
+// the corresponding `spec/<x>/VERSION` file and that no spec is missing, so a
+// spec bump that forgets this map fails the build. `oqx` is the one entry with
+// a constant of its own: `@omgbase/oqx`'s `LANGUAGE_VERSION`.
+//
+// Key order is the order spec/surface §4 lists them (the CLI prints `specs` in
+// this order).
+export const SPEC_VERSIONS = {
+    oqx: LANGUAGE_VERSION,
+    format: "0.2",
+    reconcile: "2.3",
+    store: "13.5",
+    properties: "1.1",
+    graph: "1.1",
+    search: "1.2",
+    mutate: "1.3",
+    sync: "1.3",
+    surface: "1.4",
+    cli: "1.2",
+};
+//# sourceMappingURL=spec-versions.js.map

package/dist/src/version.d.ts

@@ -0,0 +1,39 @@
+import type { Store } from "./core/store/store.js";
+import { SPEC_VERSIONS } from "./spec-versions.js";
+export interface HostInfo {
+    /** the serving binary's own version — `omgbase`'s package.json (what `--version` prints) */
+    version: string;
+    /** the build's short git revision, from `build-info.json`; null when unknown */
+    commit: string | null;
+    /** the build's RFC 3339 time, from `build-info.json`; null when unknown */
+    built: string | null;
+    /** the host module's `import.meta.url`: the component packages are resolved from its dependency graph */
+    resolveFrom?: string;
+}
+export interface VersionInfo {
+    engine: "typescript";
+    version: string;
+    /** every omgbase package the binary is built from, keys sorted bytewise */
+    components: Record<string, string>;
+    specs: typeof SPEC_VERSIONS;
+    /** `PRAGMA user_version` of the open store; null without one */
+    schema: number | null;
+    mcp: {
+        protocol: string;
+        sdk: string;
+    };
+    runtime: string;
+    commit: string | null;
+    built: string | null;
+}
+/** The omgbase packages the reference binary is built from (spec/surface §4). */
+export declare const COMPONENT_PACKAGES: readonly ["omgbase", "@omgbase/core", "@omgbase/oqx", "@omgbase/sync", "@omgbase/fs-adapter"];
+/** The nearest `package.json` named `name` at or above `fromUrl`'s directory, or null. */
+export declare function nearestPackageVersion(fromUrl: string, name: string): string | null;
+/** The engine's own package version (`@omgbase/core`), from the manifest above this module. */
+export declare function coreVersion(): string;
+/**
+ * The `version` result. `store` supplies `schema`; `host` the binary's own
+ * version, build info and resolution anchor (see the module comment).
+ */
+export declare function versionInfo(store?: Store | null, host?: HostInfo): VersionInfo;

package/dist/src/version.js

@@ -0,0 +1,103 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
+import { SPEC_VERSIONS } from "./spec-versions.js";
+/** The omgbase packages the reference binary is built from (spec/surface §4). */
+export const COMPONENT_PACKAGES = ["omgbase", "@omgbase/core", "@omgbase/oqx", "@omgbase/sync", "@omgbase/fs-adapter"];
+const MCP_SDK = "@modelcontextprotocol/sdk";
+/** The nearest `package.json` named `name` at or above `fromUrl`'s directory, or null. */
+export function nearestPackageVersion(fromUrl, name) {
+    let dir = dirname(fileURLToPath(fromUrl));
+    for (;;) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate)) {
+            const pkg = readManifest(candidate);
+            if (pkg?.name === name && typeof pkg.version === "string")
+                return pkg.version;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function readManifest(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `name`'s installed version as seen from `anchors` (module URLs). Node's own
+ * resolver is no use here: the omgbase packages are ESM-only (`exports` with an
+ * `import` condition alone), which a CJS `require.resolve` cannot see, and no
+ * package exports its `package.json`. So this walks what the algorithm would
+ * absent `exports`: the anchor's own package first (a package cannot name
+ * itself), then `node_modules/<name>/package.json` at each ancestor directory —
+ * pnpm's symlinked layout, npm's hoisted global install and a plain checkout all
+ * put the manifest there. Anchors are tried in turn; null when none has it.
+ */
+function resolvePackageVersion(name, anchors) {
+    for (const anchor of anchors) {
+        const own = nearestPackageVersion(anchor, name);
+        if (own !== null)
+            return own;
+        let dir = dirname(fileURLToPath(anchor));
+        for (;;) {
+            const pkg = readManifest(join(dir, "node_modules", name, "package.json"));
+            if (pkg?.name === name && typeof pkg.version === "string")
+                return pkg.version;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+/** The MCP SDK's version: from the module core itself imports, walking up to its manifest (its `package.json` is not exported). */
+function mcpSdkVersion() {
+    try {
+        return nearestPackageVersion(import.meta.resolve(`${MCP_SDK}/types.js`), MCP_SDK);
+    }
+    catch {
+        return null;
+    }
+}
+/** The engine's own package version (`@omgbase/core`), from the manifest above this module. */
+export function coreVersion() {
+    return nearestPackageVersion(import.meta.url, "@omgbase/core") ?? "0.0.0";
+}
+/**
+ * The `version` result. `store` supplies `schema`; `host` the binary's own
+ * version, build info and resolution anchor (see the module comment).
+ */
+export function versionInfo(store, host) {
+    const anchors = [...(host?.resolveFrom ? [host.resolveFrom] : []), import.meta.url];
+    const components = {};
+    for (const name of COMPONENT_PACKAGES) {
+        // The host IS `omgbase`: its version is what it says it is (the resolver
+        // would find the same manifest above `resolveFrom`, but the host is explicit).
+        const v = name === "omgbase" && host ? host.version : resolvePackageVersion(name, anchors);
+        if (v !== null)
+            components[name] = v;
+    }
+    const sorted = Object.fromEntries(Object.entries(components).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    const version = host?.version ?? components["omgbase"] ?? coreVersion();
+    const schema = store ? store.db.pragma("user_version", { simple: true }) : null;
+    return {
+        engine: "typescript",
+        version,
+        components: sorted,
+        specs: SPEC_VERSIONS,
+        schema,
+        mcp: { protocol: LATEST_PROTOCOL_VERSION, sdk: mcpSdkVersion() ?? "unknown" },
+        runtime: `node ${process.versions.node}`,
+        commit: host?.commit ?? null,
+        built: host?.built ?? null,
+    };
+}
+//# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/core",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Open Markdown Graph Base — embedded engine",
   "license": "MIT",
   "repository": {