@omgbase/core 0.19.0 → 0.21.0

package/dist/src/mutate/known-ids.js

@@ -1,4 +1,5 @@
 import { mintId } from "../core/ids.js";
+import { sha256 } from "../core/hash.js";
 import { extractFromBlock, extractFromFrontmatter, resolveRelativePath } from "../graph/extract.js";
 import { resolveExternal, resolveDocPath } from "../core/store/edges.js";
 import { adapterForPath } from "../format/index.js";
@@ -79,12 +80,19 @@ export function makeKnownIdResolver(store, repoId, doc, priorIds, opts = {}) {
         const assigned = assignFromMut(rest, byKey);
         const nowIds = collectIds(assigned);
         const nowSet = new Set(nowIds);
-        // Dispositions are INTENT, not inference: a carried id that existed before is
-        // `same`/`edited` (confidence 1.0); an id new this commit is `inserted`; a
-        // prior id no longer present is `deleted`.
-        const dispositions = nowIds.map((id) => ({
-            blockId: id,
-            kind: priorIds.has(id) ? "edited" : "inserted",
+        // Dispositions are INTENT, not inference (confidence 1.0, reason `api`): an
+        // id new this commit is `inserted`; a prior id no longer present is
+        // `deleted` (pooled, no row); a carried id is classified exactly as
+        // spec/reconcile §2 classifies a carry — `same` when its raw bytes, parent
+        // and sibling index are those of its live row, else `edited` / `moved` /
+        // `edited_moved` — so a block the changeset did not touch is `same` and
+        // (spec/store §5.4 step 10, 14.2) never persisted: a one-paragraph edit
+        // moves that paragraph's `updated_at`, not its siblings'. Through store
+        // 14.1 every carried block was stamped `edited`.
+        const prior = docId === null ? new Map() : priorRows(db, docId);
+        const dispositions = classifyCarries(assigned, prior, priorIds).map((c) => ({
+            blockId: c.id,
+            kind: c.kind,
             confidence: 1,
             reason: "api",
             matcherV: null,
@@ -121,10 +129,42 @@ export function makeKnownIdResolver(store, repoId, doc, priorIds, opts = {}) {
             }
             return out;
         };
-        void docId;
         return { assigned, dispositions, deleted, crossDocIds, extractEdges };
     };
 }
+function priorRows(db, docId) {
+    const rows = db
+        .prepare("SELECT block_id, parent_block, ordinal, raw_hash FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL")
+        .all(docId);
+    return new Map(rows.map((r) => [r.block_id, { parent: r.parent_block, ordinal: r.ordinal, rawHashHex: r.raw_hash.toString("hex") }]));
+}
+/**
+ * spec/reconcile §2 "Classifying a carry", applied to the api path's known ids:
+ * `moved` = the parent or the sibling index differs from the live row,
+ * `content_equal` = the raw bytes hash the same; `same` / `moved` / `edited` /
+ * `edited_moved` follow. An id with no prior row (new to this document — a
+ * mint or a cross-document arrival) is `inserted`. Pre-order over the tree.
+ */
+export function classifyCarries(blocks, prior, priorIds) {
+    const out = [];
+    const walk = (list, parent) => {
+        list.forEach((b, index) => {
+            const row = priorIds.has(b.blockId) ? prior.get(b.blockId) : undefined;
+            if (!row) {
+                out.push({ id: b.blockId, kind: "inserted" });
+            }
+            else {
+                const moved = row.parent !== parent || row.ordinal !== index;
+                const contentEqual = row.rawHashHex === sha256(b.raw).toString("hex");
+                out.push({ id: b.blockId, kind: contentEqual ? (moved ? "moved" : "same") : moved ? "edited_moved" : "edited" });
+            }
+            if (b.children.length > 0)
+                walk(b.children, b.blockId);
+        });
+    };
+    walk(blocks, null);
+    return out;
+}
 // Edge resolution — mirrors reconciling-ingest's resolvers (block-anchor targets
 // resolve to the document node in v1; the anchor is preserved on the edge).
 function resolveEdge(db, repoId, srcDoc, e, docDir) {

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

@@ -35,6 +35,7 @@ export declare function opRemove(doc: MutDoc, blockIds: string[], opIndex: numbe
 export declare function opSplit(doc: MutDoc, blockId: string, at: number[], opIndex: number, expect?: Expect): {
     ids: string[];
 };
+export declare function trimCutEdges(pieces: readonly string[]): string[];
 export declare function opMerge(doc: MutDoc, blockIds: string[], opIndex: number, separator?: string, expectPer?: Record<string, Expect>): {
     ids: string[];
     mergedInto: string[];

package/dist/src/mutate/ops.js

@@ -505,7 +505,7 @@ export function opSplit(doc, blockId, at, opIndex, expect) {
     const pieces = [];
     for (let i = 1; i < cuts.length; i++)
         pieces.push(raw.slice(cuts[i - 1], cuts[i]));
-    const nonEmpty = pieces.filter((p) => p.trim().length > 0);
+    const nonEmpty = trimCutEdges(pieces).filter((p) => p.trim().length > 0);
     if (nonEmpty.length < 2)
         throw new MutationError("type_mismatch", "split must yield ≥2 non-empty fragments");
     // First fragment carries the id (authored intent, 04 §1); rest minted.
@@ -533,6 +533,25 @@ export function opSplit(doc, blockId, at, opIndex, expect) {
     markContainerDirty(doc, found.siblings);
     return { ids: [blockId, ...newBlocks.map((b) => b.id)] };
 }
+// spec/mutate §2.5 (3.5): the pieces of a split are trimmed at the CUT edges
+// only — every piece but the last loses its trailing whitespace, every piece
+// but the first its leading whitespace — so an offset on either side of a
+// space (or inside the run, a `\n`, a hard break's `  \n`) yields the same
+// pieces and no piece ends in a stray space. The raw's own start and end are
+// not cut edges and stay as authored (a last piece keeps the raw's trailing
+// spaces). The whitespace set is the format's trim set (`spec/format` §4.1
+// step 4) — exactly what JavaScript's `trimStart`/`trimEnd` remove.
+export function trimCutEdges(pieces) {
+    const last = pieces.length - 1;
+    return pieces.map((p, i) => {
+        let out = p;
+        if (i < last)
+            out = out.trimEnd();
+        if (i > 0)
+            out = out.trimStart();
+        return out;
+    });
+}
 export function opMerge(doc, blockIds, opIndex, separator = " ", expectPer) {
     if (blockIds.length < 2)
         throw new MutationError("not_contiguous", "merge requires ≥2 blocks");

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

@@ -75,15 +75,4 @@ export declare function desugarEffect(raw: unknown, index: number, request?: Fix
 export declare function compileSelection(store: Store, repoId: string, select: unknown, expectRaw: unknown, templatesRaw: unknown): CompiledSelection;
 /** The query a selector request compiles to (admission + rewrite, before any row is read) — `print` it to see what runs. */
 export declare function selectionQuery(select: unknown, templates: unknown): Query;
-/**
- * Compile a plain `effects` list (no selector): desugar the `-> ` leaders,
- * then — when nothing is an expression — the shape check as before (3.0
- * byte-identical). Otherwise each effect with expressions is admitted as a
- * template over its own primary target's row: the effects are grouped by that
- * row's identity, one synthetic query per identity — `from <root> where id ==
- * "<id>"` with the slot items appended, named `__omg_sel_<effectIndex>_<slot>`
- * — runs, and the row binds the slots exactly as a selector's hit would. The
- * concrete effects feed the lowering unchanged; `templates` is the list as
- * written, for the intent record.
- */
 export declare function compilePlain(store: Store, repoId: string, raw: unknown): CompiledPlain;

package/dist/src/mutate/select.js

@@ -294,7 +294,7 @@ function containsOqx(v) {
  * defaults to a hit, and its primary target may not be an expression (the
  * primary target IS the row the expressions read).
  */
-function admitTemplate(raw, index, root, plain) {
+function admitTemplate(raw, index, root, plain, fix) {
     const here = `effects[${index}]`;
     if (!isRecord(raw) || typeof raw.op !== "string")
         throw selectionInvalid(`${here}: a template is an effect object whose \`op\` is one of ${EFFECT_OPS.filter((o) => o !== "retarget").join("/")}`);
@@ -501,8 +501,8 @@ function admitTemplate(raw, index, root, plain) {
         if (containsOqx(raw[key]))
             throw selectionInvalid(`${here}.${key}: \`{ oqx }\` is not allowed here`);
     }
-    // The shape, with a probe in every slot (the §11.1 messages, naming `effects[i]`).
-    validateEffect(probe, index);
+    // The shape, with a probe in every slot (the §11.1 messages, naming `effects[i]`; the §8 shape fixes rewrite the template as written).
+    validateEffect(probe, index, fix);
     return { index, base, slots, defaultTarget };
 }
 /** The `id`/`path` member a bound identity value supplies: a string as given, a row ref by its id. */
@@ -527,7 +527,7 @@ function validateExpect(v) {
 /**
  * The fix of a refused selector source (3.3): the same request over an
  * admitted root — `links` becomes `blocks` (a link lives in a block), any other
- * source `docs` — spliced over the source's span of the written query.
+ * source (`revisions` included) `docs` — spliced over the source's span of the written query.
  */
 function rootFix(select, source, request) {
     if (request === undefined)
@@ -560,6 +560,9 @@ function admitSelector(select, request) {
     if (raw.values)
         throw selectionInvalid("select: a selector yields rows, not `values`");
     const root = rootTarget(raw.source);
+    if (root === null && raw.source.kind === "ident" && raw.source.name === "revisions") {
+        throw selectionInvalid("select: `revisions` rows have no effect target — select docs, blocks or nodes", rootFix(select, raw.source, request));
+    }
     if (root === null)
         throw selectionInvalid("select: a selector scans a root collection — `from docs`, `from blocks` or `from nodes`", rootFix(select, raw.source, request));
     if (root === "links")
@@ -583,6 +586,10 @@ function runQuery(store, repoId, q, limit) {
     catch (e) {
         if (e instanceof OqxError)
             throw new FilterInvalid(e.message, "OQX");
+        // An unknown name (spec/surface §1.5) is refused before any row is read; a
+        // selector's refusal wears the admission prefix and hint like every other.
+        if (e instanceof FilterInvalid)
+            throw selectionInvalid(`select: ${e.message}`);
         throw e;
     }
 }
@@ -639,7 +646,9 @@ function admitRequest(select, templatesRaw, request) {
     if (templatesRaw.length === 0)
         throw selectionInvalid("`effects` must name at least one template");
     const { raw, root } = admitSelector(select, request);
-    const templates = templatesRaw.map((t, i) => admitTemplate(desugarEffect(t, i, request), i, root, false));
+    // Under a selector a template's `into` is bound per hit, so the anchor fix (a parent lookup) does not apply: `parentOf` finds nothing.
+    const fix = request === undefined ? undefined : { request, parentOf: () => null };
+    const templates = templatesRaw.map((t, i) => admitTemplate(desugarEffect(t, i, request), i, root, false, fix));
     // The rewrite: the slot items, named `__omg_sel_<t>_<slot>`, appended after
     // the user's items on the raw tree (so a user alias resolves into them).
     const items = [];
@@ -826,28 +835,43 @@ function scopeOf(store, repoId, e, i) {
  * concrete effects feed the lowering unchanged; `templates` is the list as
  * written, for the intent record.
  */
+/**
+ * The live-row lookup behind the anchor fix (§8, 3.4): a block's parent id
+ * (`null` at the top level) and its document's path, from the `blocks` row
+ * that is not deleted; `null` for an id the store does not know (a `$new.n`,
+ * a typo) — then there is no fix.
+ */
+function parentLookup(store) {
+    return (id) => {
+        const row = store.db
+            .prepare("SELECT b.parent_block AS parent, d.path AS path FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ? AND b.deleted_commit IS NULL")
+            .get(id);
+        return row === undefined ? null : { parent: row.parent, path: row.path };
+    };
+}
 export function compilePlain(store, repoId, raw) {
     if (!Array.isArray(raw))
         throw effectInvalid("`effects` must be an array of effects");
     if (raw.length === 0)
         throw effectInvalid("`effects` must name at least one effect");
     const request = { effects: raw };
+    const fix = { request, parentOf: parentLookup(store) };
     const desugared = raw.map((e, i) => desugarEffect(e, i, request));
     if (!desugared.some(containsOqx))
-        return { effects: desugared.map((e, i) => validateEffect(e, i)), origins: [] };
+        return { effects: desugared.map((e, i) => validateEffect(e, i, fix)), origins: [] };
     const effects = [];
     const origins = [];
     const scopes = new Map();
     desugared.forEach((e, i) => {
         if (!containsOqx(e) || !isRecord(e)) {
-            effects[i] = validateEffect(e, i);
+            effects[i] = validateEffect(e, i, fix);
             return;
         }
         const scope = scopeOf(store, repoId, e, i);
-        const t = admitTemplate(e, i, scope.root, true);
+        const t = admitTemplate(e, i, scope.root, true, fix);
         if (t.slots.length === 0) {
             // `{ oqx }` only inside data (a nested `value`): literal, as for a template.
-            effects[i] = validateEffect(e, i);
+            effects[i] = validateEffect(e, i, fix);
             return;
         }
         const key = `${scope.root}:${scope.id}`;

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[];