@omgbase/core 0.19.0 → 0.21.0

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

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

@@ -15,9 +15,9 @@ export declare function rootTarget(source: Expr): Target | null;
  *   • a bare reserved docs basename (`id path updated_at hash raw`): as
  *     an `ident` at the ROOT scope when the target is `docs`, or as `doc.<name>`
  *     on any target at any depth (the reach-through row is a doc)
- *   • a bare target name (`docs blocks nodes links`, root-row.ts) read as a
- *     property: as an `ident` at the ROOT scope when it is not a relation of
- *     the target's rows (`blocks` on blocks, `nodes` on nodes, any on links),
+ *   • a bare root name (`docs blocks nodes links revisions`, root-row.ts) read
+ *     as a property: as an `ident` at the ROOT scope when it is not a relation
+ *     of the target's rows (`blocks` on blocks, `nodes` on nodes, any on links),
  *     as an `ident` at any depth below (the rows there are unknown), or as
  *     `<head>.<name>` unless the head is a reach-through whose row has that
  *     relation (`doc.nodes`, `doc.blocks`, `block.nodes`, `section.blocks`)

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

@@ -14,15 +14,16 @@
 // `[]` planned, `filter_invalid` in memory), so when any residual conjunct could
 // raise — a function or method call, a `single` block, a `^`-escaped name, or a
 // bare reserved docs basename — the WHOLE query runs unplanned.
-import { ROWS_ROOT, partitionPushable, residualQuery } from "@omgbase/oqx";
+import { ROWS_ROOT, isRegexOp, partitionPushable, residualQuery } from "@omgbase/oqx";
 import { makeStoreContext, tagRows } from "./context.js";
 import { translatePredicate } from "./sql/translate.js";
 import { ALIAS, COLS, FROM, ORDER, guards } from "./sql/scan.js";
-import { REACH_THROUGH, TARGETS, isTargetRelationOf } from "./root-row.js";
+import { REACH_THROUGH, ROOTS, TARGETS, isTargetRelationOf } from "./root-row.js";
 // The root collection a query scans, if it is a bare `docs|blocks|nodes|links`
 // source at the root scope (else null — not a pushable shape; a nested `^docs`
-// is a block's receiver, never the query's source). run.ts also asks: a bare
-// root scan's rows are store rows by construction.
+// is a block's receiver, never the query's source). `revisions` (4.7) is a root
+// the planner never plans — it is not a `Target` here — so a revisions scan
+// always runs in memory.
 export function rootTarget(source) {
     if (source.kind === "ident" && TARGETS.has(source.name))
         return source.name;
@@ -41,9 +42,9 @@ export function rootTarget(source) {
  *   • a bare reserved docs basename (`id path updated_at hash raw`): as
  *     an `ident` at the ROOT scope when the target is `docs`, or as `doc.<name>`
  *     on any target at any depth (the reach-through row is a doc)
- *   • a bare target name (`docs blocks nodes links`, root-row.ts) read as a
- *     property: as an `ident` at the ROOT scope when it is not a relation of
- *     the target's rows (`blocks` on blocks, `nodes` on nodes, any on links),
+ *   • a bare root name (`docs blocks nodes links revisions`, root-row.ts) read
+ *     as a property: as an `ident` at the ROOT scope when it is not a relation
+ *     of the target's rows (`blocks` on blocks, `nodes` on nodes, any on links),
  *     as an `ident` at any depth below (the rows there are unknown), or as
  *     `<head>.<name>` unless the head is a reach-through whose row has that
  *     relation (`doc.nodes`, `doc.blocks`, `block.nodes`, `section.blocks`)
@@ -107,9 +108,9 @@ function exprMayRaise(e, target, root) {
         case "call": return true;
         case "outer": return true;
         case "ident":
-            return TARGETS.has(e.name) && (!root || !isTargetRelationOf(target, e.name));
+            return ROOTS.has(e.name) && (!root || !isTargetRelationOf(target, e.name));
         case "member":
-            if (TARGETS.has(e.name) && !(e.recv.kind === "ident" && isTargetRelationOf(REACH_THROUGH[e.recv.name], e.name)))
+            if (ROOTS.has(e.name) && !(e.recv.kind === "ident" && isTargetRelationOf(REACH_THROUGH[e.recv.name], e.name)))
                 return true;
             return exprMayRaise(e.recv, target, root);
         case "unary": return exprMayRaise(e.expr, target, root);
@@ -117,7 +118,10 @@ function exprMayRaise(e, target, root) {
         // read anything its block reads.
         case "required": return true;
         case "op": return opMayRaise(e, target, root);
+        // A regex operator (oqx 0.22) is a `matches` call: an invalid pattern
+        // raises, exactly as the call would.
         case "binary":
+            return isRegexOp(e.op) || exprMayRaise(e.left, target, root) || exprMayRaise(e.right, target, root);
         case "logical":
         case "in":
             return exprMayRaise(e.left, target, root) || exprMayRaise(e.right, target, root);

package/dist/src/oqx-js/root-row.d.ts

@@ -1,7 +1,18 @@
 export type Target = "docs" | "blocks" | "nodes" | "links";
+/** Every root collection (spec/surface §1.1): the four row kinds the
+ * unknown-names pass judges (`TARGETS`, names.ts) plus `revisions` (4.7), the
+ * history target — one row per revision of the repository's documents. */
+export type Root = Target | "revisions";
+/** The four row kinds whose names the unknown-names pass judges (names.ts keys
+ * its vocabulary tables by them); `revisions` joins when that pass learns the
+ * kind. Every OTHER root-collection test uses `ROOTS`. */
 export declare const TARGETS: ReadonlySet<string>;
-/** The target names that are a relation of each target's rows (§1.2). */
-export declare const TARGET_RELATIONS: Readonly<Record<Target, ReadonlySet<string>>>;
+/** The root collections, in the root object's entry order (§1.1). */
+export declare const ROOT_NAMES: readonly Root[];
+export declare const ROOTS: ReadonlySet<string>;
+/** The root names that are a relation of each kind's rows (§1.2): `revisions`
+ * on a document is its revision list (4.7). */
+export declare const TARGET_RELATIONS: Readonly<Record<Root, ReadonlySet<string>>>;
 /** The reach-through heads and the target of the row they reach (`doc.x`, `block.x`, `section.x`, and a link's `dst.x`). */
 export declare const REACH_THROUGH: Readonly<Record<string, Target>>;
 export declare const REPO_REMOVED_MESSAGE = "`$repo` was removed in surface 2.0 \u2014 reach the repository's collections through the root row: `^docs` from a top-level row (one caret per enclosing block, or the absolute `0^docs`), and the repository id as `^id` / `0^id`";
@@ -19,10 +30,10 @@ export declare function bareTargetMessage(name: string, depth: number | null): s
 export declare function pastRootMessage(name: string, levels: number): string;
 /**
  * The unknown-target error (3.0 name pass): a top-level `from <name>` whose name
- * is not one of the four collections would read an absent root and return an
+ * is not one of the five collections would read an absent root and return an
  * empty result — refused instead, naming the collections; `edges`, the links
  * target's name before 3.0, gets its new name spelled out.
  */
 export declare function unknownTargetMessage(name: string): string;
 /** Whether `name`, read as `<head>.<name>` or bare on a row of `target`, is one of that row's relations named after a target. */
-export declare function isTargetRelationOf(target: Target | undefined, name: string): boolean;
+export declare function isTargetRelationOf(target: Root | undefined, name: string): boolean;

package/dist/src/oqx-js/root-row.js

@@ -1,7 +1,7 @@
 // The root row (spec/surface §1.1, 2.0; spec/oqx 0.18). The repository is OQX's
 // root row: from a top-level row `^docs` reaches the documents (one caret per
 // enclosing block, or the absolute `0^docs`), `^id` the repository id, and the
-// root object (`^$it`) exposes the four collections. Two spellings are refused
+// root object (`^$it`) exposes the five collections (`revisions` since 4.7). Two spellings are refused
 // as `filter_invalid`, with the messages below, in both engines:
 //
 //   • `$repo` (removed in 2.0) anywhere — bare, as a member head (`$repo.docs`),
@@ -11,22 +11,30 @@
 //   • a bare target name at scope depth ≥ 1 (inside a block, or in a top-level
 //     row's clauses), where a bare name reads a property of the current row,
 //     which has none: `docs` and `links` are no row's relation, so they are
-//     refused statically by the same walk; `blocks` and `nodes` ARE relations
-//     of some rows (`docs.blocks`, `docs.nodes`, `blocks.nodes`,
-//     `section.blocks`), so the context raises the same error at read time on a
-//     row that lacks the relation (context.ts). A frontmatter key named after a
+//     refused statically by the same walk; `blocks`, `nodes` and `revisions`
+//     ARE relations of some rows (`docs.blocks`, `docs.nodes`, `blocks.nodes`,
+//     `section.blocks`, `docs.revisions`), so the context raises the same error
+//     at read time on a row that lacks the relation (context.ts). A frontmatter key named after a
 //     target is unreachable by bare name (use `frontmatter.<k>`).
+/** The four row kinds whose names the unknown-names pass judges (names.ts keys
+ * its vocabulary tables by them); `revisions` joins when that pass learns the
+ * kind. Every OTHER root-collection test uses `ROOTS`. */
 export const TARGETS = new Set(["docs", "blocks", "nodes", "links"]);
-/** The target names that are a relation of each target's rows (§1.2). */
+/** The root collections, in the root object's entry order (§1.1). */
+export const ROOT_NAMES = ["docs", "blocks", "nodes", "links", "revisions"];
+export const ROOTS = new Set(ROOT_NAMES);
+/** The root names that are a relation of each kind's rows (§1.2): `revisions`
+ * on a document is its revision list (4.7). */
 export const TARGET_RELATIONS = {
-    docs: new Set(["nodes", "blocks"]),
+    docs: new Set(["nodes", "blocks", "revisions"]),
     blocks: new Set(["nodes"]),
     nodes: new Set(["blocks"]),
     links: new Set(),
+    revisions: new Set(),
 };
 /** The reach-through heads and the target of the row they reach (`doc.x`, `block.x`, `section.x`, and a link's `dst.x`). */
 export const REACH_THROUGH = { doc: "docs", block: "blocks", section: "nodes", dst: "docs" };
-const NOUN = { docs: "documents", blocks: "blocks", nodes: "nodes", links: "links" };
+const NOUN = { docs: "documents", blocks: "blocks", nodes: "nodes", links: "links", revisions: "revisions" };
 export const REPO_REMOVED_MESSAGE = "`$repo` was removed in surface 2.0 — reach the repository's collections through the root row: `^docs` from a top-level row (one caret per enclosing block, or the absolute `0^docs`), and the repository id as `^id` / `0^id`";
 /**
  * The bare-target error. `depth` is the scope depth the name was read at when
@@ -50,13 +58,13 @@ export function pastRootMessage(name, levels) {
 }
 /**
  * The unknown-target error (3.0 name pass): a top-level `from <name>` whose name
- * is not one of the four collections would read an absent root and return an
+ * is not one of the five collections would read an absent root and return an
  * empty result — refused instead, naming the collections; `edges`, the links
  * target's name before 3.0, gets its new name spelled out.
  */
 export function unknownTargetMessage(name) {
     const was = name === "edges" ? " (`edges` was renamed `links` in surface 3.0)" : "";
-    return `\`${name}\` is not a target — the repository's collections are \`docs\`, \`blocks\`, \`nodes\`, \`links\`${was}`;
+    return `\`${name}\` is not a target — the repository's collections are ${ROOT_NAMES.map((r) => `\`${r}\``).join(", ")}${was}`;
 }
 /** Whether `name`, read as `<head>.<name>` or bare on a row of `target`, is one of that row's relations named after a target. */
 export function isTargetRelationOf(target, name) {

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

@@ -1,4 +1,5 @@
 import type { Query, Expr, SelectItem } from "@omgbase/oqx";
+import { type UnknownNames } from "./names.js";
 import type { Store } from "../core/store/store.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 import type { SemanticVec } from "../search/cel/compile.js";
@@ -36,6 +37,12 @@ export interface OqxResult {
      * empty). Paged/deduped exactly like hits — `truncated`/`cursor` apply. For
      * first/single it holds zero or one value. */
     values?: unknown[];
+    /** Unknown names (spec/surface §1.5, 4.6): one line per name the query reads
+     * that is neither a field of its row kind nor a property any object of that
+     * kind in the repository carries — the rows are still returned. First-
+     * reference order, deduplicated; absent when there is none (never `[]`).
+     * Last member of the result, after everything above. */
+    hints?: string[];
 }
 export interface OqxOptions {
     limit?: number;
@@ -55,6 +62,13 @@ export interface OqxOptions {
     /** Force the pure in-memory engine (skip tier-3 pushdown). Internal — used by
      * the differential conformance suite to prove planned == in-memory. */
     plan?: boolean;
+    /** What a tier-3 name on an open kind does (spec/surface §1.5, 4.6; a tier-3
+     * name on `links` is `filter_invalid` either way): `"hint"` records it in
+     * `hints` and runs the query — the default of the source entry (`oqxRun`,
+     * every read); `"refuse"` throws `filter_invalid` before any row is read —
+     * the default of the AST entry (`oqxRunQuery`), whose caller is the write
+     * selector compiler, where a name no row carries would select every row. */
+    unknownNames?: UnknownNames;
 }
 export declare function rootPathLiterals(e: Expr): Expr;
 export declare function checkRootSpellings(q: Query): void;
@@ -68,7 +82,10 @@ export declare function oqxRun(store: Store, repoId: string, source: string, opt
  * after `parse`, and the selector compiler (`mutate/select.ts`), which appends
  * its slot items to the RAW tree so a user alias a template reads is inlined
  * by the alias resolution here. Errors are the library's own (`OqxError`);
- * `oqxRun` normalizes them, a caller of this entry does the same.
+ * `oqxRun` normalizes them, a caller of this entry does the same. Unknown
+ * names (4.6) default to `"refuse"` here: this entry's caller is the write
+ * selector, where a name no row carries would select every row; the source
+ * entry passes `"hint"`.
  */
 export declare function oqxRunQuery(store: Store, repoId: string, raw: Query, opts?: OqxOptions): OqxResult;
 export declare function oqxRunAsync(store: Store, repoId: string, source: string, opts?: OqxOptions, embedQuery?: EmbedQuery): Promise<OqxResult>;