@omgbase/core 0.11.1 → 0.19.0

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

@@ -0,0 +1,135 @@
+import type { Store } from "../core/store/store.js";
+import { type InboundLink } from "../graph/inbound-links.js";
+import { type DocStore } from "./doc-store.js";
+import type { Effect, EffectAt, EffectExpect, EffectTarget } from "./effects.js";
+import { type ExecuteRequest, type Plan, type Receipt } from "./plan.js";
+/** What a builder returns: the ordered effects and the commit reason they carry (absent → the caller's `reason` argument). */
+export interface Sugar {
+    effects: Effect[];
+    reason?: string;
+}
+/** A live document as the builders address it: its id and its storage-form path (the reasons spell the path). */
+export interface SugarDoc {
+    id: string;
+    path: string;
+}
+/** A caller's guard as an effect guard: absent stays absent, an empty object stays an empty guard (the planner then pins what it needs). */
+export declare function guardOf(e: {
+    content_hash?: string | undefined;
+    parent_children_hash?: string | undefined;
+} | undefined): {
+    expect?: EffectExpect;
+};
+/**
+ * The pre-check a `create` / `move document` caller runs before planning
+ * (spec/surface §4 "The document operations", §9): `path_taken` exactly as the
+ * 2.x library operations raised it — the caller's message (`document already
+ * exists at <rel>` for a create, `a document already exists at <rel>` for a
+ * move), then `file already exists on disk at <rel>` — with NO `data`, so the
+ * planner's own `path_taken { path }` never fires. Shared by the MCP tools and
+ * the `omg` verbs (the Rust port mirrors it).
+ */
+export declare function requireAbsentPath(store: Store, repoId: string, where: {
+    rootPath?: string;
+    docStore?: DocStore;
+}, rel: string, takenMessage: string): void;
+/** `docs_create` / `omg new`: one `create` at the canonical path; reason `create <rel>`. */
+export declare function createEffects(path: string, markdown: string, frontmatter?: Record<string, unknown>): Sugar;
+/** `docs_move` / `omg mv`: one `move { target: document, to, retarget_inbound }`; reason `move <from> -> <to>`. */
+export declare function moveDocEffects(doc: SugarDoc, toPath: string, retargetInbound?: boolean): Sugar;
+/** `docs_delete` / `omg rm --doc`: one `remove { target: document }`; reason `delete <path>`. */
+export declare function deleteDocEffects(doc: SugarDoc): Sugar;
+/**
+ * `docs_set_meta` / `omg meta`: one `set`/`unset frontmatter.<k>` per key, `unset`
+ * winning a key named in both (the legacy merge spread `set` then deleted `unset`);
+ * reason `set_meta <path>`. An empty patch yields no effect — the caller refuses
+ * it (`filter_invalid` "pass `set` and/or `unset`", spec/surface §9).
+ */
+export declare function setMetaEffects(doc: SugarDoc, set: Record<string, unknown> | undefined, unset: readonly string[] | undefined): Sugar;
+/** `docs_update` / `omg update <doc>`: one `set { document, content }`; the reason is the caller's. */
+export declare function updateContentEffects(doc: Pick<SugarDoc, "id">, content: string, reason?: string): Sugar;
+/** `blocks_insert` / `omg insert`: `insert into <document|block> at …`; the caller's `expect` is the destination-parent CAS. */
+export declare function insertEffects(into: EffectTarget, at: EffectAt, markdown: string, expect?: {
+    parent_children_hash?: string | undefined;
+}): Sugar;
+/**
+ * `blocks_update` / `omg update <block>` / `omg edit`: `set markdown` and/or `set
+ * attrs.checked`. The caller's `expect` guards the FIRST effect (the content CAS
+ * is checked once, against the bytes the caller saw); a second effect is pinned
+ * by the planner to the block as the first left it. Nothing to set → no effect
+ * (the caller refuses it).
+ */
+export declare function updateBlockEffects(id: string, patch: {
+    markdown?: string | undefined;
+    checked?: boolean | undefined;
+    expect?: {
+        content_hash?: string | undefined;
+        parent_children_hash?: string | undefined;
+    } | undefined;
+}): Sugar;
+/** `blocks_move` / `omg move`: one `move { targets, into, at, expect }`. */
+export declare function moveBlocksEffects(ids: readonly string[], into: EffectTarget, at: EffectAt, expect?: {
+    parent_children_hash?: string | undefined;
+}): Sugar;
+/** `blocks_remove` / `omg rm`: one `remove { targets }` (the planner pins each block). */
+export declare function removeBlocksEffects(ids: readonly string[]): Sugar;
+/** `blocks_split` / `omg split`: one `split { target, at }` (the planner pins the content CAS). */
+export declare function splitEffects(id: string, at: readonly number[]): Sugar;
+/** `blocks_merge` / `omg merge`: one `merge { targets, separator? }`. */
+export declare function mergeEffects(ids: readonly string[], separator?: string): Sugar;
+/** `blocks_check` / `omg done`: N × `set attrs.checked` (a block named twice is one write — the planner drops the duplicate). */
+export declare function checkEffects(ids: readonly string[], checked: boolean): Sugar;
+/** `nodes_set` / `omg node set`: one `set { node, field: prop, value }`. */
+export declare function nodeSetEffects(nodeId: string, prop: string, value: string): Sugar;
+/** `blocks_append` / `omg append`: `insert at end` into a heading's section or a container block (the caller decided which by the block's kind). */
+export declare function appendEffects(into: EffectTarget, text: string): Sugar;
+/** `docs_append`: `insert at end` into the document's top level or a resolved section. */
+export declare function docsAppendEffects(into: EffectTarget, text: string): Sugar;
+/** `links_retarget` / `links_repair` / `omg retarget --apply`: one `retarget { repairs, path_glob? }` under the calling tool's name. */
+export declare function retargetEffects(repairs: readonly {
+    from: string;
+    to: string;
+}[], pathGlob: string | undefined, reason: "links_retarget" | "links_repair"): Sugar;
+/** The request half a caller supplies: where to write and under whom (`ExecuteRequest` minus the origin's reason, which the sugar carries). */
+export type SugarRequest = Omit<ExecuteRequest, "origin"> & {
+    actor: string | null;
+    reason?: string;
+};
+/**
+ * Plan + execute a builder's effects as one request (`applyEffectsDetailed`: one
+ * lock, one transaction) under `actor` and the sugar's reason — `request.reason`
+ * wins when given (a `--reason`, a `docs_update` argument) — and report any
+ * planner failure without its `effect_index`. `dryRun` plans only (the CLI's
+ * `--dry-run`, spec/cli §3.6: every dry run is a plan and burns no id).
+ */
+export declare function applySugar(store: Store, request: SugarRequest & {
+    dryRun?: boolean;
+}, sugar: Sugar): {
+    plan: Plan;
+    receipt?: Receipt;
+};
+/** The document-operation result the `omg` document verbs and the fixture `docs` step record (`spec/mutate` §9): `{ id, path, committed }`, the path in the storage form. */
+export interface DocOpOutcome {
+    id: string;
+    path: string;
+    committed: true;
+}
+/** `docs_create`'s document is the receipt's first revision (`new_ids["$new.0"]` is the same id); every other operation's is the one addressed. */
+export declare function createdDoc(receipt: Receipt, path: string): DocOpOutcome;
+export declare function docOutcome(doc: SugarDoc, path?: string): DocOpOutcome;
+/** What a move reports about the inbound links (spec/mutate §6 `docs_move`; the `retargeted`/`dangling` extras of the tool and the verb). */
+export interface MoveLinks {
+    /** inbound links still naming the OLD path after the move — every link when the retarget was opted out, else the frontmatter relations a move never rewrites */
+    dangling: InboundLink[];
+    /** the source blocks rewritten and their documents; `null` when the retarget was opted out or nothing linked in */
+    retargeted: {
+        blocks: string[];
+        docs: string[];
+    } | null;
+}
+/**
+ * Who links to the document BY PATH as written, and what the move's retarget
+ * rewrites — computed BEFORE the move from the current blocks (`planInboundRetarget`
+ * is pure, so it equals what the planner lowers for the same `move` effect).
+ */
+export declare function moveLinks(store: Store, repoId: string, doc: SugarDoc, toPath: string, retargetInbound?: boolean): MoveLinks;

package/dist/src/mutate/sugar.js

@@ -0,0 +1,167 @@
+import { findDoc } from "../core/read/reader.js";
+import { inboundLinksTo } from "../graph/inbound-links.js";
+import { canonicalDocPath, planInboundRetarget } from "./docs.js";
+import { resolveDocStore } from "./doc-store.js";
+import { MutationError } from "./tree.js";
+import { applyEffectsDetailed, stripEffectIndex } from "./plan.js";
+const documentTarget = (id) => ({ kind: "document", id });
+const blockTarget = (id) => ({ kind: "block", id });
+/** A caller's guard as an effect guard: absent stays absent, an empty object stays an empty guard (the planner then pins what it needs). */
+export function guardOf(e) {
+    if (!e)
+        return {};
+    const expect = {};
+    if (e.content_hash !== undefined)
+        expect.content_hash = e.content_hash;
+    if (e.parent_children_hash !== undefined)
+        expect.parent_children_hash = e.parent_children_hash;
+    return { expect };
+}
+// ---- the document operations (spec/mutate §6) ---------------------------------------------
+/**
+ * The pre-check a `create` / `move document` caller runs before planning
+ * (spec/surface §4 "The document operations", §9): `path_taken` exactly as the
+ * 2.x library operations raised it — the caller's message (`document already
+ * exists at <rel>` for a create, `a document already exists at <rel>` for a
+ * move), then `file already exists on disk at <rel>` — with NO `data`, so the
+ * planner's own `path_taken { path }` never fires. Shared by the MCP tools and
+ * the `omg` verbs (the Rust port mirrors it).
+ */
+export function requireAbsentPath(store, repoId, where, rel, takenMessage) {
+    if (findDoc(store, { repoId, path: rel }))
+        throw new MutationError("path_taken", takenMessage);
+    if (resolveDocStore(where).exists(rel))
+        throw new MutationError("path_taken", `file already exists on disk at ${rel}`);
+}
+/** `docs_create` / `omg new`: one `create` at the canonical path; reason `create <rel>`. */
+export function createEffects(path, markdown, frontmatter) {
+    const rel = canonicalDocPath(path);
+    return { effects: [{ op: "create", path: rel, markdown, ...(frontmatter !== undefined ? { frontmatter } : {}) }], reason: `create ${rel}` };
+}
+/** `docs_move` / `omg mv`: one `move { target: document, to, retarget_inbound }`; reason `move <from> -> <to>`. */
+export function moveDocEffects(doc, toPath, retargetInbound = true) {
+    const to = canonicalDocPath(toPath);
+    return { effects: [{ op: "move", target: documentTarget(doc.id), to, ...(retargetInbound ? {} : { retarget_inbound: false }) }], reason: `move ${doc.path} -> ${to}` };
+}
+/** `docs_delete` / `omg rm --doc`: one `remove { target: document }`; reason `delete <path>`. */
+export function deleteDocEffects(doc) {
+    return { effects: [{ op: "remove", target: documentTarget(doc.id) }], reason: `delete ${doc.path}` };
+}
+/**
+ * `docs_set_meta` / `omg meta`: one `set`/`unset frontmatter.<k>` per key, `unset`
+ * winning a key named in both (the legacy merge spread `set` then deleted `unset`);
+ * reason `set_meta <path>`. An empty patch yields no effect — the caller refuses
+ * it (`filter_invalid` "pass `set` and/or `unset`", spec/surface §9).
+ */
+export function setMetaEffects(doc, set, unset) {
+    const gone = unset ?? [];
+    const target = documentTarget(doc.id);
+    const effects = [
+        ...Object.entries(set ?? {}).filter(([k]) => !gone.includes(k)).map(([k, value]) => ({ op: "set", target, field: `frontmatter.${k}`, value })),
+        ...gone.map((k) => ({ op: "unset", target, field: `frontmatter.${k}` })),
+    ];
+    return { effects, reason: `set_meta ${doc.path}` };
+}
+/** `docs_update` / `omg update <doc>`: one `set { document, content }`; the reason is the caller's. */
+export function updateContentEffects(doc, content, reason) {
+    return { effects: [{ op: "set", target: documentTarget(doc.id), field: "content", value: content }], ...(reason !== undefined ? { reason } : {}) };
+}
+// ---- the block-level tools (spec/surface §4) ----------------------------------------------
+/** `blocks_insert` / `omg insert`: `insert into <document|block> at …`; the caller's `expect` is the destination-parent CAS. */
+export function insertEffects(into, at, markdown, expect) {
+    return { effects: [{ op: "insert", into, at, markdown, ...guardOf(expect) }], reason: "blocks_insert" };
+}
+/**
+ * `blocks_update` / `omg update <block>` / `omg edit`: `set markdown` and/or `set
+ * attrs.checked`. The caller's `expect` guards the FIRST effect (the content CAS
+ * is checked once, against the bytes the caller saw); a second effect is pinned
+ * by the planner to the block as the first left it. Nothing to set → no effect
+ * (the caller refuses it).
+ */
+export function updateBlockEffects(id, patch) {
+    const target = blockTarget(id);
+    const expect = guardOf(patch.expect);
+    const effects = [];
+    if (patch.markdown !== undefined)
+        effects.push({ op: "set", target, field: "markdown", value: patch.markdown, ...expect });
+    if (patch.checked !== undefined)
+        effects.push({ op: "set", target, field: "attrs.checked", value: patch.checked, ...(effects.length === 0 ? expect : {}) });
+    return { effects, reason: "blocks_update" };
+}
+/** `blocks_move` / `omg move`: one `move { targets, into, at, expect }`. */
+export function moveBlocksEffects(ids, into, at, expect) {
+    return { effects: [{ op: "move", targets: ids.map(blockTarget), into, at, ...guardOf(expect) }], reason: "blocks_move" };
+}
+/** `blocks_remove` / `omg rm`: one `remove { targets }` (the planner pins each block). */
+export function removeBlocksEffects(ids) {
+    return { effects: [{ op: "remove", targets: ids.map(blockTarget) }], reason: "blocks_remove" };
+}
+/** `blocks_split` / `omg split`: one `split { target, at }` (the planner pins the content CAS). */
+export function splitEffects(id, at) {
+    return { effects: [{ op: "split", target: blockTarget(id), at: [...at] }], reason: "blocks_split" };
+}
+/** `blocks_merge` / `omg merge`: one `merge { targets, separator? }`. */
+export function mergeEffects(ids, separator) {
+    return { effects: [{ op: "merge", targets: ids.map(blockTarget), ...(separator !== undefined ? { separator } : {}) }], reason: "blocks_merge" };
+}
+/** `blocks_check` / `omg done`: N × `set attrs.checked` (a block named twice is one write — the planner drops the duplicate). */
+export function checkEffects(ids, checked) {
+    return { effects: ids.map((id) => ({ op: "set", target: blockTarget(id), field: "attrs.checked", value: checked })), reason: "blocks_check" };
+}
+/** `nodes_set` / `omg node set`: one `set { node, field: prop, value }`. */
+export function nodeSetEffects(nodeId, prop, value) {
+    return { effects: [{ op: "set", target: { kind: "node", id: nodeId }, field: prop, value }], reason: "nodes_set" };
+}
+/** `blocks_append` / `omg append`: `insert at end` into a heading's section or a container block (the caller decided which by the block's kind). */
+export function appendEffects(into, text) {
+    return { effects: [{ op: "insert", into, at: "end", markdown: text }], reason: "blocks_append" };
+}
+/** `docs_append`: `insert at end` into the document's top level or a resolved section. */
+export function docsAppendEffects(into, text) {
+    return { effects: [{ op: "insert", into, at: "end", markdown: text }], reason: "docs_append" };
+}
+/** `links_retarget` / `links_repair` / `omg retarget --apply`: one `retarget { repairs, path_glob? }` under the calling tool's name. */
+export function retargetEffects(repairs, pathGlob, reason) {
+    return { effects: [{ op: "retarget", repairs: repairs.map((r) => ({ from: r.from, to: r.to })), ...(pathGlob !== undefined ? { path_glob: pathGlob } : {}) }], reason };
+}
+/**
+ * Plan + execute a builder's effects as one request (`applyEffectsDetailed`: one
+ * lock, one transaction) under `actor` and the sugar's reason — `request.reason`
+ * wins when given (a `--reason`, a `docs_update` argument) — and report any
+ * planner failure without its `effect_index`. `dryRun` plans only (the CLI's
+ * `--dry-run`, spec/cli §3.6: every dry run is a plan and burns no id).
+ */
+export function applySugar(store, request, sugar) {
+    const { actor, reason, dryRun, ...rest } = request;
+    const chosen = reason ?? sugar.reason;
+    try {
+        return applyEffectsDetailed(store, { ...rest, effects: sugar.effects, origin: { actor, ...(chosen !== undefined ? { reason: chosen } : {}) }, ...(dryRun ? { dryRun: true } : {}) });
+    }
+    catch (e) {
+        throw stripEffectIndex(e);
+    }
+}
+/** `docs_create`'s document is the receipt's first revision (`new_ids["$new.0"]` is the same id); every other operation's is the one addressed. */
+export function createdDoc(receipt, path) {
+    const id = receipt.new_ids["$new.0"] ?? receipt.revisions[0]?.id;
+    if (id === undefined)
+        throw new Error("createdDoc: the receipt names no created document");
+    return { id, path, committed: true };
+}
+export function docOutcome(doc, path = doc.path) {
+    return { id: doc.id, path, committed: true };
+}
+/**
+ * Who links to the document BY PATH as written, and what the move's retarget
+ * rewrites — computed BEFORE the move from the current blocks (`planInboundRetarget`
+ * is pure, so it equals what the planner lowers for the same `move` effect).
+ */
+export function moveLinks(store, repoId, doc, toPath, retargetInbound = true) {
+    const to = canonicalDocPath(toPath);
+    const inbound = inboundLinksTo(store, repoId, doc.id, doc.path);
+    if (!retargetInbound || inbound.length === 0)
+        return { dangling: inbound, retargeted: null };
+    const plan = planInboundRetarget(store, doc.id, doc.path, to, inbound);
+    return { dangling: plan.dangling, retargeted: { blocks: plan.blocks, docs: plan.docs } };
+}
+//# sourceMappingURL=sugar.js.map

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

@@ -16,10 +16,12 @@ export interface MutDoc {
     frontmatterRaw: string | null;
     children: MutBlock[];
 }
+/** 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: string;
+    code: MutationErrorCode | string;
     data: Record<string, unknown>;
-    constructor(code: string, message: string, data?: Record<string, unknown>);
+    constructor(code: MutationErrorCode | string, message: string, data?: Record<string, unknown>);
 }
 /** Find a block by id anywhere in the doc; returns the block + its parent list. */
 export declare function locate(doc: MutDoc, blockId: string): {

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: "13.5";
+    readonly store: "14.1";
     readonly properties: "1.1";
     readonly graph: "1.1";
     readonly search: "2.0";
-    readonly mutate: "2.0";
-    readonly sync: "2.0";
-    readonly surface: "3.0";
-    readonly cli: "3.0";
+    readonly mutate: "3.3";
+    readonly sync: "2.2";
+    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: "13.5",
+    store: "14.1",
     properties: "1.1",
     graph: "1.1",
     search: "2.0",
-    mutate: "2.0",
-    sync: "2.0",
-    surface: "3.0",
-    cli: "3.0",
+    mutate: "3.3",
+    sync: "2.2",
+    surface: "4.4",
+    cli: "4.3",
 };
 //# sourceMappingURL=spec-versions.js.map