@omgbase/core 0.6.0 → 0.7.0

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/reference.d.ts

@@ -1 +1 @@
-export declare const QUERY_SYNTAX = "# query \u2014 OQX syntax reference\n\nThe `query` tool takes ONE plain OQX string (+ optional `limit`/`cursor`). There\nis no {from, filter, order} envelope: every concern is a clause of the string.\n\n  [select <items>] from <target> [where <pred>] [follow <relation> [{ \u2026 }]]\n                   [order by <expr> [asc|desc], \u2026] [limit N] [offset N]\n  $repo.<target> count|exists|none|first|single { <block> }     (scalar/one-row form)\n\nCLAUSE ORDER IS FIXED: select, from, where, follow, order by, limit, offset \u2014\neach at most once; an out-of-order clause is a parse error naming the order.\nOnly `select` may drop its keyword, and only as the first clause\n(`$path, era from docs where \u2026`). Every other clause always carries its keyword:\na predicate is NEVER implicit (`nodes exists { where kind == \"md:task\" }`, not\n`{ kind == \"md:task\" }`), and `from docs count` is an error (write\n`$repo.docs count { \u2026 }`). `where` may use the same body's `select` aliases\n(`select $path, old: era < 1000 from docs where old`; an alias shadows a\nsame-named field there).\n\nResults are LEAN hits \u2014 {id, path} + whatever `select` projects (or `values`,\n`count`, `exists`, `none`). Hydrate full content by id via nodes_get/docs_read.\n\n## Targets & field namespaces\n\nThe sigil rule: `$`-prefixed names are engine intrinsics; BARE identifiers are\nyour content. On docs a bare first segment that collides with an intrinsic base\nname (id/path/repo/updated_at/content_hash/body) is REJECTED with a \"did you mean\n$X?\" hint (bare `path` would silently read an absent frontmatter key). Force the\nproperty with `frontmatter.<k>`. `title`/`tags` are NOT reserved: `$title`/`$tags`\nare computed and never shadow an authored `title:`/`tags:` key.\n\ndocs:\n  - bare identifier  = a document PROPERTY (frontmatter + inline `key:: value`,\n                       unioned; nested via dots: meta.owner). YAML/JSON docs\n                       expose the parsed object's keys the same way.\n  - source-scoped    = frontmatter.<k> / inline.<k>; the whole bag as a collection\n                       via entries(frontmatter) / entries(inline) (see entries()).\n  - computed         = $title (first H1), $tags (body #hashtags), format\n                       (the doc's format \u2014 \"markdown\"/\"yaml\"/\"json\"; a bare\n                       computed field, present on EVERY doc, so has(format) is\n                       always true and `format == \"yaml\"` is the filter).\n  - intrinsics       = $id, $path, $updated_at (ISO-8601, sorts chronologically),\n                       $body (whole file), $content_hash.\n  - relations        = nodes, blocks, doc.out / doc.in (citation graph),\n                       doc.out_edges / doc.in_edges (a doc's edges as rows).\n\nblocks:\n  - bare fields      = type, text, and every attrs key FLATTENED onto the row\n                       (bare `checked` reads attrs.checked; `attrs.<k>` still\n                       works; type/text win on collision; absent \u21D2 false).\n  - intrinsics       = $id, $doc, $path, $ordinal, $depth, $updated_at, $body\n                       (the block text), $content_hash (the block's OWN raw hash \u2014\n                       the value update/split expect).\n  - reach-through    = doc.<key> / doc.$path / doc.format = the CONTAINING doc.\n  - relations        = block.children, block.nodes, block.out_edges, section.\n\nnodes:\n  - bare fields      = kind (md:task / md:link / md:section / yaml:\u2026), name,\n                       value, + attrs keys flattened (checked, level).\n  - intrinsics       = $id (=$node_id), $doc_id, $block_id, $path.\n  - reach-through    = doc.<key>, block.type / block.text.\n  - relations        = section.blocks, section.children, section.subsections.\n\nedges:  (the authored link graph as rows \u2014 one per open edge)\n  - bare fields      = predicate (\"references\"/\"embeds\"/freeform), provenance\n                       (\"link\"/\"frontmatter\"/\"inline_field\"/\u2026), dst_kind\n                       (\"document\"/\"external\"/\"collection\"), anchor, src_field\n  - intrinsics       = $id, $src, $dst, $dst_path (target doc path; NULL when\n                       dangling/external), $dst_uri (external URL; NULL\n                       otherwise), $src_block, $via, $from_commit; $path and\n                       doc.<key> reach the SOURCE document.\n  - text()/semantic() are N/A on edges.\n\n## Scoping (ADR-015): bare names are LOCAL\n\n  name          the CURRENT row only \u2014 never falls through to an enclosing row\n                or the repository; an absent field is simply absent.\n  ^name         one scope OUT (the enclosing row's fields/intrinsics/lifts);\n                ^^name two scopes out. `^$path` = the enclosing row's path.\n  $repo.<t>     the root scan \u2014 $repo.docs / $repo.nodes / $repo.blocks /\n                $repo.edges \u2014 available from ANY depth (uncorrelated until you\n                add a ^ predicate). $repo.$id = the repository id.\n  $value        the current item itself (a row, or each ELEMENT when the\n                receiver is a list property); ^$value = the enclosing row.\n  $key          inside an entries(x) block: the entry's key.\n\n## Scalar semantics (@omgbase/oqx)\n\n  comparisons  ==  !=  <  <=  >  >=    strict & typed (5 == \"5\" is false); either\n                                       side may be a field (field-vs-field OK).\n  absence      null and a missing field are the same \"absent\" value; two absents\n               are EQUAL, so `absent != \"x\"` is TRUE and `absent == null` is TRUE.\n               Relational (< <= > >=) on an absent operand \u2192 FALSE. Bare `f` in\n               boolean position uses JS truthiness (absent/false/0/\"\" \u21D2 false;\n               NOTE: \"false\", [] and {} are truthy). has(f) = explicit presence.\n  boolean      &&  ||  !    grouping ( \u2026 )\n  arithmetic   + - * / %    (+ concatenates if either side is a string)\n  membership   x in y       array \u2192 typed membership; string \u2192 substring;\n                            object \u2192 key exists; range \u2192 coverage. Any list\n                            property works directly: \"pricing\" in tags. list(f)\n                            coerces scalar-or-list (absent \u2192 []) \u2014 use it when a\n                            key is sometimes scalar, sometimes a list.\n  ranges       lo..hi (inclusive)  lo...hi (exclusive hi)  ..hi  lo..\n               era in 800..1680; works over ISO dates. range(prop) reads a\n               range-shaped STRING property as an interval: \"2026-01-15\" in range(window).\n  strings      x.contains(\"s\") x.startsWith(\"p\") x.endsWith(\"s\") x.matches(\"^re$\")\n               (real regex) x.lower() x.upper() size(x). ALL CASE-SENSITIVE \u2014\n               fold with .lower(): $title.lower().contains(\"aurora\").\n  functions    has(f)  size(x)  list(x)  entries(x)  range(s)\n  literals     \"str\" 'str' 123 1.5 true false null\n  determinism  no now()/clock/random. Lists/structs are not literals; ternary is\n               not supported. Errors surface as filter_invalid.\n  scalars vs lists  a list-authored key never == a scalar (tags == \"x\" is false\n               when tags is a list) \u2014 use `\"x\" in tags` / `in list(tags)`.\n\n## Domain predicates (omgbase)\n\n  text(\"terms\")        FTS5 PRUNING predicate (docs match via their blocks, nodes\n                       via the node index); composes anywhere, incl. nested scopes.\n  semantic(\"phrase\")   embedding cosine SCORE (docs/blocks): threshold it\n                       (semantic(\"x\") > 0.6), project it, or `order by semantic(\"x\")\n                       desc` for top-K. Needs a provider; else semantic_unavailable.\n  blocks target only:\n    under(id_or_heading)      block in the containment subtree / section range\n    under_heading(\"Launch\")   an ancestor section heading contains the text (ci)\n    under_kind(type[, name])  an ancestor block has that type (name: its text\n                              contains / its key equals name)\n    within(\"path\" | \"d_..\")   containing doc = id, exact path, or path glob (*)\n    yaml_path(\"a.b\")          YAML docs: the block at that key path\n    json_pointer(\"#/a/b\")     JSON docs: the block at that pointer\n    has_edge(\"pred\"[, target])  an open authored edge with that predicate leaves here\n    has_anchor()              block carries an authored ^ref\n    parent_type() == \"x\"      parent block's type (must be compared)\n    child_count() > 0         number of direct children (must be compared)\n\n## Nested queries & consumers\n\n  <receiver> collect|exists|none|count|first|single { <block> }\n    receiver = a relation (nodes, blocks, doc.out_edges, section.blocks, \u2026), a\n    list property (tags), entries(x), or a root ($repo.docs).\n    block    = [select \u2026] [where \u2026] [follow \u2026] [order by \u2026] [limit N] [offset N]\n               \u2014 the same fixed order as the top level (`from` optional; the\n               receiver supplies the rows). A leading name/alias list is the\n               projection (`select` dropped); a predicate always needs `where`.\n  exists    \u22651 row      nodes exists { where kind == \"md:task\" && !checked }\n  none      0 rows      nodes none { where kind == \"md:task\" && !checked }  (\"every task done\")\n  count     a number    nodes count { where kind == \"md:task\" } >= 2\n  collect   rows (default) \u2014 in select for nested results; in where with a lift\n  first / single   zero-or-one (single errors on >1) \u2014 lookups in select\n  distinct  on any consumer: dedup by projected value \u2014 nodes count distinct { select kind }\n  limit/offset  bound the block's rows AFTER where/order/distinct, BEFORE the\n            consumer reduces: nodes exists { offset 1 } = at least two;\n            first { \u2026 offset 1 } = the second.\n  lift      `^name:` in a where-collect binds values outward:\n            select $path, open from docs where nodes collect { ^open: value where kind == \"md:task\" && !checked }\n  joins     $repo.<t> exists { where slug == ^ref }  semi-join; !\u2026 exists  anti-join;\n            $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id }  lookup;\n            x in ^keys  membership over a lifted set.\n\n## select \u2014 projection\n\n  select a, alias: expr, nested: nodes collect { \u2026 }\n  bare key \u2192 the property (scalar-authored \u2192 scalar; list \u2192 array); $-intrinsics;\n  a call/arithmetic needs an alias (n: size(tags)) unless in values mode.\n  \"$body\"     whole file bytes (docs) \u2014 docs_read is cheaper for one doc.\n  distinct    select distinct type   (dedup hits by projected value)\n  values      select <ONE item> values \u2192 bare values instead of records:\n                from docs select distinct type values          \u2192 values: [\"hub\",\"lab-note\",\u2026]\n                tags: tags collect { $value values }             \u2192 a plain array\n                h: nodes first { name values where kind == \"md:section\" order by first_ordinal }\n  entries(x)  a record as a collection ($key / $value per entry), key order:\n                select fm: entries(frontmatter) collect { k: $key, v: $value }\n                where entries(frontmatter) exists { where $key == \"era\" && $value > 1600 }\n                entries(inline), entries(attrs), a nested map, or a list (index keys)\n  $semantic_score is not a field \u2014 project semantic(\"\u2026\") under an alias instead.\n\n## order by, limit/offset, pagination\n\n  order by era desc, $path asc     absent values sort LAST (asc); ties \u2192 (path, id)\n  limit N / offset N               define the result SET (integer literals);\n                                   the tool's limit/cursor then page WITHIN it\n  cursor                           opaque keyset on (path,id); a custom order by\n                                   disables it (you get the top page + truncated)\n\n## Graph traversal (follow) and edges\n\n  from docs where <seed> follow doc.out            docs the seed links TO\n  from docs where <seed> follow doc.in             backlinks\n    follow doc.out { depth 3 }                     bound (1..8, default 8)\n    follow doc.out { where layer == \"canon\" }      keep only matching successors\n    follow doc.out { frontier type == \"practitioner\" }   cut, keeping the frontier row\n    follow distinct doc.out / follow doc.out { by group } identity control\n  Per-occurrence metadata: $depth (seed = 1), $stop (interior|leaf|frontier|\n  depth|cycle), $leaf/$frontier, $ordinal \u2014 usable in select/order by and the\n  top-level post-walk where, NOT in the follow-local where/frontier.\n  Type-preserving relations: doc.out/doc.in, block.children, section.children,\n  section.subsections.\n  from edges where $dst_path == \"notes/x.md\"       inbound edges to a doc, as rows\n  from edges where predicate == \"depends_on\" select $src, $dst_path\n  from docs where !doc.in_edges exists { }         orphans (nothing links in)\n  (The `graph` tool is a convenience wrapper that compiles to a follow query.)\n\n## semantic grain\n\nfrom docs ranks whole DOCUMENTS (one hit per file); from blocks ranks PASSAGES.\ntext()/where prune the candidate set; only order by reweights.\n\n## Examples\n\n  from docs where layer == \"working\"\n  from docs where $path.startsWith(\"guides/\") && $updated_at >= \"2026-08-01\"\n  from docs where \"pricing\" in list(tags) select layer, tags\n  from docs where inline.owner == \"alice\"\n  from docs where $title.lower().contains(\"q3 plan\")\n  from docs where format == \"yaml\"\n  from docs where type == \"practitioner\" order by era desc limit 2\n  from docs where nodes none { where kind == \"md:task\" && !checked }\n  from docs where tags exists { where $value == \"tria-prima\" }\n  from docs where $path == \"x.md\" select fm: entries(frontmatter) collect { k: $key, v: $value }\n  from docs select owner_id, owner: $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id }\n  from blocks where type == \"task\" && !checked && under_heading(\"Launch\") && doc.layer == \"working\"\n  from blocks where type == \"paragraph\" && has_edge(\"references\", \"d_92aaaaa\")\n  from blocks order by semantic(\"identity preservation across edits\") desc limit 10\n  from edges where dst_kind == \"external\" select $dst_uri\n  $repo.docs count { where layer == \"canon\" }\n\nCommon mistake: bare `path.startsWith(...)` meant the intrinsic \u2014 it fails loud\nwith a hint; write `$path.startsWith(...)`. Another: `where tags == \"x\"` on a\nlist-valued key is false \u2014 write `\"x\" in tags`.\n";
+export declare const QUERY_SYNTAX = "# query \u2014 OQX syntax reference\n\nThe `query` tool takes ONE plain OQX string (+ optional `limit`/`cursor`). There\nis no {from, filter, order} envelope: every concern is a clause of the string.\n\n  [select <items>] from <target> [where <pred>] [follow <dest>, \u2026 [{ \u2026 }]]\n                   [order by <expr> [asc|desc], \u2026] [limit N] [offset N]\n  $repo.<target> count|exists|none|first|single { <block> }     (scalar/one-row form)\n\nCLAUSE ORDER IS FIXED: select, from, where, follow, order by, limit, offset \u2014\neach at most once; an out-of-order clause is a parse error naming the order.\nOnly `select` may drop its keyword, and only as the first clause\n(`$path, era from docs where \u2026`). Every other clause always carries its keyword:\na predicate is NEVER implicit (`nodes exists { where kind == \"md:task\" }`, not\n`{ kind == \"md:task\" }`), and `from docs count` is an error (write\n`$repo.docs count { \u2026 }`). `where` may use the same body's `select` aliases\n(`select $path, old: era < 1000 from docs where old`; an alias shadows a\nsame-named field there).\n\nResults are LEAN hits \u2014 {id, path} + whatever `select` projects (or `values`,\n`count`, `exists`, `none`). Hydrate full content by id via nodes_get/docs_read.\n\n## Targets & field namespaces\n\nThe sigil rule: `$`-prefixed names are engine intrinsics; BARE identifiers are\nyour content. On docs a bare first segment that collides with an intrinsic base\nname (id/path/repo/updated_at/content_hash/body) is REJECTED with a \"did you mean\n$X?\" hint (bare `path` would silently read an absent frontmatter key). Force the\nproperty with `frontmatter.<k>`. `title`/`tags` are NOT reserved: `$title`/`$tags`\nare computed and never shadow an authored `title:`/`tags:` key.\n\ndocs:\n  - bare identifier  = a document PROPERTY (frontmatter + inline `key:: value`,\n                       unioned; nested via dots: meta.owner). YAML/JSON docs\n                       expose the parsed object's keys the same way.\n  - source-scoped    = frontmatter.<k> / inline.<k>; the whole bag as a collection\n                       via entries(frontmatter) / entries(inline) (see entries()).\n  - computed         = $title (first H1), $tags (body #hashtags), format\n                       (the doc's format \u2014 \"markdown\"/\"yaml\"/\"json\"; a bare\n                       computed field, present on EVERY doc, so has(format) is\n                       always true and `format == \"yaml\"` is the filter).\n  - intrinsics       = $id, $path, $updated_at (ISO-8601, sorts chronologically),\n                       $body (whole file), $content_hash.\n  - relations        = nodes, blocks, doc.out / doc.in (citation graph),\n                       doc.out_edges / doc.in_edges (a doc's edges as rows).\n\nblocks:\n  - bare fields      = type, text, and every attrs key FLATTENED onto the row\n                       (bare `checked` reads attrs.checked; `attrs.<k>` still\n                       works; type/text win on collision; absent \u21D2 false).\n  - intrinsics       = $id, $doc, $path, $ordinal, $depth, $updated_at, $body\n                       (the block text), $content_hash (the block's OWN raw hash \u2014\n                       the value update/split expect).\n  - reach-through    = doc.<key> / doc.$path / doc.format = the CONTAINING doc.\n  - relations        = block.children, block.nodes, block.out_edges, section.\n\nnodes:\n  - bare fields      = kind (md:task / md:link / md:section / yaml:\u2026), name,\n                       value, + attrs keys flattened (checked, level).\n  - intrinsics       = $id (=$node_id), $doc_id, $block_id, $path.\n  - reach-through    = doc.<key>, block.type / block.text.\n  - relations        = section.blocks, section.children, section.subsections.\n\nedges:  (the authored link graph as rows \u2014 one per open edge)\n  - bare fields      = predicate (\"references\"/\"embeds\"/freeform), provenance\n                       (\"link\"/\"frontmatter\"/\"inline_field\"/\u2026), dst_kind\n                       (\"document\"/\"external\"/\"collection\"), anchor, src_field\n  - intrinsics       = $id, $src, $dst, $dst_path (target doc path; NULL when\n                       dangling/external), $dst_uri (external URL; NULL\n                       otherwise), $src_block, $via, $from_commit; $path and\n                       doc.<key> reach the SOURCE document.\n  - text()/semantic() are N/A on edges.\n\n## Scoping (ADR-015): bare names are LOCAL\n\n  name          the CURRENT row only \u2014 never falls through to an enclosing row\n                or the repository; an absent field is simply absent.\n  ^name         one scope OUT (the enclosing row's fields/intrinsics/lifts);\n                ^^name two scopes out. `^$path` = the enclosing row's path.\n  $repo.<t>     the root scan \u2014 $repo.docs / $repo.nodes / $repo.blocks /\n                $repo.edges \u2014 available from ANY depth (uncorrelated until you\n                add a ^ predicate). $repo.$id = the repository id.\n  $value        the current item itself (a row, or each ELEMENT when the\n                receiver is a list property); ^$value = the enclosing row.\n  $key          inside an entries(x) block: the entry's key.\n\n## Scalar semantics (@omgbase/oqx)\n\n  comparisons  ==  !=  <  <=  >  >=    strict & typed (5 == \"5\" is false); either\n                                       side may be a field (field-vs-field OK).\n  absence      null and a missing field are the same \"absent\" value; two absents\n               are EQUAL, so `absent != \"x\"` is TRUE and `absent == null` is TRUE.\n               Relational (< <= > >=) on an absent operand \u2192 FALSE. Bare `f` in\n               boolean position uses JS truthiness (absent/false/0/\"\" \u21D2 false;\n               NOTE: \"false\", [] and {} are truthy). has(f) = explicit presence.\n  boolean      &&  ||  !    grouping ( \u2026 )\n  arithmetic   + - * / %    (+ concatenates if either side is a string)\n  membership   x in y       array \u2192 typed membership; string \u2192 substring;\n                            object \u2192 key exists; range \u2192 coverage. Any list\n                            property works directly: \"pricing\" in tags. list(f)\n                            coerces scalar-or-list (absent \u2192 []) \u2014 use it when a\n                            key is sometimes scalar, sometimes a list.\n  ranges       lo..hi (inclusive)  lo...hi (exclusive hi)  ..hi  lo..\n               era in 800..1680; works over ISO dates. range(prop) reads a\n               range-shaped STRING property as an interval: \"2026-01-15\" in range(window).\n  strings      x.contains(\"s\") x.startsWith(\"p\") x.endsWith(\"s\") x.matches(\"^re$\")\n               (real regex) x.lower() x.upper() size(x). ALL CASE-SENSITIVE \u2014\n               fold with .lower(): $title.lower().contains(\"aurora\").\n  functions    has(f)  size(x)  list(x)  entries(x)  range(s)\n  literals     \"str\" 'str' 123 1.5 true false null\n  determinism  no now()/clock/random. Lists/structs are not literals; ternary is\n               not supported. Errors surface as filter_invalid.\n  scalars vs lists  a list-authored key never == a scalar (tags == \"x\" is false\n               when tags is a list) \u2014 use `\"x\" in tags` / `in list(tags)`.\n\n## Domain predicates (omgbase)\n\n  text(\"terms\")        FTS5 PRUNING predicate (docs match via their blocks, nodes\n                       via the node index); composes anywhere, incl. nested scopes.\n  semantic(\"phrase\")   embedding cosine SCORE (docs/blocks): threshold it\n                       (semantic(\"x\") > 0.6), project it, or `order by semantic(\"x\")\n                       desc` for top-K. Needs a provider; else semantic_unavailable.\n  blocks target only:\n    under(id_or_heading)      block in the containment subtree / section range\n    under_heading(\"Launch\")   an ancestor section heading contains the text (ci)\n    under_kind(type[, name])  an ancestor block has that type (name: its text\n                              contains / its key equals name)\n    within(\"path\" | \"d_..\")   containing doc = id, exact path, or path glob (*)\n    yaml_path(\"a.b\")          YAML docs: the block at that key path\n    json_pointer(\"#/a/b\")     JSON docs: the block at that pointer\n    has_edge(\"pred\"[, target])  an open authored edge with that predicate leaves here\n    has_anchor()              block carries an authored ^ref\n    parent_type() == \"x\"      parent block's type (must be compared)\n    child_count() > 0         number of direct children (must be compared)\n\n## Nested queries & consumers\n\n  <receiver> collect|exists|none|count|first|single { <block> }\n    receiver = a relation (nodes, blocks, doc.out_edges, section.blocks, \u2026), a\n    list property (tags), entries(x), or a root ($repo.docs).\n    block    = [select \u2026] [where \u2026] [follow \u2026] [order by \u2026] [limit N] [offset N]\n               \u2014 the same fixed order as the top level (`from` optional; the\n               receiver supplies the rows). A leading name/alias list is the\n               projection (`select` dropped); a predicate always needs `where`.\n  exists    \u22651 row      nodes exists { where kind == \"md:task\" && !checked }\n  none      0 rows      nodes none { where kind == \"md:task\" && !checked }  (\"every task done\")\n  count     a number    nodes count { where kind == \"md:task\" } >= 2\n  collect   rows (default) \u2014 in select for nested results; in where with a lift\n  first / single   zero-or-one (single errors on >1) \u2014 lookups in select\n  distinct  on any consumer: dedup by projected value \u2014 nodes count distinct { select kind }\n  limit/offset  bound the block's rows AFTER where/order/distinct, BEFORE the\n            consumer reduces: nodes exists { offset 1 } = at least two;\n            first { \u2026 offset 1 } = the second.\n  lift      `^name:` in a where-collect binds values outward:\n            select $path, open from docs where nodes collect { ^open: value where kind == \"md:task\" && !checked }\n  joins     $repo.<t> exists { where slug == ^ref }  semi-join; !\u2026 exists  anti-join;\n            $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id }  lookup;\n            x in ^keys  membership over a lifted set.\n\n## select \u2014 projection\n\n  select a, alias: expr, nested: nodes collect { \u2026 }\n  bare key \u2192 the property (scalar-authored \u2192 scalar; list \u2192 array); $-intrinsics;\n  a call/arithmetic needs an alias (n: size(tags)) unless in values mode.\n  \"$body\"     whole file bytes (docs) \u2014 docs_read is cheaper for one doc.\n  distinct    select distinct type   (dedup hits by projected value)\n  values      select <ONE item> values \u2192 bare values instead of records:\n                from docs select distinct type values          \u2192 values: [\"hub\",\"lab-note\",\u2026]\n                tags: tags collect { $value values }             \u2192 a plain array\n                h: nodes first { name values where kind == \"md:section\" order by first_ordinal }\n  entries(x)  a record as a collection ($key / $value per entry), key order:\n                select fm: entries(frontmatter) collect { k: $key, v: $value }\n                where entries(frontmatter) exists { where $key == \"era\" && $value > 1600 }\n                entries(inline), entries(attrs), a nested map, or a list (index keys)\n  $semantic_score is not a field \u2014 project semantic(\"\u2026\") under an alias instead.\n\n## order by, limit/offset, pagination\n\n  order by era desc, $path asc     absent values sort LAST (asc); ties \u2192 (path, id)\n  limit N / offset N               define the result SET (integer literals);\n                                   the tool's limit/cursor then page WITHIN it\n  cursor                           opaque keyset on (path,id); a custom order by\n                                   disables it (you get the top page + truncated)\n\n## Graph traversal (follow) and edges\n\n  from docs where <seed> follow doc.out            docs the seed links TO\n  from docs where <seed> follow doc.in             backlinks\n    follow doc.out { depth 3 }                     bound (1..8, default 8)\n    follow doc.out { where layer == \"canon\" }      keep only matching successors\n    follow doc.in { where before.contains(^$path) }   ^ = the row being expanded\n                                                   (^^ = the walk's enclosing scope)\n    follow doc.out, doc.in                         several destinations: their union\n                                                   (one step dedups by identity)\n    follow $repo.docs collect { where doc.out exists { where $path == ^^$path } }\n                                                   a destination block, re-read per\n                                                   frontier row (^ = that row) = doc.in\n    follow doc.out { frontier type == \"practitioner\" }   cut, keeping the frontier row\n    follow distinct doc.out / follow doc.out { by group } identity control\n  Per-occurrence metadata: $depth (seed = 1), $stop (interior|leaf|frontier|\n  depth|cycle), $leaf/$frontier, $ordinal \u2014 usable in select/order by and the\n  top-level post-walk where, NOT metadata of the candidates the follow-local\n  where/frontier read.\n  Type-preserving relations: doc.out/doc.in, block.children, section.children,\n  section.subsections.\n  from edges where $dst_path == \"notes/x.md\"       inbound edges to a doc, as rows\n  from edges where predicate == \"depends_on\" select $src, $dst_path\n  from docs where !doc.in_edges exists { }         orphans (nothing links in)\n  (The `graph` tool is a convenience wrapper that compiles to a follow query.)\n\n## semantic grain\n\nfrom docs ranks whole DOCUMENTS (one hit per file); from blocks ranks PASSAGES.\ntext()/where prune the candidate set; only order by reweights.\n\n## Examples\n\n  from docs where layer == \"working\"\n  from docs where $path.startsWith(\"guides/\") && $updated_at >= \"2026-08-01\"\n  from docs where \"pricing\" in list(tags) select layer, tags\n  from docs where inline.owner == \"alice\"\n  from docs where $title.lower().contains(\"q3 plan\")\n  from docs where format == \"yaml\"\n  from docs where type == \"practitioner\" order by era desc limit 2\n  from docs where nodes none { where kind == \"md:task\" && !checked }\n  from docs where tags exists { where $value == \"tria-prima\" }\n  from docs where $path == \"x.md\" select fm: entries(frontmatter) collect { k: $key, v: $value }\n  from docs select owner_id, owner: $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id }\n  from blocks where type == \"task\" && !checked && under_heading(\"Launch\") && doc.layer == \"working\"\n  from blocks where type == \"paragraph\" && has_edge(\"references\", \"d_92aaaaa\")\n  from blocks order by semantic(\"identity preservation across edits\") desc limit 10\n  from edges where dst_kind == \"external\" select $dst_uri\n  $repo.docs count { where layer == \"canon\" }\n\nCommon mistake: bare `path.startsWith(...)` meant the intrinsic \u2014 it fails loud\nwith a hint; write `$path.startsWith(...)`. Another: `where tags == \"x\"` on a\nlist-valued key is false \u2014 write `\"x\" in tags`.\n";

package/dist/src/mcp/reference.js

@@ -10,7 +10,7 @@ export const QUERY_SYNTAX = `# query — OQX syntax reference
 The \`query\` tool takes ONE plain OQX string (+ optional \`limit\`/\`cursor\`). There
 is no {from, filter, order} envelope: every concern is a clause of the string.
 
-  [select <items>] from <target> [where <pred>] [follow <relation> [{ … }]]
+  [select <items>] from <target> [where <pred>] [follow <dest>, … [{ … }]]
                    [order by <expr> [asc|desc], …] [limit N] [offset N]
   $repo.<target> count|exists|none|first|single { <block> }     (scalar/one-row form)
 
@@ -195,11 +195,19 @@ edges:  (the authored link graph as rows — one per open edge)
   from docs where <seed> follow doc.in             backlinks
     follow doc.out { depth 3 }                     bound (1..8, default 8)
     follow doc.out { where layer == "canon" }      keep only matching successors
+    follow doc.in { where before.contains(^$path) }   ^ = the row being expanded
+                                                   (^^ = the walk's enclosing scope)
+    follow doc.out, doc.in                         several destinations: their union
+                                                   (one step dedups by identity)
+    follow $repo.docs collect { where doc.out exists { where $path == ^^$path } }
+                                                   a destination block, re-read per
+                                                   frontier row (^ = that row) = doc.in
     follow doc.out { frontier type == "practitioner" }   cut, keeping the frontier row
     follow distinct doc.out / follow doc.out { by group } identity control
   Per-occurrence metadata: $depth (seed = 1), $stop (interior|leaf|frontier|
   depth|cycle), $leaf/$frontier, $ordinal — usable in select/order by and the
-  top-level post-walk where, NOT in the follow-local where/frontier.
+  top-level post-walk where, NOT metadata of the candidates the follow-local
+  where/frontier read.
   Type-preserving relations: doc.out/doc.in, block.children, section.children,
   section.subsections.
   from edges where $dst_path == "notes/x.md"       inbound edges to a doc, as rows

package/dist/src/mcp/server.js

@@ -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/oqx-js/planner.js

@@ -122,8 +122,12 @@ function subMayRaise(s, target) {
         return true;
     return false;
 }
+// A destination is a relation Expr read in the frontier row's scope, or a
+// destination block (an OpNode) whose receiver and body may each raise.
 function followMayRaise(f, target) {
-    return [f.receiver, f.where, f.frontier, f.by].some((e) => e !== null && exprMayRaise(e, target, false));
+    if (f.destinations.some((d) => (d.kind === "op" ? opMayRaise(d, target, false) : exprMayRaise(d, target, false))))
+        return true;
+    return [f.where, f.frontier, f.by].some((e) => e !== null && exprMayRaise(e, target, false));
 }
 function exprMayRaise(e, target, root) {
     switch (e.kind) {

package/dist/src/oqx-js/run.js

@@ -53,7 +53,8 @@ function rewriteOp(op) {
 function rewriteFollow(f) {
     return {
         ...f,
-        receiver: rewriteExpr(f.receiver),
+        // each destination is a relation Expr or a destination block (an OpNode)
+        destinations: f.destinations.map((d) => (d.kind === "op" ? rewriteOp(d) : rewriteExpr(d))),
         where: f.where ? rewriteExpr(f.where) : null,
         frontier: f.frontier ? rewriteExpr(f.frontier) : null,
         by: f.by ? rewriteExpr(f.by) : null,
@@ -156,6 +157,10 @@ export function collectSemanticPhrases(source) {
         }
     };
     const visitOp = (op) => { visitExpr(op.receiver); visitSub(op.sub); };
+    const visitFollow = (f) => {
+        f.destinations.forEach((d) => (d.kind === "op" ? visitOp(d) : visitExpr(d)));
+        [f.where, f.frontier, f.by].forEach((x) => x && visitExpr(x));
+    };
     const visitSub = (s) => {
         s.from.forEach(visitExpr);
         if (s.where)
@@ -163,10 +168,8 @@ export function collectSemanticPhrases(source) {
         s.select.forEach((it) => it.kind === "field" ? visitExpr(it.expr) : visitOp(it.op));
         if (s.orderBy)
             s.orderBy.forEach((o) => visitExpr(o.expr));
-        if (s.follow) {
-            visitExpr(s.follow.receiver);
-            [s.follow.where, s.follow.frontier, s.follow.by].forEach((x) => x && visitExpr(x));
-        }
+        if (s.follow)
+            visitFollow(s.follow);
     };
     let q;
     try {
@@ -182,10 +185,8 @@ export function collectSemanticPhrases(source) {
     q.select.forEach((it) => it.kind === "field" ? visitExpr(it.expr) : visitOp(it.op));
     if (q.orderBy)
         q.orderBy.forEach((o) => visitExpr(o.expr));
-    if (q.follow) {
-        visitExpr(q.follow.receiver);
-        [q.follow.where, q.follow.frontier, q.follow.by].forEach((x) => x && visitExpr(x));
-    }
+    if (q.follow)
+        visitFollow(q.follow);
     return [...phrases];
 }
 const ID_ITEM = { kind: "field", name: "__oqx_id", expr: { kind: "ident", name: "$id" }, lift: 0 };

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

@@ -1,5 +1,5 @@
 export declare const SPEC_VERSIONS: {
-    readonly oqx: "0.13";
+    readonly oqx: "0.14";
     readonly format: "0.2";
     readonly reconcile: "2.3";
     readonly store: "13.5";

package/package.json

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