@omgbase/core 0.15.0 → 0.21.0

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

@@ -16,8 +16,8 @@ export interface MutDoc {
     frontmatterRaw: string | null;
     children: MutBlock[];
 }
-/** The codes spec/mutate §8 lists (2.3 adds `conflicting_effects`, `unsupported_plan_version`, `plan_mismatch`); `filter_invalid` is the planner's shape error, spec/surface §4's envelope. */
-export type MutationErrorCode = "stale_expectation" | "block_missing" | "target_missing" | "parent_missing" | "doc_missing" | "cycle_move" | "not_contiguous" | "type_mismatch" | "path_taken" | "node_not_editable" | "stale_plan" | "plan_not_convergent" | "sync_conflict" | "conflicting_effects" | "unsupported_plan_version" | "plan_mismatch" | "filter_invalid";
+/** The codes spec/mutate §8 lists (2.3 adds `conflicting_effects`, `unsupported_plan_version`, `plan_mismatch`; 3.1 `ambiguous_target`, `selection_too_large` — §11.8); `filter_invalid` is the planner's shape error, spec/surface §4's envelope. */
+export type MutationErrorCode = "stale_expectation" | "block_missing" | "target_missing" | "parent_missing" | "doc_missing" | "cycle_move" | "not_contiguous" | "type_mismatch" | "path_taken" | "node_not_editable" | "stale_plan" | "plan_not_convergent" | "sync_conflict" | "conflicting_effects" | "unsupported_plan_version" | "plan_mismatch" | "ambiguous_target" | "selection_too_large" | "filter_invalid";
 export declare class MutationError extends Error {
     code: MutationErrorCode | string;
     data: Record<string, unknown>;

package/dist/src/oqx-js/context.d.ts

@@ -1,11 +1,18 @@
 import type { DataContext } from "@omgbase/oqx";
+import { type Root } from "./root-row.js";
 import type { Store } from "../core/store/store.js";
 import type { SemanticVec } from "../search/cel/compile.js";
 export type Target = "docs" | "blocks" | "nodes" | "links";
+/** Every row kind the context tags (spec/surface §1.1): the four targets and
+ * `revisions` (4.7) — the history target, whose rows are the `revisions` ×
+ * `commits` join. `Target` stays the four kinds the unknown-names pass judges
+ * (names.ts keys its tables by it); everything that tags, scans or renders a
+ * row is keyed by `Kind`. */
+export type Kind = Root;
 declare const TARGET: unique symbol;
 /** The engine attributes per kind (spec/surface §1.2 table). Exported so the
  * translator's tests pin the two against each other. */
-export declare const ATTRIBUTES: Readonly<Record<Target, ReadonlySet<string>>>;
+export declare const ATTRIBUTES: Readonly<Record<Kind, ReadonlySet<string>>>;
 /** The source handles of a document (§1.2): `data` is the merged authored view
  * (frontmatter + inline), the other two one source each. */
 export declare const SOURCE_HANDLES: ReadonlySet<string>;
@@ -31,7 +38,7 @@ export interface StoreContextOptions {
 export declare function makeStoreContext(store: Store, repoId: string, opts?: StoreContextOptions): DataContext;
 /** Tag SQL rows with their target so the store context resolves them (used by the
  * tier-3 planner to hand produced rows back for residual evaluation). */
-export declare function tagRows(rows: Record<string, unknown>[], target: Target): unknown[];
+export declare function tagRows(rows: Record<string, unknown>[], target: Kind): unknown[];
 /**
  * A store row surfacing as a VALUE in a result (spec/surface §1.4, rows as
  * values, 1.2) is rendered as `{ id, path }` (3.0) — its id column and its

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

@@ -13,7 +13,7 @@
 // pushes the hot predicates down; both must agree (conformance suite).
 import { semantics } from "@omgbase/oqx";
 import { storeIndexFor } from "./store-index.js";
-import { TARGETS, bareTargetMessage } from "./root-row.js";
+import { ROOTS, ROOT_NAMES, bareTargetMessage } from "./root-row.js";
 import { COLS, FROM, ORDER, guards } from "./sql/scan.js";
 import { detectRange } from "../core/store/properties.js";
 import { docsRead } from "../core/read/document.js";
@@ -57,15 +57,29 @@ function tagAll(rows, t) {
 // `hash`/`raw` is simply the engine's attribute (before this batch of 3.0 the
 // attributes were `$`-prefixed and the bare spelling was an error, §9). A bare
 // target name — `docs`, `links`, … — is a loud error of its own (root-row.ts).
+// `revisions` on a document is a RELATION (its revision list, §1.2, 4.7) in
+// `rel.docs` below, and names.ts's `RELATIONS.docs` knows it as one.
 const DOC_ATTRIBUTES = new Set(["id", "path", "raw", "hash", "updated_at", "title", "tags", "format"]);
 const BLOCK_ATTRIBUTES = new Set(["id", "path", "raw", "hash", "updated_at", "doc_id", "type", "text", "attrs", "depth", "ordinal"]);
 const NODE_ATTRIBUTES = new Set(["id", "path", "doc_id", "block_id", "kind", "name", "value", "attrs"]);
 const EDGE_ATTRIBUTES = new Set(["id", "path", "doc_id", "block_id", "via_id", "dst_id", "dst_path", "uri", "field", "dst_kind", "predicate", "provenance", "anchor"]);
+// The history target (spec/surface §1.2, 4.7): a revision row's own columns
+// under the names `docs_history` already uses (`rev`, `seq`, `commit`, `origin`,
+// `actor`, `hash`), the commit's `ts` and `reason`, and `is_current`.
+const REVISION_ATTRIBUTES = new Set(["id", "path", "rev", "seq", "doc_id", "commit", "ts", "origin", "actor", "reason", "hash", "is_current"]);
 /** The engine attributes per kind (spec/surface §1.2 table). Exported so the
  * translator's tests pin the two against each other. */
 export const ATTRIBUTES = {
-    docs: DOC_ATTRIBUTES, blocks: BLOCK_ATTRIBUTES, nodes: NODE_ATTRIBUTES, links: EDGE_ATTRIBUTES,
+    docs: DOC_ATTRIBUTES, blocks: BLOCK_ATTRIBUTES, nodes: NODE_ATTRIBUTES, links: EDGE_ATTRIBUTES, revisions: REVISION_ATTRIBUTES,
 };
+// The revisions scan (spec/surface §1.1, 4.7): every revision of every document
+// of the repository — tombstoned documents included, history is history — with
+// its commit, in the keyset order `(path as of the revision, rev_id)`. The
+// `revisions` table carries no `repo_id`, so the repository guard joins `docs`.
+// `is_current` is `docs_history`'s `isCurrent`: the revision is the document's
+// `current_rev`.
+const REVISION_COLS = "r.rev_id, r.doc_id, r.seq, r.rendered_hash, r.path, r.commit_id, c.ts, c.origin, c.actor, c.reason, (d.current_rev = r.rev_id) AS is_current";
+const REVISION_FROM = "revisions r JOIN docs d ON d.doc_id = r.doc_id JOIN commits c ON c.commit_id = r.commit_id";
 /** The source handles of a document (§1.2): `data` is the merged authored view
  * (frontmatter + inline), the other two one source each. */
 export const SOURCE_HANDLES = new Set(["data", "frontmatter", "inline"]);
@@ -87,11 +101,17 @@ export function makeStoreContext(store, repoId, opts = {}) {
         return Object.values(r)[0];
     };
     // ---- root collections (the shared scan shape of sql/scan.ts: live rows of
-    // this repo, ordered for a stable (path, id) default) -----------------------
+    // this repo, ordered for a stable (path, id) default; the revisions scan is
+    // its own statement above, in the same (path, id) keyset order) -------------
     const scan = (t) => {
+        if (t === "revisions")
+            return tagAll(all(`SELECT ${REVISION_COLS} FROM ${REVISION_FROM} WHERE d.repo_id = ? ORDER BY r.path, r.rev_id`, repoId), t);
         const g = guards(t, repoId);
         return tagAll(all(`SELECT ${COLS[t]} FROM ${FROM[t]} WHERE ${g.sql} ORDER BY ${ORDER[t]}`, ...g.params), t);
     };
+    // A document's revisions (the `revisions` relation of a docs row, §1.2, 4.7):
+    // oldest first, as `docs_history` lists them.
+    const docRevisions = (docId) => tagAll(all(`SELECT ${REVISION_COLS} FROM ${REVISION_FROM} WHERE r.doc_id = ? ORDER BY r.seq`, docId), "revisions");
     // A root scan is handed out LAZILY: an array (a `Proxy` over one — `Array.isArray`,
     // iteration, indexing, `length`, rendering all see a plain array of tagged
     // rows) that runs its SELECT on first use. The engine's optimizer asks
@@ -138,21 +158,14 @@ export function makeStoreContext(store, repoId, opts = {}) {
         rootScans.set(proxy, { target: t, rows: fill });
         return proxy;
     };
-    const rootFns = {
-        docs: () => lazyRoot("docs"), blocks: () => lazyRoot("blocks"), nodes: () => lazyRoot("nodes"), links: () => lazyRoot("links"),
-    };
+    const rootFns = Object.fromEntries(ROOT_NAMES.map((t) => [t, () => lazyRoot(t)]));
     // The root row (spec/surface §1.1, 2.0; spec/oqx 0.18 `rootObject`): the
     // repository, reached as `^$it` from a top-level row (`0^$it` from any depth).
-    // Its own enumerable keys are the four collections — lazy getters, so
-    // `entries(^$it)` names them without running a scan and `^$it.docs` is the
-    // same handle as `^docs` — and `get` answers `id` with the repository id (an
-    // attribute, not an entry). Tagged so `get` recognizes it.
-    const rootRow = Object.defineProperties({ [ROOT_ROW]: true }, {
-        docs: { enumerable: true, get: () => lazyRoot("docs") },
-        blocks: { enumerable: true, get: () => lazyRoot("blocks") },
-        nodes: { enumerable: true, get: () => lazyRoot("nodes") },
-        links: { enumerable: true, get: () => lazyRoot("links") },
-    });
+    // Its own enumerable keys are the five collections in `ROOT_NAMES` order —
+    // lazy getters, so `entries(^$it)` names them without running a scan and
+    // `^$it.docs` is the same handle as `^docs` — and `get` answers `id` with the
+    // repository id (an attribute, not an entry). Tagged so `get` recognizes it.
+    const rootRow = Object.defineProperties({ [ROOT_ROW]: true }, Object.fromEntries(ROOT_NAMES.map((t) => [t, { enumerable: true, get: () => lazyRoot(t) }])));
     // ---- attrs / property decoding --------------------------------------------
     const parseJson = (v) => {
         if (typeof v !== "string")
@@ -298,6 +311,8 @@ export function makeStoreContext(store, repoId, opts = {}) {
         docs: {
             nodes: (r) => docNodesInOrder(r.doc_id, r.path),
             blocks: (r) => tagAll(docBlocksPreorder(r.doc_id, r.path).map((x) => x.row), "blocks"),
+            // A document's revision list (spec/surface §1.2, 4.7), oldest first.
+            revisions: (r) => docRevisions(r.doc_id),
             // The linked / linking DOCUMENTS are reached through the link rows (3.0
             // follow-up, §9: the `out` / `in` relations are gone): `out_links collect
             // distinct { from dst }` and `in_links collect distinct { from doc }`.
@@ -351,6 +366,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
             },
         },
         links: {},
+        revisions: {},
     };
     const jattr = (row, k) => {
         const a = row.attrs;
@@ -417,6 +433,11 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return undefined;
         return tag(one(`SELECT * FROM docs WHERE doc_id = ?`, row.dst_node), "docs");
     };
+    // `doc` on a revision row (spec/surface §1.2, 4.7): the document's CURRENT
+    // live row — the revision's `path` may be an earlier one — and absent (the
+    // single-with-no-row marker, as `dst` on a dangling link) for a tombstoned
+    // document: its revisions are rows, `doc == null` tells them apart.
+    const revisionDoc = (row) => tag(one(`SELECT * FROM docs WHERE doc_id = ? AND deleted_commit IS NULL`, row.doc_id), "docs");
     const owningBlock = (row) => {
         if (!row.block_id)
             return undefined;
@@ -501,6 +522,22 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 case "dst_kind":
                 case "anchor": return row[name];
             }
+        if (t === "revisions")
+            switch (name) {
+                // the `revisions` × `commits` columns under docs_history's names (spec/surface §1.2, 4.7).
+                case "id":
+                case "rev": return row.rev_id;
+                case "path": return referencePath(String(row.path));
+                case "seq": return row.seq;
+                case "doc_id": return row.doc_id;
+                case "commit": return row.commit_id;
+                case "ts": return row.ts;
+                case "origin": return row.origin;
+                case "actor": return row.actor ?? null;
+                case "reason": return row.reason ?? null;
+                case "hash": return hex(row.rendered_hash);
+                case "is_current": return row.is_current === 1 || row.is_current === true;
+            }
         return undefined;
     };
     // `tags` on a document: authored ∪ hashtags, each list as the property rule
@@ -561,8 +598,11 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return r;
         if (t === "nodes" && key === "section")
             return r;
-        // reach-through to owning entities, and from a link row to its destination —
-        // statically single relations: absent is the single-with-no-row marker.
+        // reach-through to owning entities, from a link row to its destination and
+        // from a revision to its document's current row — statically single
+        // relations: absent is the single-with-no-row marker.
+        if (t === "revisions" && key === "doc")
+            return revisionDoc(r) ?? ABSENT_SINGLE;
         if (t !== "docs" && key === "doc")
             return owningDoc(r) ?? ABSENT_SINGLE;
         if (t === "nodes" && key === "block")
@@ -576,9 +616,9 @@ export function makeStoreContext(store, repoId, opts = {}) {
         // A bare target name that is not one of this row's relations reads a
         // property the row has none of (spec/surface §1.1, 2.0): loud, naming the
         // root-row spelling. `docs`/`links` never get here (run.ts refuses them
-        // statically); `blocks` on a block or edge row and `nodes` on a node or
-        // edge row do.
-        if (TARGETS.has(key))
+        // statically); `blocks` on a block or edge row, `nodes` on a node or edge
+        // row and `revisions` on anything but a document do.
+        if (ROOTS.has(key))
             throw new FilterInvalid(bareTargetMessage(key, null), "OQX");
         // the author's data.
         if (t === "docs") {
@@ -652,8 +692,8 @@ export function makeStoreContext(store, repoId, opts = {}) {
         }
     };
     const textMatch = (t, r, terms) => {
-        if (t === "links")
-            throw new FilterInvalid("text(...) is not available on the links target", "10 §5");
+        if (t === "links" || t === "revisions")
+            throw new FilterInvalid(`text(...) is not available on the ${t} target`, "10 §5");
         const match = sanitizeFtsQuery(terms);
         if (match === "")
             return false;
@@ -676,7 +716,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
         return one(`SELECT vec FROM embeddings WHERE content_hash = ? AND ctx_hash = ? AND model = ?`, r.raw_hash, Buffer.from(ctxHashHex(ctx), "hex"), model);
     };
     const semanticScore = (t, r, phrase) => {
-        if (t === "nodes" || t === "links")
+        if (t === "nodes" || t === "links" || t === "revisions")
             throw new FilterInvalid("semantic(...) is available on the docs and blocks targets", "OQX semantic");
         const resolved = sv?.get(phrase);
         if (!resolved)
@@ -771,10 +811,12 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return row.node_id;
         if (t === "links")
             return row.edge_id;
+        if (t === "revisions")
+            return row.rev_id;
         return row;
     };
     return {
-        // The root scope's names (spec/oqx §2 step 5 at the root): the four lazy
+        // The root scope's names (spec/oqx §2 step 5 at the root): the five lazy
         // scans and `id`, the repository id — so `^docs` / `0^docs` from any row is
         // the scan and `^id` / `0^id` the id.
         root(name) {
@@ -817,7 +859,9 @@ export function makeStoreContext(store, repoId, opts = {}) {
             if (collection === null || typeof collection !== "object")
                 return undefined;
             const root = rootScans.get(collection);
-            if (!root)
+            // The revisions scan has no store index (4.7): the engine builds its own
+            // over the materialized rows (one SELECT per context).
+            if (!root || root.target === "revisions")
                 return undefined;
             const key = `${root.target}\u0000${JSON.stringify(path)}`;
             let index = indexes.get(key);
@@ -891,8 +935,10 @@ export function rowRef(value) {
     if (!t)
         return undefined;
     const r = value;
-    const id = t === "docs" ? r.doc_id : t === "blocks" ? r.block_id : t === "nodes" ? r.node_id : r.edge_id;
-    const path = t === "docs" ? r.path : r.__path;
+    const id = t === "docs" ? r.doc_id : t === "blocks" ? r.block_id : t === "nodes" ? r.node_id : t === "revisions" ? r.rev_id : r.edge_id;
+    // a revision's path is `revisions.path` — the path it was committed under
+    // (a move re-paths the current revision; §1.2, 4.7).
+    const path = t === "docs" || t === "revisions" ? r.path : r.__path;
     return { id: String(id), path: path == null ? "" : referencePath(String(path)) };
 }
 export { TARGET };

package/dist/src/oqx-js/names.d.ts

@@ -0,0 +1,40 @@
+import type { Query, ReferenceStep } from "@omgbase/oqx";
+import { type Kind } from "./context.js";
+import type { Store } from "../core/store/store.js";
+/** What to do with a tier-3 name on an open kind: record it in `hints` (every read) or refuse the query (a write selector). */
+export type UnknownNames = "hint" | "refuse";
+/** The relations of each kind and the kind of the rows they yield (spec/surface §1.2). */
+export declare const RELATIONS: Readonly<Record<Kind, Readonly<Record<string, Kind>>>>;
+/** The self and reach-through handles of each kind and the kind of the row they reach (§1.2). */
+export declare const HANDLES: Readonly<Record<Kind, Readonly<Record<string, Kind>>>>;
+/** The vocabulary of a kind in a repository (cached on the head commit; the SQL runs only when a name is not intrinsic). */
+export declare function vocabulary(store: Store, repoId: string, target: Kind): {
+    present: boolean;
+    keys: readonly string[];
+};
+/** The kind of the rows a scope holds, from its row chain (AST.md §5b); null when the chain reaches a value no kind describes. */
+export declare function kindOfScope(steps: readonly ReferenceStep[]): Kind | null;
+/** Optimal string alignment distance (Damerau–Levenshtein with adjacent transpositions, each edit 1). */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * The nearest match of `name` among `candidates` (§1.5): case-insensitive; a
+ * candidate qualifies when its distance is ≤ 2, or when one of the two is a
+ * substring of the other and the shorter has at least three characters; the
+ * lowest distance wins, ties broken by the shorter candidate, then
+ * alphabetically. Null when nothing qualifies.
+ */
+export declare function nearest(name: string, candidates: readonly string[]): string | null;
+/** The error of a closed kind: `` `target` is not a field of links (fields: id, path, …); did you mean `…`? ``. */
+export declare function fieldErrorMessage(store: Store, repoId: string, target: Kind, name: string): string;
+/** The hint of an open kind: `` `preview` is not a field of blocks and no block in this repository carries a property by that name; did you mean `…`? ``.
+ * Under a source handle the name is an authored lookup by construction, so the
+ * hint says only that: `` no document in this repository carries a property `path` (`data.path`); did you mean `…`? ``,
+ * the nearest match drawn from the authored keys alone. */
+export declare function propertyHintMessage(store: Store, repoId: string, target: Kind, name: string, handle?: string): string;
+/**
+ * Judge every name the query reads. Returns the hints (one per offending name
+ * of an open kind, first-reference order, deduplicated) under `"hint"`; throws
+ * `FilterInvalid` for a tier-3 name on a closed kind in either mode, and for
+ * one on an open kind under `"refuse"`.
+ */
+export declare function checkNames(store: Store, repoId: string, raw: Query, mode: UnknownNames): string[];

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

@@ -0,0 +1,347 @@
+// Unknown names (spec/surface §1.5, 4.6). A query that projects, filters or
+// orders by a name no row of the scope's kind can carry — `select path, target
+// from links` (links have `dst_path`), `where preview != ""` on blocks — used
+// to run silently: an absent column in every row, a predicate true or false of
+// every row. This pass judges every name the query reads (`@omgbase/oqx`'s
+// `references`, AST.md §5b) against the VOCABULARY of the row kind it is read
+// from, statically — before any row is read, so the verdict never depends on
+// the query's own filter — and either records a hint or refuses the query.
+//
+// The three tiers of a name at a scope whose kind is known:
+//   1. an engine attribute, handle or relation of the kind — known;
+//   2. an authored property at least one live object of the kind in this
+//      repository carries (docs: a frontmatter or inline key — `stage` on three
+//      processes is enough; blocks and nodes: a key of a live row's `attrs`,
+//      the bare-name read of those kinds) — known, however partial;
+//   3. a name no object of the kind carries — the complaint.
+// Severity: `links` has a closed row shape (no authored data reaches a link
+// row), so a tier-3 name there is `filter_invalid`; docs, blocks and nodes are
+// open — on a read the result carries one hint per offending name and the rows
+// still come back; a write selector (the AST entry, `unknownNames: "refuse"`)
+// is refused, since a name no row carries would select every row. A repository
+// with no live object of the kind has no vocabulary: the check is skipped for
+// that kind. The vocabulary is read once per (repository, kind) and cached on
+// the repository's head commit (`MAX(commits.seq)`), the one thing every
+// property or attrs change moves.
+import { references } from "@omgbase/oqx";
+import { ATTRIBUTES, SOURCE_HANDLES } from "./context.js";
+import { ROOTS } from "./root-row.js";
+import { FROM, guards } from "./sql/scan.js";
+import { FilterInvalid } from "../search/cel/parser.js";
+/** The relations of each kind and the kind of the rows they yield (spec/surface §1.2). */
+export const RELATIONS = {
+    docs: { blocks: "blocks", nodes: "nodes", out_links: "links", in_links: "links", revisions: "revisions" },
+    blocks: { children: "blocks", nodes: "nodes", out_links: "links", section: "nodes" },
+    nodes: { blocks: "blocks", subsections: "nodes", children: "nodes" },
+    links: {},
+    revisions: {},
+};
+/** The self and reach-through handles of each kind and the kind of the row they reach (§1.2). */
+export const HANDLES = {
+    docs: { doc: "docs" },
+    blocks: { block: "blocks", doc: "docs" },
+    nodes: { section: "nodes", doc: "docs", block: "blocks" },
+    links: { doc: "docs", dst: "docs" },
+    revisions: { doc: "docs" },
+};
+/** The kinds whose row shape is closed: no authored data reaches a row by bare name. */
+const CLOSED = new Set(["links", "revisions"]);
+const NOUN = { docs: "document", blocks: "block", nodes: "node", links: "link", revisions: "revision" };
+const CACHE = new WeakMap();
+function headSeq(store, repoId) {
+    const row = store.db.prepare("SELECT COALESCE(MAX(seq), 0) AS seq FROM commits WHERE repo_id = ?").get(repoId);
+    return row?.seq ?? 0;
+}
+function repoCache(store, repoId) {
+    let repos = CACHE.get(store);
+    if (!repos)
+        CACHE.set(store, (repos = new Map()));
+    const head = headSeq(store, repoId);
+    let c = repos.get(repoId);
+    if (!c || c.head !== head)
+        repos.set(repoId, (c = { head, vocab: {} }));
+    return c;
+}
+/** The authored vocabulary of a kind: docs — every live frontmatter or inline
+ * key (the merged read a bare name performs); blocks and nodes — every key a
+ * live row's `attrs` holds (the bare-name read of those kinds). Computed keys
+ * (`$title`, `$tags`) are the intrinsics `title`/`tags`, not authored keys. */
+function authoredKeys(store, repoId, target) {
+    let sql;
+    switch (target) {
+        case "docs":
+            sql = "SELECT DISTINCT key FROM properties WHERE repo_id = ? AND deleted_commit IS NULL AND source IN ('frontmatter', 'inline') ORDER BY key";
+            return store.db.prepare(sql).all(repoId).map((r) => r.key);
+        case "blocks":
+        case "nodes": {
+            const g = guards(target, repoId);
+            const alias = target === "blocks" ? "b" : "n";
+            sql = `SELECT DISTINCT j.key AS key FROM ${FROM[target]}, json_each(${alias}.attrs) j WHERE ${g.sql} ORDER BY key`;
+            return store.db.prepare(sql).all(...g.params).map((r) => r.key);
+        }
+        case "links":
+        case "revisions": return [];
+    }
+}
+function present(store, repoId, target) {
+    // A closed kind has no authored vocabulary to be absent; the question never reaches it.
+    if (target === "revisions")
+        return true;
+    const g = guards(target, repoId);
+    return store.db.prepare(`SELECT 1 FROM ${FROM[target]} WHERE ${g.sql} LIMIT 1`).get(...g.params) !== undefined;
+}
+/** The vocabulary of a kind in a repository (cached on the head commit; the SQL runs only when a name is not intrinsic). */
+export function vocabulary(store, repoId, target) {
+    const v = vocabularyOf(store, repoId, target);
+    return { present: v.present, keys: v.list };
+}
+function vocabularyOf(store, repoId, target) {
+    const c = repoCache(store, repoId);
+    let v = c.vocab[target];
+    if (v)
+        return v;
+    const list = authoredKeys(store, repoId, target);
+    const keys = new Set();
+    for (const k of list) {
+        const segs = k.split(".");
+        for (let i = 1; i <= segs.length; i++)
+            keys.add(segs.slice(0, i).join("."));
+    }
+    v = { present: list.length > 0 || present(store, repoId, target), keys, list };
+    c.vocab[target] = v;
+    return v;
+}
+/** The kind of the rows an expression yields when read on rows of `on` (`"root"`: the root scope), or null when unknown. */
+function kindOfExpr(e, on, readDepth, byDepth) {
+    switch (e.kind) {
+        case "ident": return kindOfPath(on, [e.name]);
+        case "outer": {
+            const k = readDepth - e.levels;
+            return kindOfPath(k <= 0 ? "root" : byDepth.get(k) ?? null, [e.name]);
+        }
+        case "member": {
+            const path = dotted(e);
+            if (path === null)
+                return null;
+            const head = path.head;
+            const base = head.kind === "ident" ? on : (readDepth - head.levels <= 0 ? "root" : byDepth.get(readDepth - head.levels) ?? null);
+            return kindOfPath(base, [head.name, ...path.rest]);
+        }
+        // `refs(x)` resolves document references to live document rows (§1.3).
+        case "call": return e.recv === null && e.name === "refs" ? "docs" : null;
+        // A value-position block with no projection passes its receiver's rows through (then its own `from`).
+        case "op": {
+            if (e.sub.select.some((it) => it.name !== "$key") || e.sub.values)
+                return null;
+            let k = kindOfExpr(e.receiver, on, readDepth, byDepth);
+            for (const f of e.sub.from)
+                k = k === null ? null : kindOfExpr(f, k, readDepth + 1, byDepth);
+            return k;
+        }
+        default: return null; // a literal, a binding, a tuple (mixed), a template, an operator
+    }
+}
+/** A dotted navigation headed by a name. */
+function dotted(e) {
+    if (e.kind === "ident" || e.kind === "outer")
+        return { head: e, rest: [] };
+    if (e.kind !== "member")
+        return null;
+    const inner = dotted(e.recv);
+    return inner === null ? null : { head: inner.head, rest: [...inner.rest, e.name] };
+}
+/** Follow a dotted path from a row kind through handles and relations (`doc.blocks` on a link → blocks). */
+function kindOfPath(on, path) {
+    let cur = on;
+    for (let i = 0; i < path.length; i++) {
+        const seg = path[i];
+        if (cur === null)
+            return null;
+        if (cur === "root") {
+            if (seg === "$it")
+                continue;
+            if (!ROOTS.has(seg))
+                return null;
+            cur = seg;
+            continue;
+        }
+        if (seg === "$it" && i === 0)
+            continue;
+        const next = HANDLES[cur][seg] ?? RELATIONS[cur][seg];
+        if (next === undefined)
+            return null;
+        cur = next;
+    }
+    return cur === "root" ? null : cur;
+}
+/** The kind of the frontier rows of a walk: the seeds' kind when every destination yields rows of that same kind, else unknown. */
+function kindOfFrontier(seed, f, readDepth, byDepth) {
+    if (seed === null)
+        return null;
+    // A destination block is a value-position `op`: its receiver on the frontier row, then its own `from`.
+    for (const d of f.destinations)
+        if (kindOfExpr(d, seed, readDepth, byDepth) !== seed)
+            return null;
+    return seed;
+}
+/** The kind of the rows a scope holds, from its row chain (AST.md §5b); null when the chain reaches a value no kind describes. */
+export function kindOfScope(steps) {
+    if (steps.length === 0)
+        return null; // the root scope: root names are judged elsewhere
+    const byDepth = new Map([[0, "root"]]);
+    let cur = "root";
+    let readDepth = 0;
+    for (const step of steps) {
+        const e = step.expr;
+        if (e.kind === "follow")
+            cur = kindOfFrontier(cur === "root" ? null : cur, e, readDepth, byDepth);
+        else
+            cur = kindOfExpr(e, cur, readDepth, byDepth);
+        byDepth.set(step.depth, cur);
+        readDepth = step.depth;
+    }
+    return cur === "root" ? null : cur;
+}
+/** Judge a dotted name read on rows of `target`; null = known. */
+function judge(store, repoId, target, path) {
+    const [head, ...rest] = path;
+    // An engine attribute wins on collision; what follows it (`attrs.checked`, `tags.size`) is the value's own navigation.
+    if (ATTRIBUTES[target].has(head))
+        return null;
+    // The source handles reach the authored data under them.
+    if (target === "docs" && SOURCE_HANDLES.has(head))
+        return rest.length === 0 ? null : judgeAuthored(store, repoId, "docs", rest, head);
+    const via = HANDLES[target][head] ?? RELATIONS[target][head];
+    if (via !== undefined)
+        return rest.length === 0 ? null : judge(store, repoId, via, rest);
+    // A bare target name on a row is the context's own loud error (root-row.ts); not doubled here.
+    if (ROOTS.has(head))
+        return null;
+    return judgeAuthored(store, repoId, target, path);
+}
+function judgeAuthored(store, repoId, target, path, handle) {
+    const name = path.join(".");
+    if (CLOSED.has(target))
+        return { target, name, closed: true };
+    const v = vocabularyOf(store, repoId, target);
+    if (!v.present)
+        return null; // no object of the kind: no vocabulary to judge by
+    if (v.keys.has(name))
+        return null;
+    return { target, name, closed: false, ...(handle !== undefined ? { handle } : {}) };
+}
+// ---- messages --------------------------------------------------------------
+/** The names a kind knows, for the nearest match: attributes, handles, relations, the authored keys. */
+function candidates(store, repoId, target) {
+    const out = [...ATTRIBUTES[target], ...Object.keys(HANDLES[target]), ...(target === "docs" ? [...SOURCE_HANDLES] : []), ...Object.keys(RELATIONS[target])];
+    if (!CLOSED.has(target))
+        out.push(...vocabularyOf(store, repoId, target).list);
+    return out;
+}
+/** Optimal string alignment distance (Damerau–Levenshtein with adjacent transpositions, each edit 1). */
+export function editDistance(a, b) {
+    const s = Array.from(a), t = Array.from(b);
+    const m = s.length, n = t.length;
+    const d = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        d[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = s[i - 1] === t[j - 1] ? 0 : 1;
+            let v = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && s[i - 1] === t[j - 2] && s[i - 2] === t[j - 1])
+                v = Math.min(v, d[i - 2][j - 2] + 1);
+            d[i][j] = v;
+        }
+    }
+    return d[m][n];
+}
+/**
+ * The nearest match of `name` among `candidates` (§1.5): case-insensitive; a
+ * candidate qualifies when its distance is ≤ 2, or when one of the two is a
+ * substring of the other and the shorter has at least three characters; the
+ * lowest distance wins, ties broken by the shorter candidate, then
+ * alphabetically. Null when nothing qualifies.
+ */
+export function nearest(name, candidates) {
+    const needle = name.toLowerCase();
+    // A name under three characters is within distance 2 of nearly anything, so
+    // only a substring match (which needs three characters anyway) could qualify.
+    if (needle.length < 3)
+        return null;
+    let best = null;
+    for (const c of new Set(candidates)) {
+        const hay = c.toLowerCase();
+        if (hay === needle)
+            continue;
+        const d = editDistance(needle, hay);
+        const shorter = needle.length <= hay.length ? needle : hay;
+        const longer = shorter === needle ? hay : needle;
+        const sub = shorter.length >= 3 && longer.includes(shorter);
+        if (!(d <= 2 || sub))
+            continue;
+        // One typo (distance 1) wins first; then a substring match outranks a
+        // distance-2 match (`via` → `via_id`, not `id`; `dst_pth` → `dst_path`, not
+        // `dst`); within a class the lowest distance, then the shorter candidate,
+        // then alphabetical.
+        const rank = (x) => (x.d === 1 ? 0 : x.sub ? 1 : 2);
+        const better = best === null ||
+            rank({ d, sub }) < rank(best) ||
+            (rank({ d, sub }) === rank(best) && (d < best.d || (d === best.d && (c.length < best.c.length || (c.length === best.c.length && c < best.c)))));
+        if (better)
+            best = { c, d, sub };
+    }
+    return best === null ? null : best.c;
+}
+function suggestion(name, candidates) {
+    const c = nearest(name, candidates);
+    return c === null ? "" : `; did you mean \`${c}\`?`;
+}
+/** The error of a closed kind: `` `target` is not a field of links (fields: id, path, …); did you mean `…`? ``. */
+export function fieldErrorMessage(store, repoId, target, name) {
+    return `\`${name}\` is not a field of ${target} (fields: ${[...ATTRIBUTES[target]].join(", ")})${suggestion(name, candidates(store, repoId, target))}`;
+}
+/** The hint of an open kind: `` `preview` is not a field of blocks and no block in this repository carries a property by that name; did you mean `…`? ``.
+ * Under a source handle the name is an authored lookup by construction, so the
+ * hint says only that: `` no document in this repository carries a property `path` (`data.path`); did you mean `…`? ``,
+ * the nearest match drawn from the authored keys alone. */
+export function propertyHintMessage(store, repoId, target, name, handle) {
+    if (handle !== undefined) {
+        return `no ${NOUN[target]} in this repository carries a property \`${name}\` (\`${handle}.${name}\`)${suggestion(name, vocabularyOf(store, repoId, target).list)}`;
+    }
+    return `\`${name}\` is not a field of ${target} and no ${NOUN[target]} in this repository carries a property by that name${suggestion(name, candidates(store, repoId, target))}`;
+}
+// ---- the pass --------------------------------------------------------------
+/**
+ * Judge every name the query reads. Returns the hints (one per offending name
+ * of an open kind, first-reference order, deduplicated) under `"hint"`; throws
+ * `FilterInvalid` for a tier-3 name on a closed kind in either mode, and for
+ * one on an open kind under `"refuse"`.
+ */
+export function checkNames(store, repoId, raw, mode) {
+    const hints = [];
+    const seen = new Set();
+    for (const ref of references(raw)) {
+        if (ref.scope.steps.length === 0)
+            continue; // a root name
+        const kind = kindOfScope(ref.scope.steps);
+        if (kind === null)
+            continue;
+        const verdict = judge(store, repoId, kind, ref.name.split("."));
+        if (verdict === null)
+            continue;
+        if (verdict.closed)
+            throw new FilterInvalid(fieldErrorMessage(store, repoId, verdict.target, verdict.name), "OQX");
+        const message = propertyHintMessage(store, repoId, verdict.target, verdict.name, verdict.handle);
+        if (mode === "refuse")
+            throw new FilterInvalid(message, "OQX");
+        if (!seen.has(message)) {
+            seen.add(message);
+            hints.push(message);
+        }
+    }
+    return hints;
+}
+//# sourceMappingURL=names.js.map