@omgbase/core 0.15.0 → 0.21.0

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);
@@ -125,6 +129,10 @@ function exprMayRaise(e, target, root) {
             return (e.lo !== null && exprMayRaise(e.lo, target, root)) || (e.hi !== null && exprMayRaise(e.hi, target, root));
         // A tuple (oqx 0.20) is never pushed down; it raises iff an element does.
         case "tuple": return e.items.some((x) => exprMayRaise(x, target, root));
+        // A template literal (oqx 0.21) is never pushed down; interpolating a list or
+        // a record is an eval error only the data decides, so with any interpolation
+        // it may raise.
+        case "template": return e.parts.some((p) => typeof p !== "string");
         case "lit":
         case "binding": return false;
     }

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,5 +1,7 @@
-import type { Query, Expr } from "@omgbase/oqx";
+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";
 export type OqxConsumer = "collect" | "count" | "exists" | "none" | "first" | "single";
 export type EmbedQuery = (text: string) => Promise<{
@@ -18,6 +20,10 @@ export interface OqxHit {
     [k: string]: unknown;
 }
 export interface OqxResult {
+    /** `{ id, path, ...projection }` per hit — or, under `OqxOptions.bare`, the
+     * projection alone (`id`/`path` present only when the query projected them;
+     * typed as `OqxHit` for the one hit shape every consumer handles, a bare
+     * caller knows it asked). */
     hits: OqxHit[];
     truncated: boolean;
     cursor: string | null;
@@ -31,19 +37,57 @@ 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;
     cursor?: string | null;
+    /** Return each hit as its PROJECTION only — no automatic `id`/`path`
+     * members (spec/surface §1.4, 4.2): `select title, era from docs` yields
+     * `{ title, era }` rows. Needs a `select` (without a projection a hit is
+     * only its envelope) and is refused with `values` (already the bare-values
+     * form); both are `filter_invalid` before the engine runs. A projected
+     * `id`/`path` is the intrinsic as everywhere (`select id` → `{ id }`), and
+     * with no envelope there is nothing to collide with (`select path: layer`
+     * is fine). Paging, `distinct`, `truncated` and `cursor` are unchanged —
+     * the runner keeps identity internally and strips the envelope last. The
+     * scalar consumers (`count`/`exists`/`none`) have no hits and ignore it. */
+    bare?: boolean;
     semanticVectors?: Map<string, SemanticVec>;
     /** 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;
 export declare function collectSemanticPhrases(source: string): string[];
+export declare function reservedAlias(items: readonly SelectItem[]): FilterInvalid | null;
+export declare const BARE_NEEDS_SELECT_MESSAGE = "`bare` needs a `select` \u2014 without a projection a hit is only its envelope";
+export declare const BARE_WITH_VALUES_MESSAGE = "`bare` is redundant with `values` \u2014 `values` is already the bare-values form; drop one";
 export declare function oqxRun(store: Store, repoId: string, source: string, opts?: OqxOptions): OqxResult;
+/**
+ * The AST entry (4.1): run an already parsed query — the source path above
+ * 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. 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>;
 /** Parse an OQX source into the `@omgbase/oqx` AST (re-exported for callers). */
 export declare function parseOqx(source: string): Query;

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

@@ -6,8 +6,9 @@
 // in-tree compiler, so every caller and the corpus are unchanged.
 import { parse, PlannedEngine, InMemoryEngine, OqxError, resolveAliases, transform, visit, build, semantics } from "@omgbase/oqx";
 import { makeStoreContext, rowRef } from "./context.js";
-import { SQLiteQueryPlanner, rootTarget } from "./planner.js";
-import { REPO_REMOVED_MESSAGE, TARGETS, bareTargetMessage, pastRootMessage, unknownTargetMessage } from "./root-row.js";
+import { SQLiteQueryPlanner } from "./planner.js";
+import { REPO_REMOVED_MESSAGE, ROOTS, bareTargetMessage, pastRootMessage, unknownTargetMessage } from "./root-row.js";
+import { checkNames } from "./names.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 import { float32ToBlob } from "../core/vec.js";
 import { encodeCursor as encodeKeyset, decodePathCursor } from "../core/cursor.js";
@@ -72,8 +73,8 @@ export function rootPathLiterals(e) {
 export function checkRootSpellings(q) {
     // A top-level `from <name>` that is no collection (`from edges`, the links
     // target's name before 3.0) would scan an absent root and come back empty:
-    // refused, naming the four collections (root-row.ts).
-    if (q.source.kind === "ident" && !TARGETS.has(q.source.name))
+    // refused, naming the five collections (root-row.ts).
+    if (q.source.kind === "ident" && !ROOTS.has(q.source.name))
         throw new FilterInvalid(unknownTargetMessage(q.source.name), "OQX");
     visit(q, {
         enter(node, ctx) {
@@ -84,7 +85,7 @@ export function checkRootSpellings(q) {
             if (node.kind === "ident" && ctx.depth >= 1 && (node.name === "docs" || node.name === "links")) {
                 throw new FilterInvalid(bareTargetMessage(node.name, ctx.depth), "OQX");
             }
-            if (node.kind === "outer" && TARGETS.has(node.name) && node.levels > ctx.depth) {
+            if (node.kind === "outer" && ROOTS.has(node.name) && node.levels > ctx.depth) {
                 throw new FilterInvalid(pastRootMessage(node.name, node.levels), "OQX");
             }
         },
@@ -128,6 +129,21 @@ export function collectSemanticPhrases(source) {
 }
 const ID_ITEM = build.field("__oqx_id", build.ident("id"));
 const PATH_ITEM = build.field("__oqx_path", build.ident("path"));
+// The runner's own projection names (`__oqx_id`, `__oqx_path`, `__oqx_self`,
+// `__oqx_value`) and the selector compiler's slots (`__omg_sel_<t>_<slot>`,
+// mutate/select.ts) share two reserved prefixes. A user alias under either would
+// shadow an injected item (`select __oqx_id: 1` overwrote the hit's `id` through
+// 4.0) or collide with a slot, so it is refused before anything runs — over the
+// query's own top-level items, the only ones the runner injects beside.
+const RESERVED_ALIAS_PREFIXES = ["__oqx_", "__omg_"];
+export function reservedAlias(items) {
+    for (const item of items) {
+        const prefix = RESERVED_ALIAS_PREFIXES.find((p) => item.name.startsWith(p));
+        if (prefix !== undefined)
+            return new FilterInvalid(`projection \`${item.name}\` uses the reserved prefix \`${prefix}\` — choose another alias`, "OQX");
+    }
+    return null;
+}
 // Result projections may not overwrite the envelope (spec/surface §1.4, 3.0):
 // a projection whose output key is `id` or `path` is allowed only when it IS
 // the envelope's own selection — the bare attribute of the same name, which
@@ -150,8 +166,9 @@ function envelopeCollision(items) {
     return null;
 }
 // A hit is a store row (spec/surface §1.4, 1.5). The engine's top-level rows
-// are store rows by construction when the source is a bare root scan and
-// nothing re-projects them; a `follow` destination (`follow before` over a
+// are store rows by construction when the source is a bare root scan (one of
+// the five collections, `revisions` included — the planner's `rootTarget` is
+// narrower: the four it can plan) and nothing re-projects them; a `follow` destination (`follow before` over a
 // frontmatter list of paths), a `from E` re-projection or any other source can
 // reach a scalar, which the injected `id`/`path` reads would render as the
 // junk hit `{ id: "undefined", path: "" }`. For those queries the row itself is
@@ -162,7 +179,7 @@ function envelopeCollision(items) {
 const SELF_KEY = "__oqx_self";
 const SELF_ITEM = build.field(SELF_KEY, build.ident("$it"));
 function mayReachNonRows(q) {
-    return q.follow !== null || q.from.length > 0 || rootTarget(q.source) === null;
+    return q.follow !== null || q.from.length > 0 || !(q.source.kind === "ident" && ROOTS.has(q.source.name));
 }
 function describeValue(v) {
     if (v === null || v === undefined)
@@ -180,7 +197,7 @@ function describeValue(v) {
     return "an object";
 }
 function notAStoreRow(v) {
-    return new FilterInvalid(`a hit must be a document, block, node or link row — the query reached ${describeValue(v)}; to follow document references held in a property use refs(<field>)`, "OQX");
+    return new FilterInvalid(`a hit must be a document, block, node, link or revision row — the query reached ${describeValue(v)}; to follow document references held in a property use refs(<field>)`, "OQX");
 }
 // The reserved key a top-level `values` projection's single item is renamed to,
 // so it rides through id/path injection, keyset paging, and distinct as an
@@ -213,33 +230,56 @@ function renderValue(v) {
         out[k] = renderValue(x);
     return out;
 }
-function toHit(row) {
+function shapeRow(row) {
     const o = row;
     const { __oqx_id, __oqx_path, __oqx_self, ...rest } = o;
     if (SELF_KEY in o && !rowRef(__oqx_self))
         throw notAStoreRow(__oqx_self);
-    // The envelope keys lead; a user projection of `id`/`path` collapses onto
-    // them in place (the same value, read by the same attribute).
-    return { id: String(__oqx_id), path: String(__oqx_path ?? ""), ...renderValue(rest) };
+    return { id: String(__oqx_id), path: String(__oqx_path ?? ""), proj: renderValue(rest) };
 }
-// Top-level `select distinct`: dedup hits by their USER projection (every field
-// except the envelope's `id`/`path`), keeping the first (so the retained hit
-// carries a real identity). Order-preserving.
-function dedupHitsByProjection(hits) {
+// The envelope keys lead; a user projection of `id`/`path` collapses onto
+// them in place (the same value, read by the same attribute).
+function toHit(s) {
+    return { id: s.id, path: s.path, ...s.proj };
+}
+// `bare` (4.2): the projection alone. A projected `id`/`path` is an ordinary
+// column here — the intrinsic the attribute reads, under the key the query
+// gave it — and nothing is injected beside it.
+function toBareHit(s) {
+    return s.proj;
+}
+// Top-level `select distinct`: dedup hits by their USER projection — every
+// field except the envelope's `id`/`path`, which a projection of the attribute
+// collapses onto (so `select distinct id` dedups on nothing but the empty
+// projection, as it always has); under `bare` there is no envelope, so a
+// projected `id`/`path` IS part of the projection and counts. Keeps the first
+// (so the retained hit carries a real identity). Order-preserving.
+function dedupByProjection(rows, bare) {
     const seen = new Set();
     const out = [];
-    for (const h of hits) {
-        const { id: _id, path: _path, ...proj } = h;
-        void _id;
-        void _path;
-        const key = JSON.stringify(Object.keys(proj).sort().map((k) => [k, proj[k]]));
+    for (const s of rows) {
+        const keys = Object.keys(s.proj).filter((k) => bare || !ENVELOPE_KEYS.has(k)).sort();
+        const key = JSON.stringify(keys.map((k) => [k, s.proj[k]]));
         if (seen.has(key))
             continue;
         seen.add(key);
-        out.push(h);
+        out.push(s);
     }
     return out;
 }
+// `bare` is examined where hits are built (spec/surface §1.4, 4.2): without a
+// projection a hit is only its envelope, and `values` is already the
+// bare-values form — both refused before the engine runs, over the resolved
+// query, so the error never depends on the rows.
+export const BARE_NEEDS_SELECT_MESSAGE = "`bare` needs a `select` — without a projection a hit is only its envelope";
+export const BARE_WITH_VALUES_MESSAGE = "`bare` is redundant with `values` — `values` is already the bare-values form; drop one";
+function bareMisuse(parsed) {
+    if (parsed.values)
+        return new FilterInvalid(BARE_WITH_VALUES_MESSAGE, "OQX");
+    if (parsed.select.length === 0)
+        return new FilterInvalid(BARE_NEEDS_SELECT_MESSAGE, "OQX");
+    return null;
+}
 export function oqxRun(store, repoId, source, opts = {}) {
     try {
         return oqxRunInner(store, repoId, source, opts);
@@ -252,10 +292,40 @@ export function oqxRun(store, repoId, source, opts = {}) {
     }
 }
 function oqxRunInner(store, repoId, source, opts) {
-    // The query's `select` aliases are resolved HERE, once, before the runner
-    // renames/injects items (an engine evaluates the query it is given).
     const raw = parse(source);
+    const reserved = reservedAlias(raw.select);
+    if (reserved)
+        throw reserved;
+    // The source entry is every read: a tier-3 name on an open kind is a hint.
+    return oqxRunQuery(store, repoId, raw, { unknownNames: "hint", ...opts });
+}
+/**
+ * The AST entry (4.1): run an already parsed query — the source path above
+ * 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. 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 function oqxRunQuery(store, repoId, raw, opts = {}) {
     checkRootSpellings(raw);
+    // Unknown names (spec/surface §1.5): judged over the RAW tree — before alias
+    // resolution and the runner's own items — so an alias is never mistaken for
+    // a row property and the verdict never depends on the rows. The selector
+    // compiler's slot items (`__omg_sel_*`, the templates' expressions) are not
+    // the selector: an expression reading an absent property there is
+    // spec/mutate's `target_missing` / absent value, not an unknown name.
+    const own = { ...raw, select: raw.select.filter((it) => !RESERVED_ALIAS_PREFIXES.some((p) => it.name.startsWith(p))) };
+    const hints = checkNames(store, repoId, own, opts.unknownNames ?? "refuse");
+    const result = runResolved(store, repoId, raw, opts);
+    // `hints` is the last member, present only when there is something to say.
+    return hints.length === 0 ? result : { ...result, hints };
+}
+function runResolved(store, repoId, raw, opts) {
+    // The query's `select` aliases are resolved HERE, once, before the runner
+    // renames/injects items (an engine evaluates the query it is given).
     const parsed = rewriteQuery(resolveAliases(raw));
     const consumer = parsed.consumer;
     const ctxOpts = opts.semanticVectors ? { semanticVectors: opts.semanticVectors } : {};
@@ -289,11 +359,21 @@ function oqxRunInner(store, repoId, source, opts) {
     // the final page below and returned as `values` with `hits` empty.
     const topValues = parsed.values;
     const userSelect = topValues ? [{ ...parsed.select[0], name: VALUE_KEY }] : parsed.select;
-    if (!topValues) {
+    // `bare` (4.2): the hits are the projection alone — refused without one and
+    // with `values`; with no envelope there is no collision to refuse either, a
+    // projected `id`/`path` is simply a column.
+    const bare = opts.bare === true;
+    if (bare) {
+        const misuse = bareMisuse(parsed);
+        if (misuse)
+            throw misuse;
+    }
+    else if (!topValues) {
         const collision = envelopeCollision(userSelect);
         if (collision)
             throw collision;
     }
+    const render = bare ? toBareHit : toHit;
     // On the collect path a top-level `limit`/`offset` is ALSO taken out of the
     // engine query and applied here, after the runner's own distinct — the engine
     // would otherwise bound the raw rows before dedup (`select distinct type
@@ -307,13 +387,13 @@ function oqxRunInner(store, repoId, source, opts) {
     if (consumer === "first" || consumer === "single") {
         const row = res.consumer === "first" || res.consumer === "single" ? res.row : null;
         if (topValues)
-            return { hits: [], truncated: false, cursor: null, consumer, values: row == null ? [] : [toHit(row)[VALUE_KEY]] };
-        return { hits: row == null ? [] : [toHit(row)], truncated: false, cursor: null, consumer };
+            return { hits: [], truncated: false, cursor: null, consumer, values: row == null ? [] : [shapeRow(row).proj[VALUE_KEY]] };
+        return { hits: row == null ? [] : [render(shapeRow(row))], truncated: false, cursor: null, consumer };
     }
     // collect: keyset pagination on (path, id) when the order is the default.
-    let rows = (res.consumer === "collect" ? res.rows : []).map(toHit);
+    let rows = (res.consumer === "collect" ? res.rows : []).map(shapeRow);
     if (topDistinct)
-        rows = dedupHitsByProjection(rows);
+        rows = dedupByProjection(rows, bare);
     // The query's own bound defines the result SET; the `limit`/`cursor` options
     // then page within it.
     const offset = constBound(topOffset, "offset") ?? 0;
@@ -331,9 +411,11 @@ function oqxRunInner(store, repoId, source, opts) {
     page = page.slice(0, cap);
     const last = page[page.length - 1];
     const cursor = truncated && last && !custom ? encodeCursor(last.path, last.id) : null;
+    // The envelope is stripped LAST (`bare`): the page and the cursor above ran
+    // on identity, so a bare result pages exactly like the enveloped one.
     if (topValues)
-        return { hits: [], truncated, cursor, consumer: "collect", values: page.map((h) => h[VALUE_KEY]) };
-    return { hits: page, truncated, cursor, consumer: "collect" };
+        return { hits: [], truncated, cursor, consumer: "collect", values: page.map((s) => s.proj[VALUE_KEY]) };
+    return { hits: page.map(render), truncated, cursor, consumer: "collect" };
 }
 export async function oqxRunAsync(store, repoId, source, opts = {}, embedQuery) {
     const phrases = collectSemanticPhrases(source);

package/dist/src/oqx-js/sql/translate.js

@@ -53,7 +53,7 @@ import { TARGETS } from "../root-row.js";
  * `translate.test.ts` asserts this set against the store context.
  */
 export const NON_PROPERTY_NAMES = {
-    docs: new Set(["doc", "nodes", "blocks", "out_links", "in_links", "data", "frontmatter", "inline"]),
+    docs: new Set(["doc", "nodes", "blocks", "out_links", "in_links", "revisions", "data", "frontmatter", "inline"]),
     blocks: new Set(["block", "doc", "children", "nodes", "out_links", "section", "attrs"]),
     nodes: new Set(["section", "doc", "block", "blocks", "subsections", "children", "attrs"]),
     links: new Set(["doc", "dst"]),

package/dist/src/spec-versions.d.ts

@@ -1,14 +1,14 @@
 export declare const SPEC_VERSIONS: {
-    readonly oqx: "0.20";
+    readonly oqx: "0.23";
     readonly format: "0.2";
     readonly reconcile: "2.3";
-    readonly store: "14.0";
+    readonly store: "14.2";
     readonly properties: "1.1";
     readonly graph: "1.1";
     readonly search: "2.0";
-    readonly mutate: "3.0";
+    readonly mutate: "3.5";
     readonly sync: "2.2";
-    readonly surface: "4.0";
-    readonly cli: "4.0";
+    readonly surface: "4.7";
+    readonly cli: "4.5";
 };
 export type SpecName = keyof typeof SPEC_VERSIONS;

package/dist/src/spec-versions.js

@@ -13,13 +13,13 @@ export const SPEC_VERSIONS = {
     oqx: LANGUAGE_VERSION,
     format: "0.2",
     reconcile: "2.3",
-    store: "14.0",
+    store: "14.2",
     properties: "1.1",
     graph: "1.1",
     search: "2.0",
-    mutate: "3.0",
+    mutate: "3.5",
     sync: "2.2",
-    surface: "4.0",
-    cli: "4.0",
+    surface: "4.7",
+    cli: "4.5",
 };
 //# sourceMappingURL=spec-versions.js.map

package/dist/src/sync/observe.js

@@ -189,9 +189,15 @@ function commitPrepared(store, repoId, prepared, ts, oldHashHex, newHashHex) {
     const conflicted = hasConflictMarkers(content);
     const resolveIds = makeReconcilingResolver(store, repoId, { ts, path, prepared });
     const res = ingestFile(store, repoId, path, content, { ts, origin: "observed", resolveIds, parsed: prepared.tree, conflicted });
-    const rows = store.db
-        .prepare("SELECT kind, count(*) n FROM dispositions WHERE commit_id = ? GROUP BY kind ORDER BY kind")
-        .all(res.commitId);
+    // The outcome counts every verdict the matcher produced, `same` included —
+    // it describes what the matcher saw; the `dispositions` table describes
+    // what changed (spec/store §5.4 step 10, 14.2: `same` is not persisted), so
+    // the counts come from the in-memory result, not the table. Kinds in
+    // bytewise order, as the table query listed them through 14.1.
+    const counts = new Map();
+    for (const d of prepared.result.dispositions)
+        counts.set(d.kind, (counts.get(d.kind) ?? 0) + 1);
+    const rows = [...counts].map(([kind, n]) => ({ kind, n })).sort((a, b) => (a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0));
     return {
         docId: res.docId,
         path,

package/dist/src/version.d.ts

@@ -1,5 +1,6 @@
 import type { Store } from "./core/store/store.js";
 import { SPEC_VERSIONS } from "./spec-versions.js";
+import type { ToolsProfile } from "./mcp/server.js";
 export interface HostInfo {
     /** the serving binary's own version — `omgbase`'s package.json (what `--version` prints) */
     version: string;
@@ -25,6 +26,8 @@ export interface VersionInfo {
     runtime: string;
     commit: string | null;
     built: string | null;
+    /** the catalog profile the server serves (spec/surface §4 "Profiles", 4.3): `omg version` itself reports `full` */
+    profile: ToolsProfile;
 }
 /** The omgbase packages the reference binary is built from (spec/surface §4). */
 export declare const COMPONENT_PACKAGES: readonly ["omgbase", "@omgbase/core", "@omgbase/oqx", "@omgbase/sync", "@omgbase/fs-adapter"];
@@ -34,6 +37,8 @@ export declare function nearestPackageVersion(fromUrl: string, name: string): st
 export declare function coreVersion(): string;
 /**
  * The `version` result. `store` supplies `schema`; `host` the binary's own
- * version, build info and resolution anchor (see the module comment).
+ * version, build info and resolution anchor (see the module comment);
+ * `profile` the catalog profile served (the MCP server's `--tools`; the CLI's
+ * own `version` verb is the full library and says `full`).
  */
-export declare function versionInfo(store?: Store | null, host?: HostInfo): VersionInfo;
+export declare function versionInfo(store?: Store | null, host?: HostInfo, profile?: ToolsProfile): VersionInfo;

package/dist/src/version.js

@@ -73,9 +73,11 @@ export function coreVersion() {
 }
 /**
  * The `version` result. `store` supplies `schema`; `host` the binary's own
- * version, build info and resolution anchor (see the module comment).
+ * version, build info and resolution anchor (see the module comment);
+ * `profile` the catalog profile served (the MCP server's `--tools`; the CLI's
+ * own `version` verb is the full library and says `full`).
  */
-export function versionInfo(store, host) {
+export function versionInfo(store, host, profile = "full") {
     const anchors = [...(host?.resolveFrom ? [host.resolveFrom] : []), import.meta.url];
     const components = {};
     for (const name of COMPONENT_PACKAGES) {
@@ -98,6 +100,7 @@ export function versionInfo(store, host) {
         runtime: `node ${process.versions.node}`,
         commit: host?.commit ?? null,
         built: host?.built ?? null,
+        profile,
     };
 }
 //# sourceMappingURL=version.js.map