@omgbase/core 0.5.0 → 0.6.1

package/dist/src/graph/history.d.ts

@@ -25,8 +25,16 @@ export interface DiffEntry {
     after?: string;
 }
 export declare function diffBlocks(store: Store, docId: string, fromRev: string, toRev: string): DiffEntry[];
-/** `diff_unified` (spec/surface §3): a unified diff of two revisions' rendered
- * texts — each revision's live raws joined by `\n` — via {@link unifiedDiff}. */
+/**
+ * `diff_unified` (spec/surface §3): a unified diff of the two revisions'
+ * **reconstructed file text** — exactly the bytes `docs_read_at` returns for
+ * each revision ({@link readDocumentAtRevision}: frontmatter, trivia and
+ * top-level order included) — via {@link unifiedDiff}, so hunk line numbers
+ * are real file lines. Until 1.4.x this diffed the Merkle-tree walk (every
+ * live raw at every depth joined by `\n`), which repeated each nested block
+ * after its container's raw and put an appended list item before the list's
+ * first item (§9). An unknown revision is {@link RevisionNotFound}.
+ */
 export declare function diffUnified(store: Store, docId: string, fromRev: string, toRev: string): string;
 /** The `diff_unified` tool's result (spec/surface §3): the resolved revision pair and the diff. */
 export interface DocDiffUnified {

package/dist/src/graph/history.js

@@ -1,4 +1,5 @@
 import { findDocByRef } from "../core/read/reader.js";
+import { readDocumentAtRevision } from "../core/read/document.js";
 import { isValidId } from "../core/ids.js";
 import { EngineError } from "../mcp/errors.js";
 /** history_node: a block's biography from block_changes + commits (06 §3). */
@@ -50,7 +51,9 @@ export function diffBlocks(store, docId, fromRev, toRev) {
 // core/hash.ts serializeTreeEntries): [blockId, rawHashHex, childTreeHashHex,
 // type, attrs, triviaHashHex]. Diff needs only the first three; whole-document
 // byte-faithful reconstruction (which also needs trivia + top-level order) lives
-// in core/read/document.ts readDocumentAtRevision.
+// in core/read/document.ts readDocumentAtRevision. This map is NOT a rendering
+// of the document: a container's raw already holds its children's text, so
+// joining the values would repeat every nested block (spec/surface §9).
 function blocksAtRevision(store, docId, revId) {
     const rev = store.db.prepare("SELECT root_tree FROM revisions WHERE rev_id = ? AND doc_id = ?").get(revId, docId);
     if (!rev)
@@ -73,10 +76,23 @@ function blocksAtRevision(store, docId, revId) {
     walk(rev.root_tree.toString("hex"));
     return out;
 }
-/** `diff_unified` (spec/surface §3): a unified diff of two revisions' rendered
- * texts — each revision's live raws joined by `\n` — via {@link unifiedDiff}. */
+/**
+ * `diff_unified` (spec/surface §3): a unified diff of the two revisions'
+ * **reconstructed file text** — exactly the bytes `docs_read_at` returns for
+ * each revision ({@link readDocumentAtRevision}: frontmatter, trivia and
+ * top-level order included) — via {@link unifiedDiff}, so hunk line numbers
+ * are real file lines. Until 1.4.x this diffed the Merkle-tree walk (every
+ * live raw at every depth joined by `\n`), which repeated each nested block
+ * after its container's raw and put an appended list item before the list's
+ * first item (§9). An unknown revision is {@link RevisionNotFound}.
+ */
 export function diffUnified(store, docId, fromRev, toRev) {
-    const rendered = (rev) => [...blocksAtRevision(store, docId, rev).values()].join("\n");
+    const rendered = (rev) => {
+        const at = readDocumentAtRevision(store, docId, rev);
+        if (!at)
+            throw new RevisionNotFound(docId, rev);
+        return at.content;
+    };
     return unifiedDiff(rendered(fromRev), rendered(toRev));
 }
 /**

package/dist/src/mcp/server.js

@@ -809,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);
@@ -940,7 +940,7 @@ export function buildServer(ctx) {
         }
     });
     server.registerTool("diff_unified", {
-        description: "Unified diff between two revisions of a document (the `omg diff` rendering): returns `{ doc, path, from, to, diff }` where `diff` is a unified diff of the two rendered texts (Myers shortest edit script; `@@ -a,b +c,d @@` hunks with 3 lines of context; lines prefixed `-`, `+` or a space; no file header; identical texts → \"\"). `from_rev`/`to_rev` default to the previous and current revisions ('what did the last commit change here'). Contrast `diff`, which returns block-grain added/removed/changed entries.",
+        description: "Unified diff between two revisions of a document (the `omg diff` rendering): returns `{ doc, path, from, to, diff }` where `diff` is a unified diff of the two revisions' file texts — for each revision exactly the bytes docs_read_at returns, so hunk line numbers are real file lines (Myers shortest edit script; `@@ -a,b +c,d @@` hunks with 3 lines of context; lines prefixed `-`, `+` or a space; no file header; identical texts → \"\"). `from_rev`/`to_rev` default to the previous and current revisions ('what did the last commit change here'). Contrast `diff`, which returns block-grain added/removed/changed entries.",
         inputSchema: { doc: z.string(), from_rev: z.string().optional(), to_rev: z.string().optional(), ...REPO_ARG },
     }, async (args) => {
         try {

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

@@ -6,9 +6,9 @@ export declare const SPEC_VERSIONS: {
     readonly properties: "1.1";
     readonly graph: "1.1";
     readonly search: "1.2";
-    readonly mutate: "1.2";
+    readonly mutate: "1.3";
     readonly sync: "1.3";
     readonly surface: "1.4";
-    readonly cli: "1.1";
+    readonly cli: "1.2";
 };
 export type SpecName = keyof typeof SPEC_VERSIONS;

package/dist/src/spec-versions.js

@@ -17,9 +17,9 @@ export const SPEC_VERSIONS = {
     properties: "1.1",
     graph: "1.1",
     search: "1.2",
-    mutate: "1.2",
+    mutate: "1.3",
     sync: "1.3",
     surface: "1.4",
-    cli: "1.1",
+    cli: "1.2",
 };
 //# sourceMappingURL=spec-versions.js.map

package/package.json

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