@omgbase/core 0.15.0 → 0.19.0

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

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

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

@@ -125,6 +125,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/run.d.ts

@@ -1,5 +1,6 @@
-import type { Query, Expr } from "@omgbase/oqx";
+import type { Query, Expr, SelectItem } from "@omgbase/oqx";
 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 +19,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;
@@ -35,6 +40,17 @@ export interface OqxResult {
 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. */
@@ -43,7 +59,18 @@ export interface OqxOptions {
 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.
+ */
+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

@@ -128,6 +128,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
@@ -213,33 +228,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) };
+}
+// 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`), keeping the first (so the retained hit
-// carries a real identity). Order-preserving.
-function dedupHitsByProjection(hits) {
+// 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,9 +290,22 @@ export function oqxRun(store, repoId, source, opts = {}) {
     }
 }
 function oqxRunInner(store, repoId, source, opts) {
+    const raw = parse(source);
+    const reserved = reservedAlias(raw.select);
+    if (reserved)
+        throw reserved;
+    return oqxRunQuery(store, repoId, raw, 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.
+ */
+export function oqxRunQuery(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 raw = parse(source);
     checkRootSpellings(raw);
     const parsed = rewriteQuery(resolveAliases(raw));
     const consumer = parsed.consumer;
@@ -289,11 +340,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 +368,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 +392,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/spec-versions.d.ts

@@ -1,14 +1,14 @@
 export declare const SPEC_VERSIONS: {
-    readonly oqx: "0.20";
+    readonly oqx: "0.21";
     readonly format: "0.2";
     readonly reconcile: "2.3";
-    readonly store: "14.0";
+    readonly store: "14.1";
     readonly properties: "1.1";
     readonly graph: "1.1";
     readonly search: "2.0";
-    readonly mutate: "3.0";
+    readonly mutate: "3.3";
     readonly sync: "2.2";
-    readonly surface: "4.0";
-    readonly cli: "4.0";
+    readonly surface: "4.4";
+    readonly cli: "4.3";
 };
 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.1",
     properties: "1.1",
     graph: "1.1",
     search: "2.0",
-    mutate: "3.0",
+    mutate: "3.3",
     sync: "2.2",
-    surface: "4.0",
-    cli: "4.0",
+    surface: "4.4",
+    cli: "4.3",
 };
 //# sourceMappingURL=spec-versions.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omgbase/core",
-  "version": "0.15.0",
+  "version": "0.19.0",
   "description": "Open Markdown Graph Base — embedded engine",
   "license": "MIT",
   "repository": {
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@omgbase/oqx": "^0.20.0",
+    "@omgbase/oqx": "^0.21.0",
     "better-sqlite3": "^13.0.3",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-frontmatter": "^2.0.1",