@omgbase/core 0.1.0

package/dist/src/index.js

@@ -0,0 +1,70 @@
+export { VERSION } from "./core/index.js";
+export { AdapterCapability } from "./format/adapter.js";
+export { registerAdapter, adapterForFormat, adapterForPath, registeredFormats, detectFormat } from "./format/registry.js";
+export { markdownAdapter, MARKDOWN_FORMAT } from "./format/markdown.js";
+export { yamlAdapter, YAML_FORMAT } from "./format/yaml.js";
+export { jsonAdapter, JSON_FORMAT } from "./format/json.js";
+export { writeDocNodes, deleteDocNodes } from "./core/store/nodes.js";
+export { docPropertiesMerged, docPropertiesGrouped, writeDocProperties, flattenFrontmatter } from "./core/store/properties.js";
+// Side-effect: registers built-in adapters.
+import "./format/index.js";
+// Workspace + sync surface used by the CLI (second client, 11 §1).
+export { Store } from "./core/store/store.js";
+export { Workspace, RepoSelectionError } from "./sync/workspace.js";
+export { resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, deepMerge, } from "./sync/settings.js";
+export { freshnessSweep, rebuildFileStats, recordFileStat, detectDiskDrift } from "./sync/freshness.js";
+export { withWriterLock, writerLockFree, WriterLockTimeout } from "./sync/writer-lock.js";
+export { WatchLease, watchLeaseLive } from "./sync/watch-lease.js";
+export { ingestDirectory } from "./sync/attach.js";
+export { ensureRepo } from "./core/attach.js";
+export { walkMarkdown, walkMarkdownAsync } from "./sync/fs-util.js";
+export { Watcher } from "./sync/watcher.js";
+export { createExternalSource } from "./sync/external-source.js";
+export { ensureAdapter, listAdapters, createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, renderConfigFlags, } from "./sync/sources.js";
+export { reconcileChanges, attachSource } from "./sync/driver.js";
+export { observeFile, observeMany, observeOne, observeDelete } from "./sync/observe.js";
+export { buildServer } from "./mcp/server.js";
+export { serveStdio } from "./mcp/stdio.js";
+export { processCheckpoint } from "./sync/checkpoint.js";
+export { reposStatus, syncStatus } from "./sync/admin.js";
+// Read surface consumed by CLI read commands (11 §5.2–5.5).
+export { docsOutline } from "./core/read/outline.js";
+export { docsRead, reconstructContent } from "./core/read/document.js";
+export { nodesGet, nodesGetMany } from "./core/read/nodes.js";
+export { findDoc, loadDocBlocks, blockRaw, docsList, docsTree, normalizeTreePrefix, DOCS_LIST_DEFAULT_LIMIT, DOCS_TREE_DEFAULT_LIMIT, } from "./core/read/reader.js";
+export { CursorInvalid, encodeCursor, decodeCursor } from "./core/cursor.js";
+export { resolveRef } from "./core/read/refs.js";
+export { resolve } from "./search/resolve.js";
+// OQX — omgbase Query eXpressions (unified composable query language, slice 1:
+// structural navigation over docs/blocks/nodes). Coexists with query().
+export { oqxRun, oqxRunAsync, collectSemanticPhrases, parseOqx } from "./oqx/run.js";
+// Embeddings + semantic retrieval (05 §5–6). The provider is a plugin loaded by
+// package name; core carries no ML dependency.
+export { EmbeddingWorker, SemanticUnavailable, contextPrefix, shouldEmbed, estimateTokens, } from "./search/embeddings.js";
+export { buildEmbedTasks, buildDocEmbedTasks } from "./search/tasks.js";
+export { EmbedDrainer } from "./search/drain.js";
+export { embeddingSettings } from "./search/provider.js";
+export { createExternalProvider } from "./search/external.js";
+export { hybridSearch } from "./search/rrf.js";
+export { vectorSearch, docVectorSearch } from "./search/vector.js";
+export { historyNode, diffUnified, changesSince } from "./graph/history.js";
+export { docLinks } from "./graph/links.js";
+export { FilterInvalid } from "./search/cel/parser.js";
+export { EngineError } from "./mcp/errors.js";
+export { MutationError } from "./mutate/tree.js";
+export { isValidId, prefixOf } from "./core/ids.js";
+// Mutation surface consumed by CLI write commands (11 §5.6).
+export { apply } from "./mutate/apply.js";
+export { FsDocStore, NullDocStore, resolveDocStore } from "./mutate/doc-store.js";
+export {} from "./mutate/ops.js";
+export { tasksComplete, sectionsAppend, sectionsRename, sectionsMove, listsInsertItem, linksRetarget, nodeSet, editablePropsFor, } from "./mutate/macros.js";
+// Admin/maintenance (11 §5.9). Graph traversal is OQX `follow` now (see oqx/).
+export { docsCreate, docsMove, docsDelete, docsSetMeta, } from "./mutate/docs.js";
+// Inbound-link discovery + destination-aware rewrite (docs_move's dangling report / retarget_inbound).
+export { inboundLinksTo, retargetLinksInRaw } from "./graph/inbound-links.js";
+// Whole-document update: reconcile → opset → inspect/apply.
+export { planUpdate, applyOpset, docsUpdate, } from "./mutate/plan-update.js";
+export { opsetKernelOps, renderOpsetPlan, serializeOpset, parseOpset, } from "./mutate/opset.js";
+export { rebuildIndex } from "./core/store/rebuild.js";
+export { runGc } from "./core/store/gc.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,17 @@
+export type ErrorCode = "stale_expectation" | "parent_missing" | "target_missing" | "block_missing" | "doc_missing" | "cycle_move" | "opaque_block" | "not_contiguous" | "type_mismatch" | "conflicted_document" | "path_taken" | "create_conflict" | "ambiguous_locator" | "ambiguous_heading" | "filter_invalid" | "budget_exceeded" | "semantic_unavailable" | "embedder_failed" | "sync_conflict" | "repo_not_found" | "node_not_editable" | "seed_unresolved";
+export interface EngineErrorBody {
+    error: ErrorCode;
+    message: string;
+    data?: unknown;
+    retriable: boolean;
+}
+export declare class EngineError extends Error {
+    code: ErrorCode;
+    data: unknown;
+    retriable: boolean;
+    constructor(code: ErrorCode, message: string, opts?: {
+        data?: unknown;
+        retriable?: boolean;
+    });
+    body(): EngineErrorBody;
+}

package/dist/src/mcp/errors.js

@@ -0,0 +1,18 @@
+// Error codes (06 §5). Shape: { error, message, data?, retriable }. Codes are
+// stable; prose is free to improve. FilterInvalid from the query compiler maps
+// to filter_invalid with its reason/hint in data.
+export class EngineError extends Error {
+    code;
+    data;
+    retriable;
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.code = code;
+        this.data = opts.data;
+        this.retriable = opts.retriable ?? false;
+    }
+    body() {
+        return { error: this.code, message: this.message, data: this.data, retriable: this.retriable };
+    }
+}
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,63 @@
+import type { Store } from "../core/store/store.js";
+import { type EmbedQuery } from "../oqx/run.js";
+export type GraphDirection = "in" | "out" | "both";
+export interface GraphArgs {
+    /** one or more document refs — paths and/or ids. Root nodes are depth 0. */
+    roots: string[];
+    /** max hop depth from a root (root = 0). Default 1; clamped so degrees+1 ≤ 8. */
+    degrees?: number | undefined;
+    /** which edges to follow: outgoing links, backlinks, or both. Default "both". */
+    direction?: GraphDirection | undefined;
+    /** restrict the neighborhood to documents reachable from a root via edges of
+     * this predicate, within `degrees` (both the docs and the edges are filtered). */
+    predicate?: string | undefined;
+    /** extra document projections (OQX select expressions, e.g. "layer", "$path"). */
+    select?: string[] | undefined;
+    /** cap on the distinct documents returned (default 200). */
+    max_documents?: number | undefined;
+}
+/** A traversed edge with full provenance (mirrors the `edges` target's rows). */
+export interface GraphEdge {
+    id: string;
+    src: string;
+    dst: string;
+    dst_path: string | null;
+    dst_uri: string | null;
+    dst_kind: string;
+    predicate: string;
+    provenance: string;
+    anchor: string | null;
+    src_field: string | null;
+}
+/** A reached document: id/path + walk metadata + any requested projections. */
+export interface GraphDoc {
+    id: string;
+    path: string;
+    /** minimum hop distance from a root (root = 0). */
+    degree: number;
+    /** true when this node sits on the outer boundary (its min degree == degrees). */
+    frontier: boolean;
+    [k: string]: unknown;
+}
+export interface GraphResult {
+    roots: string[];
+    degrees: number;
+    direction: GraphDirection;
+    documents: GraphDoc[];
+    edges: GraphEdge[];
+    frontier: {
+        id: string;
+        path: string;
+        degree: number;
+    }[];
+    truncated: boolean;
+    /** the exact OQX `follow` query/queries this macro generated — it delegates. */
+    queries: string[];
+}
+/**
+ * Run the `graph` neighborhood macro: compile the args into OQX `follow`
+ * query(ies), execute via the shared runner, and shape the walk output into
+ * { documents, edges, frontier }. Throws EngineError (doc_missing/target_missing)
+ * for an empty or unresolvable roots list — never a silent empty result.
+ */
+export declare function graphNeighborhood(store: Store, repoId: string, args: GraphArgs, embedQuery?: EmbedQuery): Promise<GraphResult>;

package/dist/src/mcp/graph.js

@@ -0,0 +1,212 @@
+// `graph` — a one-call neighborhood macro OVER OQX `follow`.
+//
+// ADR-006: OQX `follow` is the ONE traversal engine; the removed
+// graph_traverse/path/subgraph tools are not resurrected. This macro owns NO
+// graph-walking logic — it compiles its arguments into an OQX `follow doc.out`
+// / `doc.in` query (the exact recursive-CTE walk the `query` tool exposes),
+// runs it through the shared runner (oqxRunAsync), and then only SHAPES the
+// walk's own output (its `$depth`/`$stop` intrinsics and projected edges) into
+// the { documents, edges, frontier } envelope. Every hop, cycle-guard and depth
+// bound is `follow`'s; nothing here re-implements BFS/DFS.
+//
+// Mapping (args → follow query):
+//   roots      → the seed `where $id == … || …` (refs resolved to doc ids first)
+//   degrees    → `follow … { depth degrees+1 }` (seed is $depth 1, so N hops = depth N+1)
+//   direction  → `follow doc.out` | `doc.in` | both (two walks, unioned)
+//   predicate  → restricts the neighborhood to docs reachable via that predicate
+//                (recomputed over the walk's collected edges; no `via` clause)
+//   select     → extra doc projections spliced into the walk's `select`
+//   max_documents → a post-walk cap on the distinct document set
+//
+// Edges are surfaced by projecting the reached doc's `doc.out_edges`/`doc.in_edges`
+// in the SAME walk (a select-position collect), then keeping the induced-subgraph
+// edges (both endpoints in the neighborhood) plus dangling stubs to external/
+// phantom targets — so external (`x_…`) and phantom endpoints are never dropped,
+// exactly as `from edges` surfaces them.
+import { findDocByRef } from "../core/read/reader.js";
+import { oqxRunAsync } from "../oqx/run.js";
+import { EngineError } from "./errors.js";
+const DEFAULT_DEGREES = 1;
+const DEFAULT_MAX_DOCUMENTS = 200;
+const MAX_DEPTH = 8; // OQX follow depth cap (1..8)
+// Build the extra `select` items for caller projections. Each expression gets a
+// stable internal alias (_u0, _u1, …) so it can never collide with a reserved
+// word or the macro's own aliases; the clean output name is derived separately.
+function buildUserSelect(select) {
+    if (!select || select.length === 0)
+        return { clause: "", outNames: [] };
+    const items = [];
+    const outNames = [];
+    const used = new Set();
+    select.forEach((expr, i) => {
+        const trimmed = expr.trim();
+        if (!trimmed)
+            return;
+        const m = /^\$?([A-Za-z_][A-Za-z0-9_]*)$/.exec(trimmed);
+        let name = m ? m[1] : `sel_${i}`;
+        while (used.has(name))
+            name = `${name}_${i}`;
+        used.add(name);
+        outNames[i] = name;
+        items.push(`_u${i}: ${trimmed}`);
+    });
+    return { clause: items.length ? `, ${items.join(", ")}` : "", outNames };
+}
+// The edge fields projected from doc.out_edges/doc.in_edges — identical for both
+// directions so a single filter handles either scan (an edge is a directional
+// src→dst fact regardless of which endpoint the walk reached it from).
+const EDGE_COLLECT = "{ id: $id, src: $src, dst: $dst, dst_path: $dst_path, dst_uri: $dst_uri, " +
+    "dst_kind: dst_kind, predicate: predicate, provenance: provenance, anchor: anchor, src_field: src_field }";
+function buildQuery(seed, dir, depth, userSelect) {
+    const edgesRel = dir === "out" ? "doc.out_edges" : "doc.in_edges";
+    return (`from docs where ${seed} ` +
+        `select _depth: $depth, _stop: $stop, _edges: ${edgesRel} collect ${EDGE_COLLECT}${userSelect} ` +
+        `follow distinct doc.${dir} { depth ${depth} }`);
+}
+/**
+ * Run the `graph` neighborhood macro: compile the args into OQX `follow`
+ * query(ies), execute via the shared runner, and shape the walk output into
+ * { documents, edges, frontier }. Throws EngineError (doc_missing/target_missing)
+ * for an empty or unresolvable roots list — never a silent empty result.
+ */
+export async function graphNeighborhood(store, repoId, args, embedQuery) {
+    if (!args.roots || args.roots.length === 0) {
+        throw new EngineError("target_missing", "graph requires at least one root (path or id)");
+    }
+    // Resolve every root ref to a concrete doc id up front — the seed is built
+    // from ids only, so no caller-supplied string is interpolated into the query.
+    const rootIds = [];
+    for (const ref of args.roots) {
+        const info = findDocByRef(store, repoId, ref);
+        if (!info)
+            throw new EngineError("doc_missing", `no document for ${JSON.stringify(ref)}`, { data: { root: ref } });
+        if (!rootIds.includes(info.docId))
+            rootIds.push(info.docId);
+    }
+    const degrees = Math.max(0, Math.floor(args.degrees ?? DEFAULT_DEGREES));
+    const depth = Math.min(MAX_DEPTH, degrees + 1); // seed = $depth 1 ⇒ N hops = depth N+1
+    const effectiveDegrees = depth - 1; // after the depth-cap clamp
+    const direction = args.direction ?? "both";
+    const maxDocuments = Math.max(1, Math.floor(args.max_documents ?? DEFAULT_MAX_DOCUMENTS));
+    const dirs = direction === "both" ? ["out", "in"] : [direction];
+    const seed = rootIds.map((id) => `$id == ${JSON.stringify(id)}`).join(" || ");
+    const { clause: userSelect, outNames } = buildUserSelect(args.select);
+    const queries = [];
+    const docMap = new Map();
+    const edgeMap = new Map();
+    let queryTruncated = false;
+    for (const dir of dirs) {
+        const q = buildQuery(seed, dir, depth, userSelect);
+        queries.push(q);
+        // Fetch one more than the cap to detect truncation of a single scan; `follow
+        // distinct` yields one row per reached node so the row count == node count.
+        const res = await oqxRunAsync(store, repoId, q, { limit: maxDocuments + 1 }, embedQuery);
+        if (res.truncated)
+            queryTruncated = true;
+        for (const hit of res.hits) {
+            const hopDepth = Number(hit._depth); // $depth: seed = 1
+            const degree = hopDepth - 1; // root = 0
+            const prev = docMap.get(hit.id);
+            if (!prev || degree < prev.degree) {
+                const doc = { id: hit.id, path: hit.path, degree, frontier: false };
+                outNames.forEach((name, i) => {
+                    if (name !== undefined)
+                        doc[name] = hit[`_u${i}`] ?? null;
+                });
+                docMap.set(hit.id, doc);
+            }
+            // Gather this node's edges; dedup by edge id (an a→b edge is reachable as
+            // a's out-edge AND b's in-edge in "both" mode).
+            const raw = hit._edges ?? [];
+            for (const e of raw)
+                if (!edgeMap.has(e.id))
+                    edgeMap.set(e.id, e);
+        }
+    }
+    // Predicate filter restricts the NEIGHBORHOOD, not just the edge list: a doc is
+    // in-neighborhood only if reachable from a root by edges of that predicate
+    // within `degrees`. The unrestricted walk already collected every edge in the
+    // wider neighborhood (and any predicate-P path of length ≤ degrees stays inside
+    // it, since each prefix is reachable at ≤ that depth), so we recompute
+    // reachability over the P-filtered edges rather than issuing more queries.
+    if (args.predicate) {
+        const P = args.predicate;
+        const adj = new Map();
+        const link = (from, to) => { (adj.get(from) ?? adj.set(from, []).get(from)).push(to); };
+        for (const e of edgeMap.values()) {
+            if (e.predicate !== P)
+                continue;
+            if (dirs.includes("out"))
+                link(e.src, e.dst); // forward
+            if (dirs.includes("in"))
+                link(e.dst, e.src); // backward
+        }
+        const depthOf = new Map(rootIds.map((id) => [id, 0]));
+        let wave = [...rootIds];
+        for (let lvl = 1; lvl <= effectiveDegrees && wave.length > 0; lvl++) {
+            const next = [];
+            for (const from of wave) {
+                for (const to of adj.get(from) ?? []) {
+                    // Only traverse to real reached documents (external/phantom targets stay
+                    // edge stubs, handled below — never in-neighborhood nodes).
+                    if (docMap.has(to) && !depthOf.has(to)) {
+                        depthOf.set(to, lvl);
+                        next.push(to);
+                    }
+                }
+            }
+            wave = next;
+        }
+        const restricted = new Map();
+        for (const [id, d] of depthOf) {
+            const orig = docMap.get(id);
+            if (orig)
+                restricted.set(id, { ...orig, degree: d });
+        }
+        docMap.clear();
+        for (const [id, d] of restricted)
+            docMap.set(id, d);
+    }
+    // Cap the distinct document set (nearest-first), then bound edges to it.
+    const allDocs = [...docMap.values()].sort((a, b) => a.degree - b.degree || a.path.localeCompare(b.path));
+    const capped = allDocs.length > maxDocuments;
+    const documents = allDocs.slice(0, maxDocuments);
+    const reached = new Set(documents.map((d) => d.id));
+    const truncated = queryTruncated || capped;
+    // Mark the outer boundary: a node whose MIN degree equals the requested reach
+    // was only ever touched at the edge of the walk (never expanded past). At
+    // degrees 0 the roots themselves are the boundary.
+    const frontier = [];
+    for (const d of documents) {
+        d.frontier = d.degree === effectiveDegrees;
+        if (d.frontier)
+            frontier.push({ id: d.id, path: d.path, degree: d.degree });
+    }
+    // Keep the induced-subgraph edges (both endpoints in the neighborhood) plus
+    // dangling stubs to external/phantom targets, so external (x_…) and phantom
+    // endpoints survive the way `from edges` surfaces them. A `predicate` filter
+    // keeps only that predicate's edges (the neighborhood was already restricted to
+    // predicate-reachable docs above).
+    const edges = [];
+    for (const e of edgeMap.values()) {
+        if (args.predicate && e.predicate !== args.predicate)
+            continue;
+        const srcIn = reached.has(e.src);
+        const dstDangling = e.dst_kind === "external" || (e.dst_kind === "document" && e.dst_path === null);
+        const dstIn = reached.has(e.dst) || dstDangling;
+        if (srcIn && dstIn)
+            edges.push(e);
+    }
+    edges.sort((a, b) => (a.src === b.src ? a.id.localeCompare(b.id) : a.src.localeCompare(b.src)));
+    return {
+        roots: rootIds,
+        degrees: effectiveDegrees,
+        direction,
+        documents,
+        edges,
+        frontier,
+        truncated,
+        queries,
+    };
+}
+//# sourceMappingURL=graph.js.map

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

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

package/dist/src/mcp/reference.js

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