@omgbase/core 0.1.0

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

@@ -0,0 +1,41 @@
+import type { Query } from "@omgbase/oqx";
+import type { Store } from "../core/store/store.js";
+import type { SemanticVec } from "../search/cel/compile.js";
+export type OqxConsumer = "collect" | "count" | "exists" | "none" | "first" | "single";
+export type EmbedQuery = (text: string) => Promise<{
+    model: string;
+    vec: Float32Array;
+}>;
+export interface OqxHit {
+    id: string;
+    path: string;
+    [k: string]: unknown;
+}
+export interface OqxResult {
+    hits: OqxHit[];
+    truncated: boolean;
+    cursor: string | null;
+    consumer: OqxConsumer;
+    count?: number;
+    exists?: boolean;
+    /** The `none` consumer's result: true iff the query yields no rows. */
+    none?: boolean;
+    /** Present for a top-level `values` projection (`select <expr> values`): the
+     * bare projected values in page order, in place of `hits` (which is then
+     * empty). Paged/deduped exactly like hits — `truncated`/`cursor` apply. For
+     * first/single it holds zero or one value. */
+    values?: unknown[];
+}
+export interface OqxOptions {
+    limit?: number;
+    cursor?: string | null;
+    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;
+}
+export declare function collectSemanticPhrases(source: string): string[];
+export declare function oqxRun(store: Store, repoId: string, source: string, 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

@@ -0,0 +1,332 @@
+// omgbase's OQX entry point, served by `@omgbase/oqx`: parse the source, run it
+// through the in-memory engine over a store-backed DataContext (context.ts), and
+// shape the engine's result into omgbase's OqxResult (lean {id, path, …} hits,
+// keyset pagination, count/exists scalars). Same signature + shape as the former
+// in-tree compiler, so every caller and the corpus are unchanged.
+import { parse, PlannedEngine, InMemoryEngine, OqxError } from "@omgbase/oqx";
+import { makeStoreContext } from "./context.js";
+import { SQLiteQueryPlanner } from "./planner.js";
+import { FilterInvalid } from "../search/cel/parser.js";
+import { float32ToBlob } from "../core/vec.js";
+import { encodeCursor as encodeKeyset, decodeCursor as decodeKeyset } from "../core/cursor.js";
+// Row-scoped domain functions: authored as free calls (`text("x")`) that
+// implicitly reference the current row. `@omgbase/oqx` free functions receive no
+// row, so we rewrite them to `$self.fn(…)` (a method whose receiver is the row).
+const ROW_FNS = new Set([
+    "text", "semantic", "under", "under_heading", "within", "under_kind",
+    "yaml_path", "json_pointer", "has_edge", "has_anchor", "child_count", "parent_type",
+]);
+const selfRef = { kind: "ident", name: "$self" };
+function rewriteExpr(e) {
+    switch (e.kind) {
+        case "member": return { ...e, recv: rewriteExpr(e.recv) };
+        case "index": return { ...e, recv: rewriteExpr(e.recv), index: rewriteExpr(e.index) };
+        case "unary": return { ...e, expr: rewriteExpr(e.expr) };
+        case "binary":
+        case "logical":
+        case "in":
+            return { ...e, left: rewriteExpr(e.left), right: rewriteExpr(e.right) };
+        case "range":
+            return { ...e, lo: e.lo ? rewriteExpr(e.lo) : null, hi: e.hi ? rewriteExpr(e.hi) : null };
+        case "call": {
+            const recv = e.recv ? rewriteExpr(e.recv) : null;
+            const args = e.args.map(rewriteExpr);
+            if (recv === null && ROW_FNS.has(e.name))
+                return { kind: "call", recv: selfRef, name: e.name, args };
+            return { kind: "call", recv, name: e.name, args };
+        }
+        default: return e; // lit, ident, outer, binding
+    }
+}
+function rewriteWhere(w) {
+    switch (w.kind) {
+        case "and": return { kind: "and", parts: w.parts.map(rewriteWhere) };
+        case "or": return { kind: "or", parts: w.parts.map(rewriteWhere) };
+        case "not": return { kind: "not", expr: rewriteWhere(w.expr) };
+        case "scalar": return { kind: "scalar", expr: rewriteExpr(w.expr) };
+        case "op": return rewriteOp(w);
+    }
+}
+function rewriteOp(op) {
+    return { ...op, receiver: rewriteExpr(op.receiver), sub: rewriteSub(op.sub) };
+}
+function rewriteFollow(f) {
+    return {
+        ...f,
+        receiver: rewriteExpr(f.receiver),
+        where: f.where ? rewriteExpr(f.where) : null,
+        frontier: f.frontier ? rewriteExpr(f.frontier) : null,
+        by: f.by ? rewriteExpr(f.by) : null,
+    };
+}
+function rewriteSelect(items) {
+    return items.map((it) => it.kind === "field" ? { ...it, expr: rewriteExpr(it.expr) } : { ...it, op: rewriteOp(it.op) });
+}
+function rewriteSub(s) {
+    return {
+        from: s.from.map(rewriteExpr),
+        where: s.where ? rewriteWhere(s.where) : null,
+        select: rewriteSelect(s.select),
+        orderBy: s.orderBy ? s.orderBy.map((o) => ({ ...o, expr: rewriteExpr(o.expr) })) : null,
+        follow: s.follow ? rewriteFollow(s.follow) : null,
+        ...(s.values ? { values: true } : {}),
+        ...(s.limit ? { limit: rewriteExpr(s.limit) } : {}),
+        ...(s.offset ? { offset: rewriteExpr(s.offset) } : {}),
+    };
+}
+function rewriteQuery(q) {
+    return {
+        source: rewriteExpr(q.source),
+        from: q.from.map(rewriteExpr),
+        where: q.where ? rewriteWhere(q.where) : null,
+        select: rewriteSelect(q.select),
+        orderBy: q.orderBy ? q.orderBy.map((o) => ({ ...o, expr: rewriteExpr(o.expr) })) : null,
+        consumer: q.consumer,
+        follow: q.follow ? rewriteFollow(q.follow) : null,
+        ...(q.distinct ? { distinct: true } : {}),
+        ...(q.values ? { values: true } : {}),
+        ...(q.limit ? { limit: rewriteExpr(q.limit) } : {}),
+        ...(q.offset ? { offset: rewriteExpr(q.offset) } : {}),
+    };
+}
+// A top-level `limit`/`offset` on the collect path is applied by the runner (see
+// oqxRunInner), so it must be a plain number literal here — there is no row to
+// evaluate anything else against at the root, and omgbase queries carry no
+// bindings.
+function constBound(e, word) {
+    if (!e)
+        return null;
+    if (e.kind === "lit" && typeof e.value === "number" && Number.isInteger(e.value) && e.value >= 0)
+        return e.value;
+    throw new FilterInvalid(`top-level ${word} must be a non-negative integer literal`, "OQX");
+}
+// Distinct phrases referenced by `semantic("…")` (free calls in the raw parse).
+export function collectSemanticPhrases(source) {
+    const phrases = new Set();
+    const visitExpr = (e) => {
+        switch (e.kind) {
+            case "call":
+                if (e.recv === null && e.name === "semantic" && e.args[0]?.kind === "lit" && typeof e.args[0].value === "string") {
+                    phrases.add(e.args[0].value);
+                }
+                if (e.recv)
+                    visitExpr(e.recv);
+                e.args.forEach(visitExpr);
+                return;
+            case "member":
+                visitExpr(e.recv);
+                return;
+            case "index":
+                visitExpr(e.recv);
+                visitExpr(e.index);
+                return;
+            case "unary":
+                visitExpr(e.expr);
+                return;
+            case "binary":
+            case "logical":
+            case "in":
+                visitExpr(e.left);
+                visitExpr(e.right);
+                return;
+            case "range":
+                if (e.lo)
+                    visitExpr(e.lo);
+                if (e.hi)
+                    visitExpr(e.hi);
+                return;
+            default: return;
+        }
+    };
+    const visitWhere = (w) => {
+        switch (w.kind) {
+            case "and":
+            case "or":
+                w.parts.forEach(visitWhere);
+                return;
+            case "not":
+                visitWhere(w.expr);
+                return;
+            case "scalar":
+                visitExpr(w.expr);
+                return;
+            case "op":
+                visitOp(w);
+                return;
+        }
+    };
+    const visitOp = (op) => { visitExpr(op.receiver); visitSub(op.sub); };
+    const visitSub = (s) => {
+        s.from.forEach(visitExpr);
+        if (s.where)
+            visitWhere(s.where);
+        s.select.forEach((it) => it.kind === "field" ? visitExpr(it.expr) : visitOp(it.op));
+        if (s.orderBy)
+            s.orderBy.forEach((o) => visitExpr(o.expr));
+        if (s.follow) {
+            visitExpr(s.follow.receiver);
+            [s.follow.where, s.follow.frontier, s.follow.by].forEach((x) => x && visitExpr(x));
+        }
+    };
+    let q;
+    try {
+        q = parse(source);
+    }
+    catch {
+        return [];
+    }
+    visitExpr(q.source);
+    q.from.forEach(visitExpr);
+    if (q.where)
+        visitWhere(q.where);
+    q.select.forEach((it) => it.kind === "field" ? visitExpr(it.expr) : visitOp(it.op));
+    if (q.orderBy)
+        q.orderBy.forEach((o) => visitExpr(o.expr));
+    if (q.follow) {
+        visitExpr(q.follow.receiver);
+        [q.follow.where, q.follow.frontier, q.follow.by].forEach((x) => x && visitExpr(x));
+    }
+    return [...phrases];
+}
+const ID_ITEM = { kind: "field", name: "__oqx_id", expr: { kind: "ident", name: "$id" }, lift: 0 };
+const PATH_ITEM = { kind: "field", name: "__oqx_path", expr: { kind: "ident", name: "$path" }, lift: 0 };
+// 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
+// ordinary record field and is peeled off at the end.
+const VALUE_KEY = "__oqx_value";
+function toHit(row) {
+    const o = row;
+    const { __oqx_id, __oqx_path, ...rest } = o;
+    return { id: String(__oqx_id), path: String(__oqx_path ?? ""), ...rest };
+}
+// Top-level `select distinct`: dedup hits by their USER projection (every field
+// except the injected id/path), keeping the first (so the retained hit carries a
+// real id/path). Order-preserving.
+function dedupHitsByProjection(hits) {
+    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]]));
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(h);
+    }
+    return out;
+}
+export function oqxRun(store, repoId, source, opts = {}) {
+    try {
+        return oqxRunInner(store, repoId, source, opts);
+    }
+    catch (e) {
+        // Normalize the library's errors to omgbase's contract (filter_invalid).
+        if (e instanceof OqxError)
+            throw new FilterInvalid(e.message, "OQX");
+        throw e;
+    }
+}
+function oqxRunInner(store, repoId, source, opts) {
+    const parsed = rewriteQuery(parse(source));
+    const consumer = parsed.consumer;
+    const ctxOpts = opts.semanticVectors ? { semanticVectors: opts.semanticVectors } : {};
+    const ctx = makeStoreContext(store, repoId, ctxOpts);
+    // Tier-3 pushdown reduces the scan in SQL; the in-memory fallback finishes the
+    // residual (and runs anything not pushable), so results match a pure scan.
+    const engine = opts.plan === false
+        ? new InMemoryEngine(ctx)
+        : new PlannedEngine(new SQLiteQueryPlanner(store, repoId, ctxOpts), ctx);
+    if (consumer === "exists") {
+        const res = engine.run(parsed, []);
+        return { hits: [], truncated: false, cursor: null, consumer: "exists", exists: res.consumer === "exists" ? res.exists : false };
+    }
+    if (consumer === "count") {
+        const res = engine.run(parsed, []);
+        return { hits: [], truncated: false, cursor: null, consumer: "count", count: res.consumer === "count" ? res.count : 0 };
+    }
+    if (consumer === "none") {
+        const res = engine.run(parsed, []);
+        return { hits: [], truncated: false, cursor: null, consumer: "none", none: res.consumer === "none" ? res.none : true };
+    }
+    // collect / first / single: inject id + path so every hit carries them. A
+    // top-level `select distinct` is applied HERE, not in the engine: the injected
+    // id/path are unique per row and would defeat the engine's projection dedup, so
+    // we run without engine-distinct and dedup hits by their USER projection below,
+    // keeping the first row's id/path.
+    const topDistinct = !!parsed.distinct;
+    // A top-level `values` projection runs as a RECORD projection whose single
+    // item is renamed to VALUE_KEY (the engine's own values mode is switched off),
+    // so pagination and distinct work unchanged; the bare values are peeled off
+    // 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;
+    // 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
+    // limit 3` must be three distinct types). first/single keep theirs: the
+    // engine's offset-aware cap is exactly right for them.
+    const { limit: topLimit, offset: topOffset, ...unbounded } = parsed;
+    const base = consumer === "collect" ? unbounded : parsed;
+    const q = { ...base, distinct: false, values: false, select: [ID_ITEM, PATH_ITEM, ...userSelect] };
+    const res = engine.run(q, []);
+    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 };
+    }
+    // collect: keyset pagination on (path, id) when the order is the default.
+    let rows = (res.consumer === "collect" ? res.rows : []).map(toHit);
+    if (topDistinct)
+        rows = dedupHitsByProjection(rows);
+    // The query's own bound defines the result SET; the `limit`/`cursor` options
+    // then page within it.
+    const offset = constBound(topOffset, "offset") ?? 0;
+    const limit = constBound(topLimit, "limit");
+    if (offset || limit != null)
+        rows = rows.slice(offset, limit == null ? undefined : offset + limit);
+    const custom = !!parsed.orderBy && parsed.orderBy.length > 0;
+    const cap = opts.limit ?? 50;
+    let page = rows;
+    if (!custom && opts.cursor) {
+        const { path, id } = decodeCursor(opts.cursor);
+        page = page.filter((h) => h.path > path || (h.path === path && h.id > id));
+    }
+    const truncated = page.length > cap;
+    page = page.slice(0, cap);
+    const last = page[page.length - 1];
+    const cursor = truncated && last && !custom ? encodeCursor(last.path, last.id) : null;
+    if (topValues)
+        return { hits: [], truncated, cursor, consumer: "collect", values: page.map((h) => h[VALUE_KEY]) };
+    return { hits: page, truncated, cursor, consumer: "collect" };
+}
+export async function oqxRunAsync(store, repoId, source, opts = {}, embedQuery) {
+    const phrases = collectSemanticPhrases(source);
+    if (phrases.length === 0)
+        return oqxRun(store, repoId, source, opts);
+    if (!embedQuery)
+        throw new FilterInvalid("semantic(...) needs an embedding provider; none is configured", "OQX semantic");
+    const semanticVectors = new Map();
+    for (const phrase of phrases) {
+        const { model, vec } = await embedQuery(phrase);
+        semanticVectors.set(phrase, { model, vec: float32ToBlob(vec) });
+    }
+    return oqxRun(store, repoId, source, { ...opts, semanticVectors });
+}
+// The collect page's keyset is (path, id): the kernel's shared cursor encoding
+// (core/cursor.ts) with a two-part tuple. A malformed cursor is CursorInvalid,
+// which the MCP layer maps to filter_invalid.
+function encodeCursor(path, id) {
+    return encodeKeyset([path, id]);
+}
+function decodeCursor(cursor) {
+    const [path, id] = decodeKeyset(cursor, "query", 2);
+    return { path: path, id: id };
+}
+/** Parse an OQX source into the `@omgbase/oqx` AST (re-exported for callers). */
+export function parseOqx(source) {
+    return parse(source);
+}
+//# sourceMappingURL=run.js.map

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

@@ -0,0 +1,27 @@
+import type { Expr } from "@omgbase/oqx";
+/** SQL row domain, matching the store's tables. */
+export type Target = "docs" | "blocks" | "nodes" | "edges";
+/** The SQL aliases the compiler assigned to the current scope's row (`self`) and
+ * its owning document (`doc`). On the `docs` target the row IS the document, so
+ * both are the same alias. */
+export interface Aliases {
+    self: string;
+    doc: string;
+}
+export interface TranslateCtx extends Aliases {
+    target: Target;
+    /** Query bindings, used to resolve `${…}` interpolations (`{kind:"binding"}`)
+     * to their values (mirrors `@omgbase/oqx`'s `constValue`). */
+    params: readonly unknown[];
+}
+/** A SQL fragment plus its positional bind params, in statement order. */
+export interface Frag {
+    sql: string;
+    params: unknown[];
+}
+/** Translate an expression used as a VALUE (comparison operand, method receiver,
+ * function argument) to a SQL scalar. Returns null if not faithfully translatable. */
+export declare function translateValue(e: Expr, ctx: TranslateCtx): Frag | null;
+/** Translate an expression used as a boolean PREDICATE to a SQL boolean, or null
+ * if it cannot be pushed faithfully. Only positive, AND-safe forms are handled. */
+export declare function translatePredicate(e: Expr, ctx: TranslateCtx): Frag | null;