@omgbase/core 0.11.0 → 0.11.1

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 <dest> [{ \u2026 }], \u2026]\n                   [order by <expr> [asc|desc], \u2026] [limit N] [offset N]\n  <target> count|exists|none|first|single { <block> }     (scalar/one-row form: a bare target at the root scope)\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`). A top-level predicate needs `where`, because\n`where` follows `from` (`era > 1600 from docs` is the clause-order error); a\nblock may LEAD with a predicate (see Sugar), but a predicate after a projection\nstill needs the keyword (`{ name where kind == \"md:task\" }`, not\n`{ name, kind == \"md:task\" }`); `from docs count` is an error (write\n`docs count { \u2026 }`). `where` and later `select` items may use the same body's\n`select` aliases (`select path, old: era < 1000 from docs where old`; an alias\nshadows a same-named field there). `and` / `or` / `not` are the connectives;\nthe symbols `&&` / `||` / `!` are accepted synonyms (the words are canonical and\nwhat `print` writes).\n\n## Sugar (OQX 0.17)\n\nEvery form here is shorthand for an explicit directive (the AST is the explicit form):\n  nodes { kind == \"md:task\" }        \u2261 nodes collect { where kind == \"md:task\" } \u2014 a receiver block with\n                                       no consumer is collect; a block whose LEADING expression is a predicate\n                                       (comparison, call, !/is/not, in, literal, (\u2026), a consumer test \u2014 anything\n                                       but a bare name, a dotted path or a ^lift) is where-first. Bare names still\n                                       project: nodes { name } \u2261 nodes collect { name }; filter a bare field with\n                                       nodes { is checked }. Wherever a value stands (0.20), call arguments included:\n                                       size(children { is checked }); x distinct { \u2026 } \u2261 x collect distinct { \u2026 }. After a\n                                       follow destination too: follow children { depth 2 } is that destination's block.\n  (a, b)                              a tuple (0.20): two or more expressions, concatenated one level flat \u2014 a value\n                                       (size((tags, aliases)), \"x\" in (tags, aliases)) and a receiver ((a, b) { \u2026 },\n                                       follow (before, after) { depth 2 }); (a) alone is grouping\n  refs(x)[0]                          \u2261 refs(x) first { offset 0 }   positional (integer literal or ${binding});\n                                       out of range \u21D2 absent; refs(x)[0].path navigates the row\n  ^docs[path == ^company]             \u2261 ^docs first { where path == ^company }   first match or absent\n  ^docs[path == ^company]!            \u2261 \u2026 single { \u2026 } required: exactly one, else filter_invalid\n  title!                              required: title, or an error naming the expression (and the row's $key \u2014 its id)\n                                       \u2014 never a filter, never a coercion (0!, \"\"! are values); tightest: a!.b vs a.b!\n  is x / not x                        truthiness of x, and its negation (prefix; `not` \u2261 `!`)\n  x is y / x is not y                 identity ($key: a store row's id, else structural) \u2014 compares rows, which == does not;\n                                       x is null = absent; for scalars is \u2261 ==; comparison precedence, no chaining\n  a and b / a or b                    the connectives (\u2261 && / ||: same precedence, short-circuit, value: data.title or path coalesces)\n  boss: ^docs[path == ^manager], bossName: boss.title   a select item may use the items to its LEFT\n  Reserved words (never a bare field name): from where select is not and or, true false null.\n  Contextual words (limit order offset follow collect count first distinct desc by in frontier depth) parse as\n  fields in expression position (select o: order from docs).\n\nResults are LEAN hits \u2014 { id, path } + whatever `select` projects (or `values`,\n`count`, `exists`, `none`). The envelope keys ARE the attributes: copy a hit's\n`id` straight into `where id == \"\u2026\"` (no translation); `select id, path` is simply\nthe envelope (no duplicate columns); any OTHER projection whose output key would\nbe `id` or `path` must be aliased \u2014 `select data.path` is refused (\"projection\n`path` collides with the hit envelope \u2014 alias it (`p: data.path`)\"); a row\nsurfacing as a value (an empty `collect { }`) is the same `{ id, path }`. Every\nother tool spells a row the same way (`docs_read` \u2192 `{ id, path, rev, properties,\nraw }`, `blocks_read` \u2192 `{ id, type, text, raw, hash, \u2026 }`, `docs_list` \u2192 `{ id,\npath, updated_at, blocks }`, a revision \u2192 `{ id, path, hash }`): hydrate by id via\nblocks_read/docs_read.\n\n## Paths\n\nEvery path the surface returns is `/`-rooted \u2014 the form a reference is\nwritten in (`[x](/projects/oqx.md)`, `before: [/timeline/kickoff.md]`): a\nhit's `path`, an edge's `dst_path`, every tool's paths. Every path it\naccepts tolerates both forms (`/a.md` or `a.md`): tool arguments, `refs(x)`,\n`within(...)`, and a string LITERAL compared with `path`/`dst_path` (bare, or\nthrough a row handle: `doc.path`) by `==`/`!=` or passed to their\n`.startsWith(...)` (it is rooted first, so `path == \"a.md\"` and `path == \"/a.md\"`\nboth match). A property holding a reference compares directly \u2014 and is never\nrooted: `where ^path in list(after)`, `where customer == ^path`,\n`where data.path == \"/x.md\"` (the author's `path:` key, as written) \u2014 no\n`\"/\" + ...` glue.\n\n## Targets & field namespaces\n\nTHE NAME RULE: `$` belongs to OQX \u2014 $it, $key, $depth, $stop, $leaf, $frontier,\n$ordinal are values the LANGUAGE injects into a scope; omgbase adds NO $ names\n(a `$id` in a query is an unknown name, absent). Every engine attribute is a BARE\nsnake_case name that WINS on collision \u2014 the convention the relations (children,\nblocks, out, in, doc, frontmatter, \u2026) always followed: a bare name that is an\nengine attribute reads the engine's value, never yours. Your data is bare too;\nwhere a key of yours collides with an engine name, reach it through a source\nhandle: `data.<k>` (the merged authored view \u2014 frontmatter + inline, exactly the\nread a bare non-colliding key performs), `frontmatter.<k>`, `inline.<k>`. So\n`path` is the engine's /-rooted location and `data.path` your `path:` key;\n`tags` is your tags \u222A the body #hashtags and `data.tags` the authored list alone;\n`title` the computed title (the first H1) and `data.title` your `title:`;\n`entries(data)` lists every authored top-level key. Same value, same name\neverywhere: a hit's `id` is docs_read's `id` and the `id` argument of blocks_read.\n\n  Reserved bare names per kind (engine attributes; handles; self; relations):\n    docs    id path raw hash updated_at title tags format | data frontmatter inline | doc | blocks nodes out in out_links in_links\n    blocks  id path doc_id raw hash updated_at type text attrs depth ordinal | block doc | children nodes out_links section\n    nodes   id path doc_id block_id kind name value attrs | section doc block | blocks subsections children\n    links   id path doc_id block_id via_id dst_id dst_path uri field dst_kind predicate provenance anchor | doc\n  A key of yours with any of these names is `data.<k>` (or frontmatter.<k> /\n  inline.<k> by source; attrs.<k> on a block or node).\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 handles   = data.<k> (merged authored view) / frontmatter.<k> /\n                       inline.<k>; the whole bag as a collection via entries(data)\n                       / entries(frontmatter) / entries(inline) (see entries()).\n  - attributes       = id, path (/-rooted, see Paths), updated_at (ISO-8601,\n                       sorts chronologically), raw (the whole file, frontmatter\n                       included), hash (its sha256, 64 hex), title (the computed\n                       title: the first H1; data.title is the authored key), tags\n                       (authored tags \u222A body #hashtags, deduped, authored first;\n                       data.tags is the authored list), format (the doc's format \u2014\n                       \"markdown\"/\"yaml\"/\"json\"; present on EVERY doc, so\n                       has(format) is always true and `format == \"yaml\"` is the\n                       filter).\n  - relations        = nodes, blocks, doc.out_links / doc.in_links (a doc's\n                       links as rows; the documents at their other end are\n                       out_links collect distinct { from dst } and\n                       in_links collect distinct { from doc } \u2014 there is no\n                       out / in relation).\n\nblocks:\n  - bare fields      = doc_id (the owning doc), type, text (normalized), ordinal\n                       (0-based among siblings), depth (0 at the top level), and\n                       every attrs key FLATTENED onto the row (bare `checked`\n                       reads attrs.checked; `attrs.<k>` still works; the\n                       structural fields win on collision; absent \u21D2 false).\n  - attributes       = id, path (the owning doc's path), raw (the block's raw\n                       source \u2014 a container's raw holds its children), hash\n                       (its sha256 \u2014 the value update/split expect as\n                       expect.content_hash), updated_at.\n  - reach-through    = doc.<key> / doc.path / doc.id / doc.format = the\n                       CONTAINING doc (doc.id and doc.path cost nothing \u2014 they\n                       read the row's own doc_id / joined path, no lookup).\n  - relations        = block.children, block.nodes, block.out_links, section.\n  NOTE: inside a `follow`, $depth/$ordinal are ALWAYS the walk's metadata; a\n  block's own nesting is `depth` / `ordinal` (no $) everywhere.\n\nnodes:\n  - bare fields      = doc_id, block_id (null for a block-less node), kind\n                       (md:task / md:link / md:section / yaml:\u2026), name, value,\n                       + attrs keys flattened (checked, level).\n  - attributes       = id, path.\n  - reach-through    = doc.<key> / doc.id / doc.path, block.type / block.text\n                       / block.id / block.path.\n  - relations        = section.blocks, section.children, section.subsections.\n\nlinks:  (the authored link graph as rows \u2014 one per open link: the relation a link\n        establishes; the md:link NODE is its occurrence in the text and via_id\n        points at it \u2014 a frontmatter link has a row and no node)\n  - bare fields      = doc_id (the SOURCE doc), block_id (the source block; null\n                       for a frontmatter edge), via_id, dst_id (the destination\n                       node id: a doc id, an external node id or phantom:<path>),\n                       dst_path (target doc path, /-rooted; NULL when\n                       dangling/external), uri (external URL; NULL otherwise),\n                       predicate (\"references\"/\"embeds\"/freeform), provenance\n                       (\"link\"/\"frontmatter\"/\"inline_field\"/\u2026), dst_kind\n                       (\"document\"/\"external\"/\"collection\"), anchor, field (the\n                       frontmatter key / inline field it was authored in).\n  - attributes       = id, path (the SOURCE doc's path); doc.<key> reaches the\n                       source document. There is no from_commit: a query sees\n                       open edges only (history is blocks_history/changes_since).\n  - text()/semantic() are N/A on links.\n\n## Scoping (ADR-015; the root row since surface 2.0): 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  ^docs ^nodes ^blocks ^links\n                THE ROOT ROW (surface 2.0, oqx 0.18): the repository is the root\n                scope's row, one scope out from a top-level row, so ^docs there is\n                the whole documents scan (uncorrelated until you add a ^ predicate);\n                one caret per enclosing block (^^docs from depth two), or the\n                absolute 0^docs from ANY depth. ^id / 0^id = the repository id.\n                ^$it = the root object: ^$it.docs \u2261 ^docs, entries(^$it) names the\n                four collections. At the root scope itself a bare target is the scan\n                (docs count { \u2026 }, from docs, entries(docs)).\n                ERRORS: a bare `docs` INSIDE a block reads a property of the current\n                row, which has none \u2014 refused (\"did you mean ^docs\"); `^docs` AT THE\n                TOP LEVEL reaches past the root \u2014 refused (write the bare `docs`);\n                so is `$repo` (surface < 2.0; the message names the replacement).\n                nodes/blocks on a doc row are that doc's RELATIONS, not the root.\n  $it           the current item itself (a row, or each ELEMENT when the\n                receiver is a list property); ^$it = the enclosing row.\n                $value is NOT an intrinsic (since oqx 0.15): it reads a\n                property literally named $value, absent when there is none.\n  $key          the row's identity (0.20): a store row's id (doc/block/node/edge), an entries(x)\n                entry's key, a follow occurrence's walk identity; project $key: <expr> to rekey the\n                rows a block yields (a destination block's $key: is not a column).\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      and  or  not    grouping ( \u2026 )   \u2014 && || ! are accepted synonyms\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 that has embedded the repository; else provider_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                              either path form\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  refs(x)              the live documents a property's document references name:\n                       x is a string, a list or absent; each \"/a/b.md\", \"a/b.md\"\n                       or \"d_\u2026\" element resolves to that doc's row; dangling and\n                       non-string elements are dropped. Yields docs rows, so it is\n                       a source, a receiver or a follow destination:\n                       follow refs(before), refs(after) walks a timeline both ways.\n                       The reverse direction needs no function: a document's\n                       path is already the reference form, so\n                       ^docs { where ^path in list(after) } is\n                       \"the documents whose `after` names me\".\n  A HIT IS A STORE ROW: a top-level row that is not a doc/block/node/edge fails\n                       (filter_invalid). `follow before` over a list of paths\n                       reaches the STRINGS \u2014 write `follow refs(before)`.\n\n## Nested queries & consumers\n\n  <receiver> collect|exists|none|count|first|single { <block> }\n    receiver = a relation (nodes, blocks, doc.out_links, section.blocks, \u2026), a\n               reach-through row (dst, doc: one row \u2014 dst { title }), a\n    list property (tags), entries(x), or a root collection (^docs; 0^docs at depth \u2265 2).\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\" and not checked }\n  none      0 rows      nodes none { where kind == \"md:task\" and not 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\" and not checked }\n  joins     ^<t> exists { where slug == ^ref }  semi-join; not \u2026 exists  anti-join;\n            ^nodes single { where kind == \"person\" and 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 attribute when it is one (id, path, title, \u2026), else the property\n  (scalar-authored \u2192 scalar; list \u2192 array); data.<k> forces the property;\n  a call/arithmetic needs an alias (n: size(tags)) unless in values mode;\n  an output key of id/path other than the attribute itself needs an alias.\n  raw         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                select path values from docs                   \u2192 values: [\"/index.md\", \u2026]\n                tags: tags collect { $it 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 / $it per entry), key order:\n                select fm: entries(data) collect { k: $key, v: $it }\n                where entries(frontmatter) exists { where $key == \"era\" and $it > 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 links\n\n  The citation graph is the LINK ROWS walked through a destination block:\n  dst is a link's destination document (absent for an external or dangling\n  link \u2014 it then contributes no successor), doc its source.\n  from docs where <seed> follow out_links collect { from dst }     docs the seed links TO\n  from docs where <seed> follow in_links collect { from doc }      backlinks\n    follow out_links collect { from dst depth 3 }                  bound (1..8, default 8) \u2014 a clause of the block\n    follow out_links collect { from dst where layer == \"canon\" }   keep only matching successors\n    follow in_links collect { from doc where ^path in list(before) }   ^ = the row being expanded\n                                                   (^^ = the walk's enclosing scope)\n    follow out_links collect { from dst where predicate == \"depends_on\" }   one predicate only\n    follow out_links collect { from dst }, in_links collect { from doc }\n                                                   several destinations: their union\n                                                   (one step dedups by identity)\n    follow ^docs { where out_links exists { where dst_path == ^^path } }\n                                                   a destination block over the root's\n                                                   documents, re-read per frontier row\n                                                   (^ = that row) = the backlinks walk\n    follow out_links collect { from dst frontier type == \"practitioner\" }   cut, keeping the frontier row\n    from docs where type == \"process\" frontier !verified follow out_links collect { from dst }\n                                                   the BODY's frontier applies to the seeds:\n                                                   an unverified seed is kept, not expanded\n    follow distinct out_links collect { from dst } / \u2026 { $key: group from dst }   identity control ($key)\n    follow refs(before), ^docs { where ^path in list(after) }    forward over `before`, backward\n                                                   over every doc whose `after` names me\n  Per-occurrence metadata: $depth (seed = 1), $stop (interior|leaf|frontier|\n  depth|cycle), $leaf/$frontier, $ordinal, $key \u2014 usable in select/order by and\n  the top-level post-walk where, NOT metadata of the candidates a destination\n  block's where reads.\n  Destination blocks (OQX 0.20): a brace after ANY destination opens that\n  destination's block \u2014 children { depth 2 }, refs(x) { depth 2 }, out_links\n  collect { from dst depth 2 }, ^docs { where ^path in list(after) } \u2014 with the\n  0.17 body rules (where-first, projections) and two clauses of its own after\n  `where`: frontier <pred> (occurrences reached through this destination that\n  match are frontiers; ^ there is the walk's enclosing scope) and depth <n>\n  (this destination expands a frontier row only while $depth < n). The body\n  that carries the follow may write frontier <pred> too, after its where and\n  before follow: it applies to the SEEDS (read like the body's where) \u2014 a\n  matching seed stays in the result with $stop == \"frontier\" and is not\n  expanded; each destination's frontier is its own. There is no options block;\n  the old `by` is $key. A bare follow ^docs (no brace, no consumer) is an\n  error naming both block spellings.\n  Type-preserving relations: block.children, section.children, section.subsections;\n  the citation graph is out_links collect { from dst } / in_links collect { from doc }.\n  from links where dst_path == \"/notes/x.md\"       inbound links to a doc, as rows\n  select d: dst.title, k: dst_kind from links       the destination document's title\n  from docs where out_links exists { where dst.layer == \"draft\" }   links into drafts\n  select b: in_links collect distinct { from doc } from docs     backlinks as { id, path }\n  from links where predicate == \"depends_on\" select doc_id, dst_path\n  from docs where not doc.in_links 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/\") and 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\" and not checked }\n  from docs where tags exists { where $it == \"tria-prima\" }\n  from docs where path == \"/x.md\" select fm: entries(data) collect { k: $key, v: $it }\n  from docs select owner_id, owner: ^nodes single { where kind == \"person\" and attrs.id == ^owner_id }\n  from blocks where type == \"task\" and not checked and under_heading(\"Launch\") and doc.layer == \"working\"\n  from blocks where type == \"paragraph\" and has_edge(\"references\", \"d_92aaaaa\")\n  select path, $depth from docs where path == \"/timeline/review.md\" follow refs(before), refs(after)\n  select path, next: ^docs collect { path where ^path in list(before) } from docs where type == \"milestone\"\n  select path, n: size(^docs), repo: ^id from docs limit 1\n  select p: data.path, t: data.title from docs where has(data.path)\n  docs { type == \"substance\" and not verified }\n  select subject, process: ^docs[slug == ^subject]!.path from docs where type == \"lab-note\"\n  select path, back: nodes first { select p: 0^docs collect { path where ^^path in list(after) } values } from docs where type == \"milestone\"\n  select path, prior: refs(before) collect { path, when } from docs where type == \"milestone\"\n  from blocks order by semantic(\"identity preservation across edits\") desc limit 10\n  from links where dst_kind == \"external\" select uri\n  docs count { where layer == \"canon\" }\n\nCommon mistake: `$path`/`$id` (the 2.x spelling) \u2014 omgbase has no $ names; write\n`path`/`id`. Another: `where tags == \"x\"` on a list-valued key is false \u2014 write\n`\"x\" in tags`. Another: `select data.path` \u2014 alias it (`p: data.path`).\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>] [frontier <pred>] [follow <dest> [{ \u2026 }], \u2026]\n                   [order by <expr> [asc|desc], \u2026] [limit N] [offset N]\n  <target> count|exists|none|first|single { <block> }     (scalar/one-row form: a bare target at the root scope)\n\nCLAUSE ORDER IS FIXED: select, from, where, frontier, 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`). A top-level predicate needs `where`, because\n`where` follows `from` (`era > 1600 from docs` is the clause-order error); a\nblock may LEAD with a predicate (see Sugar), but a predicate after a projection\nstill needs the keyword (`{ name where kind == \"md:task\" }`, not\n`{ name, kind == \"md:task\" }`); `from docs count` is an error (write\n`docs count { \u2026 }`). `where` and later `select` items may use the same body's\n`select` aliases (`select path, old: era < 1000 from docs where old`; an alias\nshadows a same-named field there). `and` / `or` / `not` are the connectives;\nthe symbols `&&` / `||` / `!` are accepted synonyms (the words are canonical and\nwhat `print` writes).\n\n## Sugar (OQX 0.17)\n\nEvery form here is shorthand for an explicit directive (the AST is the explicit form):\n  nodes { kind == \"md:task\" }        \u2261 nodes collect { where kind == \"md:task\" } \u2014 a receiver block with\n                                       no consumer is collect; a block whose LEADING expression is a predicate\n                                       (comparison, call, !/is/not, in, literal, (\u2026), a consumer test \u2014 anything\n                                       but a bare name, a dotted path or a ^lift) is where-first. Bare names still\n                                       project: nodes { name } \u2261 nodes collect { name }; filter a bare field with\n                                       nodes { is checked }. Wherever a value stands (0.20), call arguments included:\n                                       size(children { is checked }); x distinct { \u2026 } \u2261 x collect distinct { \u2026 }. After a\n                                       follow destination too: follow children { depth 2 } is that destination's block.\n  (a, b)                              a tuple (0.20): two or more expressions, concatenated one level flat \u2014 a value\n                                       (size((tags, aliases)), \"x\" in (tags, aliases)) and a receiver ((a, b) { \u2026 },\n                                       follow (before, after) { depth 2 }); (a) alone is grouping\n  refs(x)[0]                          \u2261 refs(x) first { offset 0 }   positional (integer literal or ${binding});\n                                       out of range \u21D2 absent; refs(x)[0].path navigates the row\n  ^docs[path == ^company]             \u2261 ^docs first { where path == ^company }   first match or absent\n  ^docs[path == ^company]!            \u2261 \u2026 single { \u2026 } required: exactly one, else filter_invalid\n  title!                              required: title, or an error naming the expression (and the row's $key \u2014 its id)\n                                       \u2014 never a filter, never a coercion (0!, \"\"! are values); tightest: a!.b vs a.b!\n  is x / not x                        truthiness of x, and its negation (prefix; `not` \u2261 `!`)\n  x is y / x is not y                 identity ($key: a store row's id, else structural) \u2014 compares rows, which == does not;\n                                       x is null = absent; for scalars is \u2261 ==; comparison precedence, no chaining\n  a and b / a or b                    the connectives (\u2261 && / ||: same precedence, short-circuit, value: data.title or path coalesces)\n  boss: ^docs[path == ^manager], bossName: boss.title   a select item may use the items to its LEFT\n  Reserved words (never a bare field name): from where select is not and or, true false null.\n  Contextual words (limit order offset follow collect count first distinct desc by in frontier depth) parse as\n  fields in expression position (select o: order from docs).\n\nResults are LEAN hits \u2014 { id, path } + whatever `select` projects (or `values`,\n`count`, `exists`, `none`). The envelope keys ARE the attributes: copy a hit's\n`id` straight into `where id == \"\u2026\"` (no translation); `select id, path` is simply\nthe envelope (no duplicate columns); any OTHER projection whose output key would\nbe `id` or `path` must be aliased \u2014 `select data.path` is refused (\"projection\n`path` collides with the hit envelope \u2014 alias it (`p: data.path`)\"); a row\nsurfacing as a value (an empty `collect { }`) is the same `{ id, path }`. Every\nother tool spells a row the same way (`docs_read` \u2192 `{ id, path, rev, properties,\nraw }`, `blocks_read` \u2192 `{ id, type, text, raw, hash, \u2026 }`, `docs_list` \u2192 `{ id,\npath, updated_at, blocks }`, a revision \u2192 `{ id, path, hash }`): hydrate by id via\nblocks_read/docs_read.\n\n## Paths\n\nEvery path the surface returns is `/`-rooted \u2014 the form a reference is\nwritten in (`[x](/projects/oqx.md)`, `before: [/timeline/kickoff.md]`): a\nhit's `path`, an edge's `dst_path`, every tool's paths. Every path it\naccepts tolerates both forms (`/a.md` or `a.md`): tool arguments, `refs(x)`,\n`within(...)`, and a string LITERAL compared with `path`/`dst_path` (bare, or\nthrough a row handle: `doc.path`) by `==`/`!=` or passed to their\n`.startsWith(...)` (it is rooted first, so `path == \"a.md\"` and `path == \"/a.md\"`\nboth match). A property holding a reference compares directly \u2014 and is never\nrooted: `where ^path in list(after)`, `where customer == ^path`,\n`where data.path == \"/x.md\"` (the author's `path:` key, as written) \u2014 no\n`\"/\" + ...` glue.\n\n## Targets & field namespaces\n\nTHE NAME RULE: `$` belongs to OQX \u2014 $it, $key, $depth, $stop, $leaf, $frontier,\n$ordinal are values the LANGUAGE injects into a scope; omgbase adds NO $ names\n(a `$id` in a query is an unknown name, absent). Every engine attribute is a BARE\nsnake_case name that WINS on collision \u2014 the convention the relations (children,\nblocks, out, in, doc, frontmatter, \u2026) always followed: a bare name that is an\nengine attribute reads the engine's value, never yours. Your data is bare too;\nwhere a key of yours collides with an engine name, reach it through a source\nhandle: `data.<k>` (the merged authored view \u2014 frontmatter + inline, exactly the\nread a bare non-colliding key performs), `frontmatter.<k>`, `inline.<k>`. So\n`path` is the engine's /-rooted location and `data.path` your `path:` key;\n`tags` is your tags \u222A the body #hashtags and `data.tags` the authored list alone;\n`title` the computed title (the first H1) and `data.title` your `title:`;\n`entries(data)` lists every authored top-level key. Same value, same name\neverywhere: a hit's `id` is docs_read's `id` and the `id` argument of blocks_read.\n\n  Reserved bare names per kind (engine attributes; handles; self; relations):\n    docs    id path raw hash updated_at title tags format | data frontmatter inline | doc | blocks nodes out in out_links in_links\n    blocks  id path doc_id raw hash updated_at type text attrs depth ordinal | block doc | children nodes out_links section\n    nodes   id path doc_id block_id kind name value attrs | section doc block | blocks subsections children\n    links   id path doc_id block_id via_id dst_id dst_path uri field dst_kind predicate provenance anchor | doc\n  A key of yours with any of these names is `data.<k>` (or frontmatter.<k> /\n  inline.<k> by source; attrs.<k> on a block or node).\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 handles   = data.<k> (merged authored view) / frontmatter.<k> /\n                       inline.<k>; the whole bag as a collection via entries(data)\n                       / entries(frontmatter) / entries(inline) (see entries()).\n  - attributes       = id, path (/-rooted, see Paths), updated_at (ISO-8601,\n                       sorts chronologically), raw (the whole file, frontmatter\n                       included), hash (its sha256, 64 hex), title (the computed\n                       title: the first H1; data.title is the authored key), tags\n                       (authored tags \u222A body #hashtags, deduped, authored first;\n                       data.tags is the authored list), format (the doc's format \u2014\n                       \"markdown\"/\"yaml\"/\"json\"; present on EVERY doc, so\n                       has(format) is always true and `format == \"yaml\"` is the\n                       filter).\n  - relations        = nodes, blocks, doc.out_links / doc.in_links (a doc's\n                       links as rows; the documents at their other end are\n                       out_links collect distinct { from dst } and\n                       in_links collect distinct { from doc } \u2014 there is no\n                       out / in relation).\n\nblocks:\n  - bare fields      = doc_id (the owning doc), type, text (normalized), ordinal\n                       (0-based among siblings), depth (0 at the top level), and\n                       every attrs key FLATTENED onto the row (bare `checked`\n                       reads attrs.checked; `attrs.<k>` still works; the\n                       structural fields win on collision; absent \u21D2 false).\n  - attributes       = id, path (the owning doc's path), raw (the block's raw\n                       source \u2014 a container's raw holds its children), hash\n                       (its sha256 \u2014 the value update/split expect as\n                       expect.content_hash), updated_at.\n  - reach-through    = doc.<key> / doc.path / doc.id / doc.format = the\n                       CONTAINING doc (doc.id and doc.path cost nothing \u2014 they\n                       read the row's own doc_id / joined path, no lookup).\n  - relations        = block.children, block.nodes, block.out_links, section.\n  NOTE: inside a `follow`, $depth/$ordinal are ALWAYS the walk's metadata; a\n  block's own nesting is `depth` / `ordinal` (no $) everywhere.\n\nnodes:\n  - bare fields      = doc_id, block_id (null for a block-less node), kind\n                       (md:task / md:link / md:section / yaml:\u2026), name, value,\n                       + attrs keys flattened (checked, level).\n  - attributes       = id, path.\n  - reach-through    = doc.<key> / doc.id / doc.path, block.type / block.text\n                       / block.id / block.path.\n  - relations        = section.blocks, section.children, section.subsections.\n\nlinks:  (the authored link graph as rows \u2014 one per open link: the relation a link\n        establishes; the md:link NODE is its occurrence in the text and via_id\n        points at it \u2014 a frontmatter link has a row and no node)\n  - bare fields      = doc_id (the SOURCE doc), block_id (the source block; null\n                       for a frontmatter edge), via_id, dst_id (the destination\n                       node id: a doc id, an external node id or phantom:<path>),\n                       dst_path (target doc path, /-rooted; NULL when\n                       dangling/external), uri (external URL; NULL otherwise),\n                       predicate (\"references\"/\"embeds\"/freeform), provenance\n                       (\"link\"/\"frontmatter\"/\"inline_field\"/\u2026), dst_kind\n                       (\"document\"/\"external\"/\"collection\"), anchor, field (the\n                       frontmatter key / inline field it was authored in).\n  - attributes       = id, path (the SOURCE doc's path); doc.<key> reaches the\n                       source document. There is no from_commit: a query sees\n                       open edges only (history is blocks_history/changes_since).\n  - text()/semantic() are N/A on links.\n\n## Scoping (ADR-015; the root row since surface 2.0): 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  ^docs ^nodes ^blocks ^links\n                THE ROOT ROW (surface 2.0, oqx 0.18): the repository is the root\n                scope's row, one scope out from a top-level row, so ^docs there is\n                the whole documents scan (uncorrelated until you add a ^ predicate);\n                one caret per enclosing block (^^docs from depth two), or the\n                absolute 0^docs from ANY depth. ^id / 0^id = the repository id.\n                ^$it = the root object: ^$it.docs \u2261 ^docs, entries(^$it) names the\n                four collections. At the root scope itself a bare target is the scan\n                (docs count { \u2026 }, from docs, entries(docs)).\n                ERRORS: a bare `docs` INSIDE a block reads a property of the current\n                row, which has none \u2014 refused (\"did you mean ^docs\"); `^docs` AT THE\n                TOP LEVEL reaches past the root \u2014 refused (write the bare `docs`);\n                so is `$repo` (surface < 2.0; the message names the replacement).\n                nodes/blocks on a doc row are that doc's RELATIONS, not the root.\n  $it           the current item itself (a row, or each ELEMENT when the\n                receiver is a list property); ^$it = the enclosing row.\n                $value is NOT an intrinsic (since oqx 0.15): it reads a\n                property literally named $value, absent when there is none.\n  $key          the row's identity (0.20): a store row's id (doc/block/node/edge), an entries(x)\n                entry's key, a follow occurrence's walk identity; project $key: <expr> to rekey the\n                rows a block yields (a destination block's $key: is not a column).\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      and  or  not    grouping ( \u2026 )   \u2014 && || ! are accepted synonyms\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 that has embedded the repository; else provider_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                              either path form\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  refs(x)              the live documents a property's document references name:\n                       x is a string, a list or absent; each \"/a/b.md\", \"a/b.md\"\n                       or \"d_\u2026\" element resolves to that doc's row; dangling and\n                       non-string elements are dropped. Yields docs rows, so it is\n                       a source, a receiver or a follow destination:\n                       follow refs(before), refs(after) walks a timeline both ways.\n                       The reverse direction needs no function: a document's\n                       path is already the reference form, so\n                       ^docs { where ^path in list(after) } is\n                       \"the documents whose `after` names me\".\n  A HIT IS A STORE ROW: a top-level row that is not a doc/block/node/edge fails\n                       (filter_invalid). `follow before` over a list of paths\n                       reaches the STRINGS \u2014 write `follow refs(before)`.\n\n## Nested queries & consumers\n\n  <receiver> collect|exists|none|count|first|single { <block> }\n    receiver = a relation (nodes, blocks, doc.out_links, section.blocks, \u2026), a\n               reach-through row (dst, doc: one row \u2014 dst { title }), a\n    list property (tags), entries(x), or a root collection (^docs; 0^docs at depth \u2265 2).\n    block    = [select \u2026] [where \u2026] [frontier \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\" and not checked }\n  none      0 rows      nodes none { where kind == \"md:task\" and not 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\" and not checked }\n  joins     ^<t> exists { where slug == ^ref }  semi-join; not \u2026 exists  anti-join;\n            ^nodes single { where kind == \"person\" and 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 attribute when it is one (id, path, title, \u2026), else the property\n  (scalar-authored \u2192 scalar; list \u2192 array); data.<k> forces the property;\n  a call/arithmetic needs an alias (n: size(tags)) unless in values mode;\n  an output key of id/path other than the attribute itself needs an alias.\n  raw         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                select distinct type values from docs          \u2192 values: [\"hub\",\"lab-note\",\u2026]\n                select path values from docs                   \u2192 values: [\"/index.md\", \u2026]\n                tags: tags collect { $it 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 / $it per entry), key order:\n                select fm: entries(data) collect { k: $key, v: $it }\n                where entries(frontmatter) exists { where $key == \"era\" and $it > 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 links\n\n  The citation graph is the LINK ROWS walked through a destination block:\n  dst is a link's destination document (absent for an external or dangling\n  link \u2014 it then contributes no successor), doc its source.\n  from docs where <seed> follow out_links collect { from dst }     docs the seed links TO\n  from docs where <seed> follow in_links collect { from doc }      backlinks\n    follow out_links collect { from dst depth 3 }                  bound (1..8, default 8) \u2014 a clause of the block\n    follow out_links collect { from dst where layer == \"canon\" }   keep only matching successors\n    follow in_links collect { from doc where ^path in list(before) }   ^ = the row being expanded\n                                                   (^^ = the walk's enclosing scope)\n    follow out_links collect { from dst where predicate == \"depends_on\" }   one predicate only\n    follow out_links collect { from dst }, in_links collect { from doc }\n                                                   several destinations: their union\n                                                   (one step dedups by identity)\n    follow ^docs { where out_links exists { where dst_path == ^^path } }\n                                                   a destination block over the root's\n                                                   documents, re-read per frontier row\n                                                   (^ = that row) = the backlinks walk\n    follow out_links collect { from dst frontier type == \"practitioner\" }   cut, keeping the frontier row\n    from docs where type == \"process\" frontier !verified follow out_links collect { from dst }\n                                                   the BODY's frontier applies to the seeds:\n                                                   an unverified seed is kept, not expanded\n    follow distinct out_links collect { from dst } / \u2026 { $key: group from dst }   identity control ($key)\n    follow refs(before), ^docs { where ^path in list(after) }    forward over `before`, backward\n                                                   over every doc whose `after` names me\n  Per-occurrence metadata: $depth (seed = 1), $stop (interior|leaf|frontier|\n  depth|cycle), $leaf/$frontier, $ordinal, $key \u2014 usable in select/order by and\n  the top-level post-walk where, NOT metadata of the candidates a destination\n  block's where reads.\n  Destination blocks (OQX 0.20): a brace after ANY destination opens that\n  destination's block \u2014 children { depth 2 }, refs(x) { depth 2 }, out_links\n  collect { from dst depth 2 }, ^docs { where ^path in list(after) } \u2014 with the\n  0.17 body rules (where-first, projections) and two clauses of its own after\n  `where`: frontier <pred> (occurrences reached through this destination that\n  match are frontiers; ^ there is the walk's enclosing scope) and depth <n>\n  (this destination expands a frontier row only while $depth < n). The body\n  that carries the follow may write frontier <pred> too, after its where and\n  before follow: it applies to the SEEDS (read like the body's where) \u2014 a\n  matching seed stays in the result with $stop == \"frontier\" and is not\n  expanded; each destination's frontier is its own. There is no options block;\n  the old `by` is $key. A bare follow ^docs (no brace, no consumer) is an\n  error naming both block spellings.\n  Type-preserving relations: block.children, section.children, section.subsections;\n  the citation graph is out_links collect { from dst } / in_links collect { from doc }.\n  from links where dst_path == \"/notes/x.md\"       inbound links to a doc, as rows\n  select d: dst.title, k: dst_kind from links       the destination document's title\n  from docs where out_links exists { where dst.layer == \"draft\" }   links into drafts\n  select b: in_links collect distinct { from doc } from docs     backlinks as { id, path }\n  select doc_id, dst_path from links where predicate == \"depends_on\"\n  from docs where not doc.in_links 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/\") and updated_at >= \"2026-08-01\"\n  select layer, tags from docs where \"pricing\" in list(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\" and not checked }\n  from docs where tags exists { where $it == \"tria-prima\" }\n  select fm: entries(data) collect { k: $key, v: $it } from docs where path == \"/x.md\"\n  select owner_id, owner: ^nodes single { where kind == \"person\" and attrs.id == ^owner_id } from docs\n  from blocks where type == \"task\" and not checked and under_heading(\"Launch\") and doc.layer == \"working\"\n  from blocks where type == \"paragraph\" and has_edge(\"references\", \"d_92aaaaa\")\n  select path, $depth from docs where path == \"/timeline/review.md\" follow refs(before), refs(after)\n  select path, next: ^docs collect { path where ^path in list(before) } from docs where type == \"milestone\"\n  select path, n: size(^docs), repo: ^id from docs limit 1\n  select p: data.path, t: data.title from docs where has(data.path)\n  docs { type == \"substance\" and not verified }\n  select subject, process: ^docs[slug == ^subject]!.path from docs where type == \"lab-note\"\n  select path, back: nodes first { select p: 0^docs collect { path where ^^path in list(after) } values } from docs where type == \"milestone\"\n  select path, prior: refs(before) collect { path, when } from docs where type == \"milestone\"\n  from blocks order by semantic(\"identity preservation across edits\") desc limit 10\n  select uri from links where dst_kind == \"external\"\n  docs count { where layer == \"canon\" }\n\nCommon mistake: `$path`/`$id` (the 2.x spelling) \u2014 omgbase has no $ names; write\n`path`/`id`. Another: `where tags == \"x\"` on a list-valued key is false \u2014 write\n`\"x\" in tags`. Another: `select data.path` \u2014 alias it (`p: data.path`).\n";

package/dist/src/mcp/reference.js

@@ -10,11 +10,11 @@ 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 <dest> [{ … }], …]
+  [select <items>] from <target> [where <pred>] [frontier <pred>] [follow <dest> [{ … }], …]
                    [order by <expr> [asc|desc], …] [limit N] [offset N]
   <target> count|exists|none|first|single { <block> }     (scalar/one-row form: a bare target at the root scope)
 
-CLAUSE ORDER IS FIXED: select, from, where, follow, order by, limit, offset —
+CLAUSE ORDER IS FIXED: select, from, where, frontier, follow, order by, limit, offset —
 each at most once; an out-of-order clause is a parse error naming the order.
 Only \`select\` may drop its keyword, and only as the first clause
 (\`path, era from docs where …\`). A top-level predicate needs \`where\`, because
@@ -270,7 +270,7 @@ links:  (the authored link graph as rows — one per open link: the relation a l
     receiver = a relation (nodes, blocks, doc.out_links, section.blocks, …), a
                reach-through row (dst, doc: one row — dst { title }), a
     list property (tags), entries(x), or a root collection (^docs; 0^docs at depth ≥ 2).
-    block    = [select …] [where …] [follow …] [order by …] [limit N] [offset N]
+    block    = [select …] [where …] [frontier …] [follow …] [order by …] [limit N] [offset N]
                — the same fixed order as the top level (\`from\` optional; the
                receiver supplies the rows). A leading name/alias list is the
                projection (\`select\` dropped); a predicate always needs \`where\`.
@@ -299,7 +299,7 @@ links:  (the authored link graph as rows — one per open link: the relation a l
   raw         whole file bytes (docs) — docs_read is cheaper for one doc.
   distinct    select distinct type   (dedup hits by projected value)
   values      select <ONE item> values → bare values instead of records:
-                from docs select distinct type values          → values: ["hub","lab-note",…]
+                select distinct type values from docs          → values: ["hub","lab-note",…]
                 select path values from docs                   → values: ["/index.md", …]
                 tags: tags collect { $it values }             → a plain array
                 h: nodes first { name values where kind == "md:section" order by first_ordinal }
@@ -366,7 +366,7 @@ links:  (the authored link graph as rows — one per open link: the relation a l
   select d: dst.title, k: dst_kind from links       the destination document's title
   from docs where out_links exists { where dst.layer == "draft" }   links into drafts
   select b: in_links collect distinct { from doc } from docs     backlinks as { id, path }
-  from links where predicate == "depends_on" select doc_id, dst_path
+  select doc_id, dst_path from links where predicate == "depends_on"
   from docs where not doc.in_links exists { }      orphans (nothing links in)
   (The \`graph\` tool is a convenience wrapper that compiles to a follow query.)
 
@@ -379,15 +379,15 @@ text()/where prune the candidate set; only order by reweights.
 
   from docs where layer == "working"
   from docs where path.startsWith("/guides/") and updated_at >= "2026-08-01"
-  from docs where "pricing" in list(tags) select layer, tags
+  select layer, tags from docs where "pricing" in list(tags)
   from docs where inline.owner == "alice"
   from docs where title.lower().contains("q3 plan")
   from docs where format == "yaml"
   from docs where type == "practitioner" order by era desc limit 2
   from docs where nodes none { where kind == "md:task" and not checked }
   from docs where tags exists { where $it == "tria-prima" }
-  from docs where path == "/x.md" select fm: entries(data) collect { k: $key, v: $it }
-  from docs select owner_id, owner: ^nodes single { where kind == "person" and attrs.id == ^owner_id }
+  select fm: entries(data) collect { k: $key, v: $it } from docs where path == "/x.md"
+  select owner_id, owner: ^nodes single { where kind == "person" and attrs.id == ^owner_id } from docs
   from blocks where type == "task" and not checked and under_heading("Launch") and doc.layer == "working"
   from blocks where type == "paragraph" and has_edge("references", "d_92aaaaa")
   select path, $depth from docs where path == "/timeline/review.md" follow refs(before), refs(after)
@@ -399,7 +399,7 @@ text()/where prune the candidate set; only order by reweights.
   select path, back: nodes first { select p: 0^docs collect { path where ^^path in list(after) } values } from docs where type == "milestone"
   select path, prior: refs(before) collect { path, when } from docs where type == "milestone"
   from blocks order by semantic("identity preservation across edits") desc limit 10
-  from links where dst_kind == "external" select uri
+  select uri from links where dst_kind == "external"
   docs count { where layer == "canon" }
 
 Common mistake: \`$path\`/\`$id\` (the 2.x spelling) — omgbase has no $ names; write

package/dist/src/mcp/server.js

@@ -474,7 +474,7 @@ export function buildServer(ctx) {
         inputSchema: {},
     }, async () => ok({ syntax: QUERY_SYNTAX }));
     tool("query", {
-        description: "OQX (omgbase Query eXpressions) — composable query in ONE expression. Two rules: DOT navigation belongs to the host object model (`doc.layer`, `section.blocks`, `dst.title`); WHITESPACE query directives belong to OQX — a nested query is `<receiver> collect|exists|count|first|single { <block> }` (a postfix directive + a `{ … }` block), never a method. `from E` selects a property/relation relative to the current source scope and flattens it (a typed flatMap): top-level `from docs|blocks|nodes|links` selects the repository's docs/blocks/nodes/links (the `links` target is the authored link graph as first-class rows — one row per link RELATION; the `md:link` node is a link's occurrence in the text, `via_id` points at it, and a frontmatter link has a row and no node — `id`/`path` plus the plain fields doc_id/block_id/via_id/dst_id/dst_path/uri/predicate/provenance/dst_kind/anchor/field, with path/doc.* reaching the SOURCE doc and `dst` the destination DOCUMENT row when the link points at one — `dst.title`, `dst.layer`, `dst_kind == \"document\"`; absent for an external or block destination and for a dangling target); `where`; `select`. Its distinctive power is receiver-constrained nested queries that correlate to the current row: `from docs where nodes exists { where kind == \"md:task\" }` returns only the docs that themselves contain a matching node (not a global scan). Directives: `exists { … }` / `count { … }` in where — with an optional count comparison `nodes count { where kind == \"md:task\" } >= 2`; `collect { … }` in select for hierarchical results, nestable (`select secs: nodes collect { select h: name, items: section.blocks collect { where type == \"list_item\" } where kind == \"md:section\" } from docs`). CLAUSE ORDER IS FIXED (ADR-020): within one body — the top level or any `{ block }` — clauses appear at most once each, in exactly this order: `select … from … where … follow … order by … limit N offset N`. Every clause is optional except a top-level `from`; an out-of-order clause is a parse error naming the order. ONLY `select` may drop its keyword, and only when it is the first clause written (`path, open from docs where …`; `nodes collect { attrs.text }` projects `attrs.text`). Every other clause carries its keyword, with one piece of sugar (oqx 0.17): a block's leading expression is its `where` when it is predicate-shaped (`nodes exists { kind == \"md:task\" }` ≡ `nodes exists { where kind == \"md:task\" }`); a bare name or dotted path is a projection, so filter on a bare field with `is active`, and `{ name where … }` is the projection + filter (`{ age >= 18, name }` is an error). A top-level predicate needs `where` (`where` follows `from`, so `age > 15 from people` is an error), a bare boolean property in leading position PROJECTS (`nodes collect { active }`), and `from docs count` is an error (write `docs count { … }` for the consumer, or `select count from docs` to project a field named count). More sugar, each desugaring in the parser to the explicit directive: a receiver block without a consumer is `collect` (`docs { type == \"x\" }`, `nodes { kind == \"md:task\" }`, `size(nodes { is checked })` — wherever a value stands, and after a `follow` destination too: `follow children { depth 2 }` is that destination's block; `x distinct { … }` is `x collect distinct { … }`); a tuple `(a, b)` (two or more expressions, concatenated one level flat) is a value and a receiver (`\"x\" in (tags, aliases)`, `follow (before, after) { depth 2 }`); brackets `x[p]` = `x first { where p }` (the first match or absent), `x[p]!` = `x single { where p }` required (exactly one, else filter_invalid), `x[n]` = `x first { offset n }` (positional; out of range is absent); postfix `x!` = required (the value, or a loud error naming the expression and the row — never a filter, never a coercion; tightest: `a!.b` vs `a.b!`); prefix `is x` / `not x` (truthiness); infix `x is y` / `x is not y` compares identity (`$key`: a store row's id, else the value — `x is null` is the absence test; for scalars `is` ≡ `==`); and a `select` item may use the items to its left (`boss: ^docs[slug == ^manager], name: boss.title`). `and` / `or` / `not` are the connectives; `&&` / `||` / `!` are accepted synonyms (the canonical printer writes the words). `where` may reference the same body's `select` aliases (`select path, old: era < 1000 from docs where old` — inlined at parse time; an alias shadows a same-named field there). On the nodes/blocks targets a bare identifier that is not a structural field (doc_id, block_id, kind/name/value; doc_id, type/text, ordinal/depth) or row attribute (id, path, raw, hash, updated_at) reads the flattened attrs bag — `checked` == `attrs.checked`, `level` == `attrs.level` — so the name you filter on matches the name a projection returns (`select attrs.checked` yields key `checked`); the `attrs.<key>` form still works and an absent key is silently false. Any consumer accepts `distinct` to dedup the rows it reduces by their projected value — `nodes count distinct { select kind }`, `nodes collect distinct { select kind }`, top-level `select distinct type` (empty projection dedups by identity). `values` after a projection of exactly ONE item returns the bare value instead of a `{name: value}` record: at the top level `select path values from docs where layer == \"canon\"` returns `values: [\"a.md\", …]` (paged like hits; `hits` is empty), and inside a block `select tags: tags collect { $it values }` yields a plain array. `$it` is the current item itself — the row, or the scalar element when the receiver is a list property (`where tags exists { where $it == \"pricing\" }`); inside a block `^$it` is the enclosing row. `none { … }` is the zero-cardinality test — true iff the block yields no rows (≡ `!… exists { … }`), and how \"every\" is spelled: `nodes none { where kind == \"md:task\" and not checked }` = no open tasks; also a whole-query directive (`docs none { … }` returns `none`). `limit N` / `offset N` bound a row set AFTER where/order/distinct and BEFORE the consumer reduces it, so they mean the same under every consumer: at the top level (`order by era desc limit 3` — the tool's `limit`/`cursor` then page within that bounded set) or inside any block (`nodes collect { … order by ordinal limit 1 }`; `nodes exists { offset 1 }` = at least two). `entries(x)` turns a record into a collection of entries — inside the block `$key` is the property key and `$it` (and bare names) the value: `select fm: entries(frontmatter) collect { k: $key, v: $it }`, `from nodes where kind == \"md:task\" and entries(attrs) exists { where $key == \"checked\" and $it }`; works on `data` (the merged authored bag: frontmatter + inline) / `frontmatter` / `inline` (nested dotted keys folded back — an authored `$`-prefixed key such as `$version` is reached as `frontmatter.$version` and listed by `entries(frontmatter)`; a bare `$version` is an unknown OQX name and reads nothing), `attrs`, a nested frontmatter map, or a list (numeric index keys). Plain objects never auto-iterate; `entries()` is the explicit bridge. The where clause is a boolean tree: compose scalar predicates and consumer directives with `and`, `or`, `not`, and grouping (`layer == \"canon\" or nodes exists { where kind == \"md:task\" }`). Relative source: `from E` inside a top-level consumer block re-projects the rows — `docs collect { from nodes where kind == \"md:task\" }` starts at docs, projects each doc through its `nodes` relation, and queries the resulting nodes (a scalar relation like `from doc` contributes one row; a missing/non-navigable relation is a loud error, never a global scan). One-scope lift: a `collect` in `where` with a `^name` both filters (non-empty) and binds the matching values into the parent select in one expression — `select path, open from docs where nodes collect { ^open: value where kind == \"md:task\" and not attrs.checked }` returns the docs with an open task, each carrying its open-task texts. Correlation / joins (the `^` sigil, symmetric with the lift): a nested query may READ a name bound one scope outward — bind it in the parent (a select value or a lift), then reference `^name` inside a nested query's where. Combined with the root row's collections `^docs` / `^nodes` / `^blocks` / `^links` (the repository is OQX's root row, one scope out from a top-level row — one caret per enclosing block, or the absolute `0^docs` from any depth; an UNBOUNDED repository scan, uncorrelated until you add a `^` predicate) this expresses lateral/dependent joins without a JOIN keyword: `^<t> exists { where … == ^k }` = semi-join, `not … exists { … }` = anti-join, `… collect { … }` in select = nested left-join, and the select-only lookups `first { … }` / `single { … }` (zero-or-one / one-to-one; `single` errors if it matches >1) — e.g. `select owner_id, owner: ^nodes single { where kind == \"person\" and attrs.id == ^owner_id } from docs`. Membership over a lifted set: `<value> in ^keys`. `^` reads exactly ONE scope out (no arbitrary-ancestor search), and a bare name reads the CURRENT row only — it never falls through to an enclosing row or the root, so reach outward explicitly with `^name` (the enclosing row) or `^docs` / `0^docs` (the root row's collections; `^id` / `0^id` is the repository id, `^$it` the root object). A bare `docs` INSIDE a block is an error (\"did you mean `^docs`\"), never an empty read; `$repo` (surface < 2.0) is refused with the replacement spelled out. PATHS are `/`-rooted on the surface (surface 2.0): every path returned — `path`, an edge's `dst_path`, a hit's `path` — is the reference form (`/a/b.md`), and a string literal compared with `path`/`dst_path` by `==`/`!=` or passed to their `startsWith` accepts both forms (`path == \"a.md\"` and `path == \"/a.md\"` both match); a property's value is the author's, so a reference held in frontmatter compares with `^path` directly (`^docs { ^path in list(after) }` = the documents whose `after` names me). `refs(field)` resolves the document REFERENCES a property holds (a string or a list of `/a.md`, `a.md` or `d_…` elements; dangling and non-string elements dropped) to live docs rows, so it is a source (`from refs(\"/a.md\")`), a receiver (`refs(before) collect { path, when }`, `refs(see_also)[0]`) or a `follow` destination (`follow refs(before), refs(after)` walks a timeline both ways); `follow before` over the strings fails — a hit must be a document, block, node or edge row. Top-level consumers: the whole query can be a consumer directive over a bare root receiver (a target name at the root scope) to change its result shape — `docs count { … }`, `docs exists { … }` and `docs none { … }` reduce to a scalar (returned as `count`/`exists`/`none`, no hits), `docs first { … }` / `docs single { … }` return zero-or-one hit (`single` errors if the query matches >1); a bare `from …` is the collect form. (A bare target at the root scope is the same collection `^<target>` reaches from inside where/select.) Scalar predicates follow the @omgbase/oqx semantics (strict typed equality with absence normalized so `!=` over an absent field matches; case-sensitive string ops with `.lower()`/`.upper()` and a regex `matches()`; absent sorts last; arithmetic supported), including doc.<key> reach-through and `text(\"terms\")` — a full-text (FTS5) PRUNING predicate that, because it is an ordinary predicate, composes inside correlated subqueries and collects (e.g. `nodes exists { where kind == \"md:task\" and text(\"ship\") }`), which the flat `query` tool cannot express. (`text` prunes; relevance ranking is separate.) And `semantic(\"phrase\")` — an embedding cosine SCORE (docs/blocks only) usable as a threshold prune (`semantic(\"the great work\") > 0.6`) or a projection (`select score: semantic(\"…\")`); it needs an embedding provider that has embedded this repository (else `provider_unavailable`, naming what to configure — never a silent unranked result) and, like `text`, composes inside nested scopes. Ranking: `order by <expr> [asc|desc], …` sorts the result (`order by semantic(\"the great work\") desc` = semantic top-K; also orders by any frontmatter field / `path`), always tie-broken by (path, id) for a total order — this is how score functions become a ranking. A custom order disables the keyset cursor (you still get the top `limit` with `truncated`). Recursion (`follow`): make the query recursive over a TYPE-PRESERVING relation (the relation's successor type must equal the query target). `from blocks where id == \"b_x\" follow block.children` walks the block subtree from a seed; the `where` picks the SEED rows and `follow <relation>` expands them. A bare `follow <relation>` carries no sub-clauses; a brace after any destination opens that destination's block (oqx 0.20 — there is no options block), an ordinary block with two clauses of its own after `where`: `follow <rel> { where <pred> }` filters which successors keep participating at each hop (running out ⇒ a leaf), `{ frontier <pred> }` cuts a relation that could otherwise continue (⇒ a frontier; only occurrences this destination reached), `{ depth <n> }` bounds the walk through this destination (1..8, default 8). `follow distinct` dedups reached rows by identity (the default keeps one occurrence per distinct walk path). Identity is `$key` — a store row's id; a block may project `$key: <expr>` to rekey the rows it yields (a destination block's `$key:` is not a column) — e.g. `follow out_links collect { $key: group from dst }` treats same-`group` documents as one node. Each reached row carries recursion metadata: `$depth` (seed = 1), the categorical `$stop` (interior | leaf | frontier | depth | cycle) with `$leaf`/`$frontier` boolean sugar, and `$ordinal` (a deterministic 1..N rank over the walk, ordered by depth then path — `order by $ordinal` for walk order, `where $ordinal <= N` for a deterministic budget cut). It is queryable in select / order by AND filterable post-walk in the top-level `where` (a `where` conjunct referencing a recursion intrinsic filters the walk's RESULT — `from blocks where type == \"list_item\" and $leaf follow block.children` = the leaves; the non-recursion conjuncts remain the seed predicate). Recursion intrinsics are NOT valid in a destination block's `where` or `frontier` (those run mid-walk, before the metadata exists), nor inside a consumer directive. Cyclic graphs are safe: a revisited node is admitted once as a `$stop == \"cycle\"` occurrence and never re-expanded. Type-preserving relations today: `block.children` (blocks→blocks, immediate child blocks), `section.children` (nodes→nodes, immediate child sections — a true outline depth ladder) and `section.subsections` (nodes→nodes, the whole transitive sub-tree — flattens to depth 2). The authored citation graph is walked through the LINK ROWS with a destination block (docs→docs): `follow out_links collect { from dst }` reaches the documents a doc links TO (`dst` is a link's destination document; an external or dangling link has none and contributes no successor), `follow in_links collect { from doc }` its backlinks (`doc` is the link's source); `depth`/`frontier` are clauses of the block — `follow out_links collect { from dst depth 2 }`; filter the rows first for a predicate-restricted walk (`follow out_links collect { from dst where predicate == \"depends_on\" }`). There is no `out`/`in` relation (surface 3.0 — a doc's `out`/`in` is an ordinary absent property). Consumers compose over the walk (`blocks count { where … follow block.children }`). A `follow` may also nest inside a select-position `collect` for a per-row recursive subtree: `select outline: nodes collect { select n: name, d: $depth where kind == \"md:section\" and name == \"Overview\" follow section.children } from docs` (the collect's `where` seeds, correlated to the row; `follow` recurses; the collect's `select` projects each occurrence). Receivers: from docs — `nodes`, `blocks`, `doc.out_links`/`doc.in_links` (a doc's outgoing/incoming links as rows; the documents at their other end are `out_links collect distinct { from dst }` / `in_links collect distinct { from doc }`); from links — `doc` (the source document) and `dst` (the destination document, when there is one); from nodes — `section.blocks` (content under an `md:section` node's heading, transitively including deeper headings), `section.children` (immediate child sections), and `section.subsections` (all contained sections); from blocks — `section` (enclosing `md:section` node(s)), `block.children` (child blocks), `block.nodes` (the projected nodes anchored to this block — links/tasks/anchors/…), and `block.out_links` (this block's outgoing links as rows — body links + inline fields; frontmatter links are doc-grain, use `doc.out_links`); from any row — `^docs` / `^nodes` / `^blocks` / `^links` (the root row's collections; `0^docs` from any depth). Returns lean hits {id, path, ...projections} — the envelope keys are the attributes, so a hit's `id` pastes into the next `where id == …` unchanged, and is the value a tool's `id` argument takes (the name rule, surface 3.0: omgbase adds no `$` names — `$` belongs to OQX's `$it`/`$key`/`$depth`…; every engine attribute is bare snake_case and WINS on collision — id/path everywhere, raw/hash/updated_at on docs and blocks, title/tags/format on docs — and an authored key of the same name is reached through `data.<k>` / `frontmatter.<k>` / `inline.<k>`; `select id, path` is simply the envelope and any other projection whose key would be id/path must be aliased (`p: data.path`); every tool result spells a row with the same names) — with truncated + cursor (or a `count`/`exists` scalar for those consumers). Covers structural + section navigation + ad-hoc correlation + bounded recursive traversal (`follow`).",
+        description: "OQX (omgbase Query eXpressions) — composable query in ONE expression. Clause order is fixed: select, from, where, frontier, follow, order by, limit, offset — `select` first (`select path, era from docs where era > 1600 order by era desc limit 3`), its keyword optional only there; `from docs where … select …` is a parse error naming the order. Two rules: DOT navigation belongs to the host object model (`doc.layer`, `section.blocks`, `dst.title`); WHITESPACE query directives belong to OQX — a nested query is `<receiver> collect|exists|count|first|single { <block> }` (a postfix directive + a `{ … }` block), never a method. The clauses, in writing order: `select` projects the hit's columns (`select path, title`; an alias per computed item, `n: size(tags)`; no `select` = the bare envelope); `from E` selects a property/relation relative to the current source scope and flattens it (a typed flatMap): top-level `from docs|blocks|nodes|links` selects the repository's docs/blocks/nodes/links (the `links` target is the authored link graph as first-class rows — one row per link RELATION; the `md:link` node is a link's occurrence in the text, `via_id` points at it, and a frontmatter link has a row and no node — `id`/`path` plus the plain fields doc_id/block_id/via_id/dst_id/dst_path/uri/predicate/provenance/dst_kind/anchor/field, with path/doc.* reaching the SOURCE doc and `dst` the destination DOCUMENT row when the link points at one — `dst.title`, `dst.layer`, `dst_kind == \"document\"`; absent for an external or block destination and for a dangling target); `where` filters the rows; then `frontier`, `follow`, `order by`, `limit`/`offset` (each below). Its distinctive power is receiver-constrained nested queries that correlate to the current row: `from docs where nodes exists { where kind == \"md:task\" }` returns only the docs that themselves contain a matching node (not a global scan). Directives: `exists { … }` / `count { … }` in where — with an optional count comparison `nodes count { where kind == \"md:task\" } >= 2`; `collect { … }` in select for hierarchical results, nestable (`select secs: nodes collect { select h: name, items: section.blocks collect { where type == \"list_item\" } where kind == \"md:section\" } from docs`). CLAUSE ORDER IS FIXED (ADR-020): within one body — the top level or any `{ block }` — clauses appear at most once each, in exactly this order: `select … from … where … frontier … follow … order by … limit N offset N` (`frontier <pred>` is a clause of a body that has a `follow` — it marks the body's SEEDS, oqx 0.20). Every clause is optional except a top-level `from`; an out-of-order clause is a parse error naming the order. ONLY `select` may drop its keyword, and only when it is the first clause written (`path, open from docs where …`; `nodes collect { attrs.text }` projects `attrs.text`). Every other clause carries its keyword, with one piece of sugar (oqx 0.17): a block's leading expression is its `where` when it is predicate-shaped (`nodes exists { kind == \"md:task\" }` ≡ `nodes exists { where kind == \"md:task\" }`); a bare name or dotted path is a projection, so filter on a bare field with `is active`, and `{ name where … }` is the projection + filter (`{ age >= 18, name }` is an error). A top-level predicate needs `where` (`where` follows `from`, so `age > 15 from people` is an error), a bare boolean property in leading position PROJECTS (`nodes collect { active }`), and `from docs count` is an error (write `docs count { … }` for the consumer, or `select count from docs` to project a field named count). More sugar, each desugaring in the parser to the explicit directive: a receiver block without a consumer is `collect` (`docs { type == \"x\" }`, `nodes { kind == \"md:task\" }`, `size(nodes { is checked })` — wherever a value stands, and after a `follow` destination too: `follow children { depth 2 }` is that destination's block; `x distinct { … }` is `x collect distinct { … }`); a tuple `(a, b)` (two or more expressions, concatenated one level flat) is a value and a receiver (`\"x\" in (tags, aliases)`, `follow (before, after) { depth 2 }`); brackets `x[p]` = `x first { where p }` (the first match or absent), `x[p]!` = `x single { where p }` required (exactly one, else filter_invalid), `x[n]` = `x first { offset n }` (positional; out of range is absent); postfix `x!` = required (the value, or a loud error naming the expression and the row — never a filter, never a coercion; tightest: `a!.b` vs `a.b!`); prefix `is x` / `not x` (truthiness); infix `x is y` / `x is not y` compares identity (`$key`: a store row's id, else the value — `x is null` is the absence test; for scalars `is` ≡ `==`); and a `select` item may use the items to its left (`boss: ^docs[slug == ^manager], name: boss.title`). `and` / `or` / `not` are the connectives; `&&` / `||` / `!` are accepted synonyms (the canonical printer writes the words). `where` may reference the same body's `select` aliases (`select path, old: era < 1000 from docs where old` — inlined at parse time; an alias shadows a same-named field there). On the nodes/blocks targets a bare identifier that is not a structural field (doc_id, block_id, kind/name/value; doc_id, type/text, ordinal/depth) or row attribute (id, path, raw, hash, updated_at) reads the flattened attrs bag — `checked` == `attrs.checked`, `level` == `attrs.level` — so the name you filter on matches the name a projection returns (`select attrs.checked` yields key `checked`); the `attrs.<key>` form still works and an absent key is silently false. Any consumer accepts `distinct` to dedup the rows it reduces by their projected value — `nodes count distinct { select kind }`, `nodes collect distinct { select kind }`, top-level `select distinct type` (empty projection dedups by identity). `values` after a projection of exactly ONE item returns the bare value instead of a `{name: value}` record: at the top level `select path values from docs where layer == \"canon\"` returns `values: [\"a.md\", …]` (paged like hits; `hits` is empty), and inside a block `select tags: tags collect { $it values }` yields a plain array. `$it` is the current item itself — the row, or the scalar element when the receiver is a list property (`where tags exists { where $it == \"pricing\" }`); inside a block `^$it` is the enclosing row. `none { … }` is the zero-cardinality test — true iff the block yields no rows (≡ `!… exists { … }`), and how \"every\" is spelled: `nodes none { where kind == \"md:task\" and not checked }` = no open tasks; also a whole-query directive (`docs none { … }` returns `none`). `limit N` / `offset N` bound a row set AFTER where/order/distinct and BEFORE the consumer reduces it, so they mean the same under every consumer: at the top level (`order by era desc limit 3` — the tool's `limit`/`cursor` then page within that bounded set) or inside any block (`nodes collect { … order by ordinal limit 1 }`; `nodes exists { offset 1 }` = at least two). `entries(x)` turns a record into a collection of entries — inside the block `$key` is the property key and `$it` (and bare names) the value: `select fm: entries(frontmatter) collect { k: $key, v: $it }`, `from nodes where kind == \"md:task\" and entries(attrs) exists { where $key == \"checked\" and $it }`; works on `data` (the merged authored bag: frontmatter + inline) / `frontmatter` / `inline` (nested dotted keys folded back — an authored `$`-prefixed key such as `$version` is reached as `frontmatter.$version` and listed by `entries(frontmatter)`; a bare `$version` is an unknown OQX name and reads nothing), `attrs`, a nested frontmatter map, or a list (numeric index keys). Plain objects never auto-iterate; `entries()` is the explicit bridge. The where clause is a boolean tree: compose scalar predicates and consumer directives with `and`, `or`, `not`, and grouping (`layer == \"canon\" or nodes exists { where kind == \"md:task\" }`). Relative source: `from E` inside a top-level consumer block re-projects the rows — `docs collect { from nodes where kind == \"md:task\" }` starts at docs, projects each doc through its `nodes` relation, and queries the resulting nodes (a scalar relation like `from doc` contributes one row; a missing/non-navigable relation is a loud error, never a global scan). One-scope lift: a `collect` in `where` with a `^name` both filters (non-empty) and binds the matching values into the parent select in one expression — `select path, open from docs where nodes collect { ^open: value where kind == \"md:task\" and not attrs.checked }` returns the docs with an open task, each carrying its open-task texts. Correlation / joins (the `^` sigil, symmetric with the lift): a nested query may READ a name bound one scope outward — bind it in the parent (a select value or a lift), then reference `^name` inside a nested query's where. Combined with the root row's collections `^docs` / `^nodes` / `^blocks` / `^links` (the repository is OQX's root row, one scope out from a top-level row — one caret per enclosing block, or the absolute `0^docs` from any depth; an UNBOUNDED repository scan, uncorrelated until you add a `^` predicate) this expresses lateral/dependent joins without a JOIN keyword: `^<t> exists { where … == ^k }` = semi-join, `not … exists { … }` = anti-join, `… collect { … }` in select = nested left-join, and the select-only lookups `first { … }` / `single { … }` (zero-or-one / one-to-one; `single` errors if it matches >1) — e.g. `select owner_id, owner: ^nodes single { where kind == \"person\" and attrs.id == ^owner_id } from docs`. Membership over a lifted set: `<value> in ^keys`. `^` reads exactly ONE scope out (no arbitrary-ancestor search), and a bare name reads the CURRENT row only — it never falls through to an enclosing row or the root, so reach outward explicitly with `^name` (the enclosing row) or `^docs` / `0^docs` (the root row's collections; `^id` / `0^id` is the repository id, `^$it` the root object). A bare `docs` INSIDE a block is an error (\"did you mean `^docs`\"), never an empty read; `$repo` (surface < 2.0) is refused with the replacement spelled out. PATHS are `/`-rooted on the surface (surface 2.0): every path returned — `path`, an edge's `dst_path`, a hit's `path` — is the reference form (`/a/b.md`), and a string literal compared with `path`/`dst_path` by `==`/`!=` or passed to their `startsWith` accepts both forms (`path == \"a.md\"` and `path == \"/a.md\"` both match); a property's value is the author's, so a reference held in frontmatter compares with `^path` directly (`^docs { ^path in list(after) }` = the documents whose `after` names me). `refs(field)` resolves the document REFERENCES a property holds (a string or a list of `/a.md`, `a.md` or `d_…` elements; dangling and non-string elements dropped) to live docs rows, so it is a source (`from refs(\"/a.md\")`), a receiver (`refs(before) collect { path, when }`, `refs(see_also)[0]`) or a `follow` destination (`follow refs(before), refs(after)` walks a timeline both ways); `follow before` over the strings fails — a hit must be a document, block, node or edge row. Top-level consumers: the whole query can be a consumer directive over a bare root receiver (a target name at the root scope) to change its result shape — `docs count { … }`, `docs exists { … }` and `docs none { … }` reduce to a scalar (returned as `count`/`exists`/`none`, no hits), `docs first { … }` / `docs single { … }` return zero-or-one hit (`single` errors if the query matches >1); a bare `from …` is the collect form. (A bare target at the root scope is the same collection `^<target>` reaches from inside where/select.) Scalar predicates follow the @omgbase/oqx semantics (strict typed equality with absence normalized so `!=` over an absent field matches; case-sensitive string ops with `.lower()`/`.upper()` and a regex `matches()`; absent sorts last; arithmetic supported), including doc.<key> reach-through and `text(\"terms\")` — a full-text (FTS5) PRUNING predicate that, because it is an ordinary predicate, composes inside correlated subqueries and collects (e.g. `nodes exists { where kind == \"md:task\" and text(\"ship\") }`), which the flat `query` tool cannot express. (`text` prunes; relevance ranking is separate.) And `semantic(\"phrase\")` — an embedding cosine SCORE (docs/blocks only) usable as a threshold prune (`semantic(\"the great work\") > 0.6`) or a projection (`select score: semantic(\"…\")`); it needs an embedding provider that has embedded this repository (else `provider_unavailable`, naming what to configure — never a silent unranked result) and, like `text`, composes inside nested scopes. Ranking: `order by <expr> [asc|desc], …` sorts the result (`order by semantic(\"the great work\") desc` = semantic top-K; also orders by any frontmatter field / `path`), always tie-broken by (path, id) for a total order — this is how score functions become a ranking. A custom order disables the keyset cursor (you still get the top `limit` with `truncated`). Recursion (`follow`): make the query recursive over a TYPE-PRESERVING relation (the relation's successor type must equal the query target). `from blocks where id == \"b_x\" follow block.children` walks the block subtree from a seed; the `where` picks the SEED rows and `follow <relation>` expands them. A bare `follow <relation>` carries no sub-clauses; a brace after any destination opens that destination's block (oqx 0.20 — there is no options block), an ordinary block with two clauses of its own after `where`: `follow <rel> { where <pred> }` filters which successors keep participating at each hop (running out ⇒ a leaf), `{ frontier <pred> }` cuts a relation that could otherwise continue (⇒ a frontier; only occurrences this destination reached), `{ depth <n> }` bounds the walk through this destination (1..8, default 8). `follow distinct` dedups reached rows by identity (the default keeps one occurrence per distinct walk path). Identity is `$key` — a store row's id; a block may project `$key: <expr>` to rekey the rows it yields (a destination block's `$key:` is not a column) — e.g. `follow out_links collect { $key: group from dst }` treats same-`group` documents as one node. Each reached row carries recursion metadata: `$depth` (seed = 1), the categorical `$stop` (interior | leaf | frontier | depth | cycle) with `$leaf`/`$frontier` boolean sugar, and `$ordinal` (a deterministic 1..N rank over the walk, ordered by depth then path — `order by $ordinal` for walk order, `where $ordinal <= N` for a deterministic budget cut). It is queryable in select / order by AND filterable post-walk in the top-level `where` (a `where` conjunct referencing a recursion intrinsic filters the walk's RESULT — `from blocks where type == \"list_item\" and $leaf follow block.children` = the leaves; the non-recursion conjuncts remain the seed predicate). Recursion intrinsics are NOT valid in a destination block's `where` or `frontier` (those run mid-walk, before the metadata exists), nor inside a consumer directive. Cyclic graphs are safe: a revisited node is admitted once as a `$stop == \"cycle\"` occurrence and never re-expanded. Type-preserving relations today: `block.children` (blocks→blocks, immediate child blocks), `section.children` (nodes→nodes, immediate child sections — a true outline depth ladder) and `section.subsections` (nodes→nodes, the whole transitive sub-tree — flattens to depth 2). The authored citation graph is walked through the LINK ROWS with a destination block (docs→docs): `follow out_links collect { from dst }` reaches the documents a doc links TO (`dst` is a link's destination document; an external or dangling link has none and contributes no successor), `follow in_links collect { from doc }` its backlinks (`doc` is the link's source); `depth`/`frontier` are clauses of the block — `follow out_links collect { from dst depth 2 }`; filter the rows first for a predicate-restricted walk (`follow out_links collect { from dst where predicate == \"depends_on\" }`). There is no `out`/`in` relation (surface 3.0 — a doc's `out`/`in` is an ordinary absent property). Consumers compose over the walk (`blocks count { where … follow block.children }`). A `follow` may also nest inside a select-position `collect` for a per-row recursive subtree: `select outline: nodes collect { select n: name, d: $depth where kind == \"md:section\" and name == \"Overview\" follow section.children } from docs` (the collect's `where` seeds, correlated to the row; `follow` recurses; the collect's `select` projects each occurrence). Receivers: from docs — `nodes`, `blocks`, `doc.out_links`/`doc.in_links` (a doc's outgoing/incoming links as rows; the documents at their other end are `out_links collect distinct { from dst }` / `in_links collect distinct { from doc }`); from links — `doc` (the source document) and `dst` (the destination document, when there is one); from nodes — `section.blocks` (content under an `md:section` node's heading, transitively including deeper headings), `section.children` (immediate child sections), and `section.subsections` (all contained sections); from blocks — `section` (enclosing `md:section` node(s)), `block.children` (child blocks), `block.nodes` (the projected nodes anchored to this block — links/tasks/anchors/…), and `block.out_links` (this block's outgoing links as rows — body links + inline fields; frontmatter links are doc-grain, use `doc.out_links`); from any row — `^docs` / `^nodes` / `^blocks` / `^links` (the root row's collections; `0^docs` from any depth). Returns lean hits {id, path, ...projections} — the envelope keys are the attributes, so a hit's `id` pastes into the next `where id == …` unchanged, and is the value a tool's `id` argument takes (the name rule, surface 3.0: omgbase adds no `$` names — `$` belongs to OQX's `$it`/`$key`/`$depth`…; every engine attribute is bare snake_case and WINS on collision — id/path everywhere, raw/hash/updated_at on docs and blocks, title/tags/format on docs — and an authored key of the same name is reached through `data.<k>` / `frontmatter.<k>` / `inline.<k>`; `select id, path` is simply the envelope and any other projection whose key would be id/path must be aliased (`p: data.path`); every tool result spells a row with the same names) — with truncated + cursor (or a `count`/`exists` scalar for those consumers). Covers structural + section navigation + ad-hoc correlation + bounded recursive traversal (`follow`).",
         inputSchema: {
             query: z.string(),
             limit: z.number().int().optional(),

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

@@ -180,7 +180,7 @@ function describeValue(v) {
     return "an object";
 }
 function notAStoreRow(v) {
-    return new FilterInvalid(`a hit must be a document, block, node or edge row — the query reached ${describeValue(v)}; to follow document references held in a property use refs(<field>)`, "OQX");
+    return new FilterInvalid(`a hit must be a document, block, node or link row — the query reached ${describeValue(v)}; to follow document references held in a property use refs(<field>)`, "OQX");
 }
 // The reserved key a top-level `values` projection's single item is renamed to,
 // so it rides through id/path injection, keyset paging, and distinct as an

package/package.json

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