@omgbase/core 0.23.0 → 0.27.0

package/dist/src/mutate/frontmatter-parts.js

@@ -0,0 +1,237 @@
+// Frontmatter entries (spec/mutate §11.3 "Frontmatter entries", 3.6). The
+// effect planner's `set`/`unset frontmatter.<key>` edits ONE entry of a
+// document's frontmatter and leaves every other byte alone. To do that the
+// `frontmatter` block's raw (fences included) is cut into an ordered list of
+// PARTS — the opening fence line, one part per top-level YAML entry (with the
+// lines that continue it and the comment lines that lead it), the trailing
+// comment/blank lines, the closing fence — by a LEXICAL, line-based rule, not
+// a YAML parse: it is total (every frontmatter the store holds, valid YAML or
+// not, splits), byte-exact (the parts concatenate back to the raw, always) and
+// identical in both engines; what a line *means* is the properties layer's
+// business. Where the rule and YAML disagree (a pathological document) the
+// edit may touch a wider or narrower run of lines than a YAML parser would,
+// but never loses a byte of the other entries.
+//
+// Storage is untouched: a revision's frontmatter stays one blob (spec/store
+// 15.0). The parts are the planner's view of the bytes, computed from
+// `frontmatter_raw` when a frontmatter key is set or unset.
+/** Split text into lines, each keeping its own line ending (`\n` or `\r\n`); the last line has none. `""` → `[""]`. */
+export function splitLines(text) {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10) {
+            out.push(text.slice(start, i + 1));
+            start = i + 1;
+        }
+    }
+    out.push(text.slice(start));
+    return out;
+}
+/** A line without its line ending. */
+function content(line) {
+    return line.endsWith("\r\n") ? line.slice(0, -2) : line.endsWith("\n") ? line.slice(0, -1) : line;
+}
+/** The line ending of `line` (`"\r\n"`, `"\n"`, or `""` when it has none). */
+export function lineEndingOf(line) {
+    return line.endsWith("\r\n") ? "\r\n" : line.endsWith("\n") ? "\n" : "";
+}
+/** A blank line (empty, or spaces and tabs only). */
+export function isBlankLine(line) {
+    return /^[ \t]*$/.test(content(line));
+}
+/** A comment line — `#` in column 0. (An indented `#` is content: a block scalar's line, for one.) */
+export function isCommentLine(line) {
+    return content(line).startsWith("#");
+}
+/** A LEAD line: blank or comment — the lines that travel with the entry that follows them. */
+function isLeadLine(line) {
+    return isBlankLine(line) || isCommentLine(line);
+}
+// Characters that cannot begin a plain YAML key (flow indicators, anchors,
+// aliases, tags, block scalar indicators, directives, reserved).
+const NOT_A_PLAIN_KEY_START = new Set(["[", "]", "{", "}", ",", "&", "*", "!", "|", ">", "%", "@", "`"]);
+/**
+ * The entry boundary: the key of a column-0 line that opens a top-level
+ * mapping entry, or `null` when the line does not. A line opens an entry when
+ * it is not blank, not a comment, not a sequence item (`-` followed by a
+ * space, a tab or the end of the line), not an explicit key or value
+ * indicator (`?` / `:` the same way), not a document marker (`---` / `...`
+ * followed by whitespace or the end of the line), and reads as `<key>:`
+ * followed by a space, a tab or the end of the line — the key either
+ * - quoted: a `"…"` string (`\` escapes the next character) or a `'…'` string
+ *   (`''` is a literal quote), closed on the same line, then optional spaces/
+ *   tabs, then the colon; the key is the content with `\\` → `\`, `\"` → `"`
+ *   (double) or `''` → `'` (single) undone and every other escape kept as
+ *   written; or
+ * - plain: the text before the FIRST `:` that is followed by a space, a tab or
+ *   the end of the line, trailing spaces/tabs trimmed — non-empty, not
+ *   starting with a flow indicator, an anchor/alias/tag/block-scalar/
+ *   directive/reserved character (`[ ] { } , & * ! | > % @ \``) and not
+ *   containing ` #` or `\t#` (a comment would start there).
+ * Anything else — an indented line, a flow collection's continuation, a block
+ * scalar's content — is a continuation of the entry above it.
+ */
+export function entryKeyOf(line) {
+    const c = content(line);
+    if (c.length === 0)
+        return null;
+    const c0 = c[0];
+    if (c0 === " " || c0 === "\t" || c0 === "#")
+        return null;
+    if (c0 === '"' || c0 === "'")
+        return quotedKey(c, c0);
+    const c1 = c.length > 1 ? c[1] : "";
+    const wsOrEnd = (ch) => ch === "" || ch === " " || ch === "\t";
+    if ((c0 === "-" || c0 === "?" || c0 === ":") && wsOrEnd(c1))
+        return null;
+    if ((c.startsWith("---") || c.startsWith("...")) && wsOrEnd(c.length > 3 ? c[3] : ""))
+        return null;
+    if (NOT_A_PLAIN_KEY_START.has(c0))
+        return null;
+    const m = /^(.*?):(?:[ \t]|$)/.exec(c);
+    if (!m)
+        return null;
+    const key = m[1].replace(/[ \t]+$/, "");
+    if (key.length === 0 || / #|\t#/.test(key))
+        return null;
+    return key;
+}
+function quotedKey(c, quote) {
+    let i = 1;
+    let close = -1;
+    if (quote === '"') {
+        while (i < c.length) {
+            const ch = c[i];
+            if (ch === "\\")
+                i += 2;
+            else if (ch === '"') {
+                close = i;
+                break;
+            }
+            else
+                i++;
+        }
+    }
+    else {
+        while (i < c.length) {
+            if (c[i] === "'") {
+                if (c[i + 1] === "'")
+                    i += 2;
+                else {
+                    close = i;
+                    break;
+                }
+            }
+            else
+                i++;
+        }
+    }
+    if (close < 0)
+        return null;
+    if (!/^[ \t]*:(?:[ \t]|$)/.test(c.slice(close + 1)))
+        return null;
+    const inner = c.slice(1, close);
+    return quote === '"' ? inner.replace(/\\(["\\])/g, "$1") : inner.replace(/''/g, "'");
+}
+/**
+ * The frontmatter block's raw (fences included, no trailing line ending) → its
+ * parts, in order. The parts always concatenate back to `raw` byte for byte:
+ * every line of the raw lands in exactly one part.
+ *
+ * - part 0 is the opening fence line with its line ending, key `null`;
+ * - the last part is the closing fence line (no line ending), key `null`;
+ * - between them, the body lines: every line before the first entry line is
+ *   one part with key `null` (comments, blank lines, or — when no line opens
+ *   an entry: a bare scalar, a sequence — the whole body); then one part per
+ *   entry, from the first of the lead lines (blank / column-0 comment)
+ *   immediately preceding its key line (never reaching back past the
+ *   previous entry's key line) through the line before the next entry's
+ *   lead, the last entry ending before the trailing lead run; the trailing
+ *   lead run (blank / comment lines after the last entry's content) is one
+ *   part with key `null`.
+ *
+ * A raw with fewer than two lines (not a frontmatter block) is one part.
+ */
+export function splitFrontmatterRaw(raw) {
+    const lines = splitLines(raw);
+    if (lines.length < 2)
+        return [{ key: null, bytes: raw }];
+    const open = lines[0];
+    const close = lines[lines.length - 1];
+    const body = lines.slice(1, -1);
+    const parts = [{ key: null, bytes: open }];
+    const entryAt = body.map(entryKeyOf);
+    const entryIdx = [];
+    entryAt.forEach((k, i) => {
+        if (k !== null)
+            entryIdx.push(i);
+    });
+    if (entryIdx.length === 0) {
+        if (body.length > 0)
+            parts.push({ key: null, bytes: body.join("") });
+        parts.push({ key: null, bytes: close });
+        return parts;
+    }
+    // Where each entry's part starts: its lead run, bounded by the previous
+    // entry's key line; the first entry starts at its key line (the lines
+    // before it are the leading null part).
+    const starts = entryIdx.map((i, n) => {
+        if (n === 0)
+            return i;
+        const floor = entryIdx[n - 1] + 1;
+        let j = i;
+        while (j - 1 >= floor && isLeadLine(body[j - 1]))
+            j--;
+        return j;
+    });
+    // The trailing null part: the lead run after the last entry's key line.
+    let tail = body.length;
+    const lastKey = entryIdx[entryIdx.length - 1];
+    while (tail - 1 > lastKey && isLeadLine(body[tail - 1]))
+        tail--;
+    if (starts[0] > 0)
+        parts.push({ key: null, bytes: body.slice(0, starts[0]).join("") });
+    entryIdx.forEach((i, n) => {
+        const end = n + 1 < starts.length ? starts[n + 1] : tail;
+        parts.push({ key: entryAt[i], bytes: body.slice(starts[n], end).join("") });
+    });
+    if (tail < body.length)
+        parts.push({ key: null, bytes: body.slice(tail).join("") });
+    parts.push({ key: null, bytes: close });
+    return parts;
+}
+/** The inverse of {@link splitFrontmatterRaw}: the parts' bytes concatenated. */
+export function joinFrontmatterParts(parts) {
+    return parts.map((p) => p.bytes).join("");
+}
+/**
+ * The frontmatter block's raw and its trailing trivia, out of a document's
+ * `frontmatter_raw` (`raw + docs.frontmatter_trivia`, spec/mutate §2): the
+ * closing fence is the first line after the opening one that is `---`
+ * followed only by spaces/tabs (the format layer's rule); the raw ends with
+ * that line's content, the trivia is everything after. `null` when no closing
+ * fence is found (not a frontmatter the format layer would have produced).
+ */
+export function splitFrontmatterTrivia(frontmatterRaw) {
+    const lines = splitLines(frontmatterRaw);
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^---[ \t]*$/.test(content(line))) {
+            const upto = lines.slice(0, i).join("") + content(line);
+            return { raw: upto, trivia: frontmatterRaw.slice(upto.length) };
+        }
+    }
+    return null;
+}
+/** The lines of a part that LEAD its key line (blank / column-0 comment lines), as one string; `""` for a part without a key. */
+export function leadOf(part) {
+    if (part.key === null)
+        return "";
+    const lines = splitLines(part.bytes);
+    let n = 0;
+    while (n < lines.length - 1 && isLeadLine(lines[n]))
+        n++;
+    return lines.slice(0, n).join("");
+}
+//# sourceMappingURL=frontmatter-parts.js.map

package/dist/src/mutate/load.js

@@ -1,3 +1,4 @@
+import { currentFrontmatterRaw } from "../core/read/document.js";
 export function loadMutDoc(db, docId) {
     const doc = db.prepare("SELECT doc_id, path, format, leading_trivia, frontmatter_trivia, current_rev FROM docs WHERE doc_id = ? AND deleted_commit IS NULL").get(docId);
     if (!doc)
@@ -44,15 +45,14 @@ export function loadMutDoc(db, docId) {
     }
     let frontmatterRaw = null;
     if (doc.current_rev) {
-        const rev = db.prepare("SELECT frontmatter_blob FROM revisions WHERE rev_id = ?").get(doc.current_rev);
-        if (rev?.frontmatter_blob) {
-            const fm = blob.get(rev.frontmatter_blob);
-            // Append the exact stored separator (docs.frontmatter_trivia) so the
-            // write path round-trips byte-for-byte. Ingest always captures it when a
-            // frontmatter block exists, so the ?? "" is just a type guard.
-            if (fm)
-                frontmatterRaw = fm.bytes.toString("utf8") + (doc.frontmatter_trivia ?? "");
-        }
+        // The current revision's frontmatter, resolved when stored as a delta
+        // (spec/store §6.1, 16.0). Append the exact stored separator
+        // (docs.frontmatter_trivia) so the write path round-trips byte-for-byte.
+        // Ingest always captures it when a frontmatter block exists, so the ?? ""
+        // is just a type guard.
+        const fm = currentFrontmatterRaw(db, doc.current_rev);
+        if (fm !== null)
+            frontmatterRaw = fm + (doc.frontmatter_trivia ?? "");
     }
     return {
         docId: doc.doc_id,

package/dist/src/mutate/select.js

@@ -1,5 +1,5 @@
 import { OqxError, parse } from "@omgbase/oqx";
-import { checkRootSpellings, oqxRunQuery, reservedAlias } from "../oqx-js/run.js";
+import { TUPLE_HINT, bracketListAsTuple, checkRootSpellings, oqxRunQuery, reservedAlias } from "../oqx-js/run.js";
 import { rootTarget } from "../oqx-js/planner.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 import { EFFECT_OPS, EXPRESSION_LEADER, bareTarget, effectInvalid, findDocumentTarget, isNewSymbol, isTargetId, looksLikePath, validateEffect, validateTarget, } from "./effects.js";
@@ -545,8 +545,14 @@ function admitSelector(select, request) {
         checkRootSpellings(raw);
     }
     catch (e) {
-        if (e instanceof OqxError)
-            throw selectionInvalid(`select: ${e.message}`);
+        if (e instanceof OqxError) {
+            // (spec/surface 4.11) `id in ["a", "b"]` — the bracket list rewritten to a
+            // tuple is the `fix` (the same request over the corrected selector).
+            const rewritten = bracketListAsTuple(select, e.message);
+            if (rewritten === null)
+                throw selectionInvalid(`select: ${e.message}`);
+            throw selectionInvalid(`select: ${e.message}${TUPLE_HINT}`, request === undefined ? {} : { fix: fixRequest({ ...request, select: rewritten }) });
+        }
         if (e instanceof FilterInvalid)
             throw selectionInvalid(`select: ${e.message}`);
         throw e;
@@ -616,7 +622,11 @@ export function compileSelection(store, repoId, select, expectRaw, templatesRaw)
             fix: fixRequest({ select, effects: templatesRaw, expect: { max: count } }),
         });
     }
-    // Row → effects: hits in result order × templates in order (k = h·T + t).
+    // Row → effects: hits in result order × templates in order (k = h·T + t). A
+    // selector with `flatten` (oqx 0.25; §11.8) fans out per FLATTENED row: each
+    // hit is the parent row (its `id`/`path`), the slot items read the bound name
+    // (`-> tag`) in the flattened scope, and `expect.max` — the page bound above —
+    // counts the flattened hits.
     const effects = [];
     const origins = [];
     hits.forEach((hit) => {

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

@@ -45,7 +45,9 @@ function tagAll(rows, t) {
 // (`children`, `blocks`, `out_links`, `doc`, `frontmatter`, …) always followed:
 // a bare name that is an engine attribute reads the engine's value, never the
 // author's. The attributes: every row's `id`/`path`; docs' and blocks' `raw`/
-// `hash`/`updated_at`; docs' `title` (the computed title) and `tags` (authored
+// `hash`/`updated_at`/`created_at` (4.10: the commit `ts` of the thing's first
+// revision / earliest `block_changes` row — "first observed by omgbase", not a
+// filesystem time); docs' `title` (the computed title) and `tags` (authored
 // tags ∪ body hashtags) and `format`; a foreign key named for what it is
 // (`doc_id`, `block_id`, `via_id`, `dst_id`, `dst_path`, `uri`), a column its
 // column (`type`, `text`, `depth`, `ordinal`, `kind`, `predicate`, `field`).
@@ -60,8 +62,8 @@ function tagAll(rows, t) {
 // target name — `docs`, `links`, … — is a loud error of its own (root-row.ts).
 // `revisions` on a document is a RELATION (its revision list, §1.2, 4.7) in
 // `rel.docs` below, and names.ts's `RELATIONS.docs` knows it as one.
-const DOC_ATTRIBUTES = new Set(["id", "path", "raw", "hash", "updated_at", "title", "tags", "format"]);
-const BLOCK_ATTRIBUTES = new Set(["id", "path", "raw", "hash", "updated_at", "doc_id", "type", "text", "attrs", "depth", "ordinal"]);
+const DOC_ATTRIBUTES = new Set(["id", "path", "raw", "hash", "updated_at", "created_at", "title", "tags", "format"]);
+const BLOCK_ATTRIBUTES = new Set(["id", "path", "raw", "hash", "updated_at", "created_at", "doc_id", "type", "text", "attrs", "depth", "ordinal"]);
 const NODE_ATTRIBUTES = new Set(["id", "path", "doc_id", "block_id", "kind", "name", "value", "attrs"]);
 const EDGE_ATTRIBUTES = new Set(["id", "path", "doc_id", "block_id", "via_id", "dst_id", "dst_path", "uri", "field", "dst_kind", "predicate", "provenance", "anchor"]);
 // The history target (spec/surface §1.2, 4.7): a revision row's own columns
@@ -449,6 +451,18 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return tag(load(), "blocks");
         return lazyOwner({ block_id: row.block_id, doc_id: row.doc_id, __path: row.__path }, "blocks", load);
     };
+    // `block` on a link row (spec/surface §1.2, 4.11): the SOURCE block the link
+    // was written in — the blocks row `block_id` (the edge's `src_block`) names,
+    // in the source document (`__path` is already the block's document path) —
+    // mirroring `doc`; absent when the link has none (a frontmatter link).
+    const linkBlock = (row) => {
+        if (!row.src_block)
+            return undefined;
+        const load = () => one(`SELECT b.*, d.path AS __path FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ?`, row.src_block);
+        if (typeof row.__path !== "string")
+            return tag(load(), "blocks");
+        return lazyOwner({ block_id: row.src_block, doc_id: row.src_doc, __path: row.__path }, "blocks", load);
+    };
     // ---- engine attributes -----------------------------------------------------
     // Bare, snake_case, winning on collision (see the name rule above; spec/surface
     // §1.2, 3.0). `path` (and the edge field `dst_path`) is the REFERENCE form
@@ -464,6 +478,12 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 case "path": return referencePath(String(row.path));
                 case "hash": return row.file_hash == null ? null : hex(row.file_hash);
                 case "updated_at": return scalar(`SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.rev_id = ?`, row.current_rev) ?? null;
+                // `created_at` (4.10): the commit `ts` of the document's first revision
+                // (`seq = 1`, the row `revisions first { ts values }` reads) — when
+                // omgbase first observed the document, not a filesystem time. The
+                // retention squash (spec/store §7.1, 15.0) keeps every revision and
+                // commit row, so the value survives archiving.
+                case "created_at": return scalar(`SELECT c.ts FROM revisions r JOIN commits c ON c.commit_id = r.commit_id WHERE r.doc_id = ? AND r.seq = 1`, row.doc_id) ?? null;
                 // `raw`: the exact file bytes (spec/store §6.1, frontmatter included).
                 case "raw": return docsRead(store, String(row.doc_id))?.raw ?? null;
                 // `title`: the computed title (spec/properties §3.3 — the authored
@@ -487,6 +507,13 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 case "raw": return row.raw_hash == null ? null : scalar(`SELECT bytes FROM blobs WHERE hash = ?`, row.raw_hash)?.toString("utf8") ?? null;
                 case "hash": return row.raw_hash == null ? null : hex(row.raw_hash);
                 case "updated_at": return scalar(`SELECT MAX(c.ts) FROM block_changes bc JOIN commits c ON c.commit_id = bc.commit_id WHERE bc.block_id = ?`, row.block_id) ?? null;
+                // `created_at` (4.10): the EARLIEST commit `ts` among the block's
+                // `block_changes` — the same join as `updated_at` under MIN: the commit
+                // that first wrote the id (`inserted`, or the split/merge lineage row
+                // that minted it). Store 14.2 keeps that row and the 15.0 squash keeps
+                // each block's earliest row (spec/store §7.1), so it survives archiving;
+                // a resurrected block keeps its original creation.
+                case "created_at": return scalar(`SELECT MIN(c.ts) FROM block_changes bc JOIN commits c ON c.commit_id = bc.commit_id WHERE bc.block_id = ?`, row.block_id) ?? null;
                 case "doc_id": return row.doc_id;
                 case "type": return row.type;
                 case "text": return row.text;
@@ -613,6 +640,8 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return owningBlock(r) ?? ABSENT_SINGLE;
         if (t === "links" && key === "dst")
             return destinationDoc(r) ?? ABSENT_SINGLE;
+        if (t === "links" && key === "block")
+            return linkBlock(r) ?? ABSENT_SINGLE;
         // relations.
         const rels = rel[t];
         if (rels[key])

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

@@ -41,7 +41,7 @@ export const HANDLES = {
     docs: { doc: "docs" },
     blocks: { block: "blocks", doc: "docs" },
     nodes: { section: "nodes", doc: "docs", block: "blocks" },
-    links: { doc: "docs", dst: "docs" },
+    links: { doc: "docs", dst: "docs", block: "blocks" },
     revisions: { doc: "docs" },
 };
 /** The kinds whose row shape is closed: no authored data reaches a row by bare name. */

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

@@ -97,6 +97,9 @@ function subMayRaise(s, target) {
         return true;
     if (s.having && whereMayRaise(s.having, target, false))
         return true;
+    // A flattened block (oqx 0.25) evaluates each `flatten` expression per row.
+    if (s.flatten.some((f) => exprMayRaise(f.expr, target, false)))
+        return true;
     if (s.limit && exprMayRaise(s.limit, target, false))
         return true;
     if (s.offset && exprMayRaise(s.offset, target, false))
@@ -158,13 +161,14 @@ export class SQLiteQueryPlanner {
     }
     plan(query, params) {
         // Only simple top-level scans: no follow, no `from E` re-projection, no
-        // `group by` (oqx 0.24). A grouped query is declined whole: its `where`
-        // conjuncts could be pushed (grouping happens after them, so the residual
-        // would group the produced rows correctly), but a pushed conjunct that
-        // empties the scan would hide an eval error an aggregate or `having` raises
-        // in memory (`sum` over a string) — decline (c) extended to the post-group
-        // clauses. SQL `GROUP BY` pushdown is a later round.
-        if (query.follow || query.from.length > 0 || query.groupBy)
+        // `group by` (oqx 0.24), no `flatten` (oqx 0.25). A grouped or flattened
+        // query is declined whole: its `where` conjuncts could be pushed (the fan-out
+        // and the grouping happen after them, so the residual would flatten and
+        // group the produced rows correctly), but a pushed conjunct that empties the
+        // scan would hide an eval error a `flatten` expression, an aggregate or
+        // `having` raises in memory (`x!`, `sum` over a string) — decline (c)
+        // extended to the post-where clauses. SQL pushdown of either is a later round.
+        if (query.follow || query.from.length > 0 || query.groupBy || query.flatten.length > 0)
             return null;
         const target = rootTarget(query.source);
         if (!target)

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

@@ -69,6 +69,11 @@ export interface OqxOptions {
      * 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;
+    /** The `query` call as the caller received it (spec/surface 4.11): the
+     * arguments a corrected call is spelled from when a parse error can be fixed
+     * (`data.fix`, the bracket-list rule below). Absent, the message still gains
+     * its hint and no `fix` is composed. */
+    request?: Record<string, unknown>;
 }
 export declare function rootPathLiterals(e: Expr): Expr;
 export declare function checkRootSpellings(q: Query): void;
@@ -78,6 +83,9 @@ export declare function reservedAlias(items: readonly SelectItem[]): FilterInval
 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;
+export declare const TUPLE_HINT = "; a list is written as a tuple: (\u2026)";
+/** The source with the bracket list at the error's offset rewritten to a tuple, or null when the rule does not apply. */
+export declare function bracketListAsTuple(source: string, message: string): string | null;
 /**
  * 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

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

@@ -14,6 +14,7 @@ import { FilterInvalid } from "../search/cel/parser.js";
 import { float32ToBlob } from "../core/vec.js";
 import { encodeCursor as encodeKeyset, decodePathCursor } from "../core/cursor.js";
 import { referencePath } from "../core/paths.js";
+import { canonicalJson } from "../mutate/canonical.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)
@@ -312,10 +313,95 @@ export function oqxRun(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 parseInvalid(source, e, opts.request);
         throw e;
     }
 }
+// ---- the bracket-list fix (spec/surface §4 "Error data", 4.11) ----------------------
+//
+// OQX has no list literal; a tuple `("a", "b")` is the collection (`spec/oqx`
+// SEMANTICS §3b), so `id in ["a", "b"]` — the SQL habit — is the parse error
+// `unexpected '[' — expected a value (at offset N)`. When the source at N opens a
+// bracketed comma list of LITERALS closed by `]` (two or more members, each a
+// string, number, `true`, `false` or `null`; nothing nested), the message gains
+// `; a list is written as a tuple: (…)` and, when the request is known, the
+// error carries `fix`: the same request with that `[…]` rewritten to `(…)`.
+// Anything else at N (an identifier member, a nested bracket, one member, an
+// unclosed list) is the parser's error as it stands.
+const BRACKET_ERROR = /^unexpected '\[' — expected a value \(at offset (\d+)\)$/;
+export const TUPLE_HINT = "; a list is written as a tuple: (…)";
+/** The source with the bracket list at the error's offset rewritten to a tuple, or null when the rule does not apply. */
+export function bracketListAsTuple(source, message) {
+    const m = BRACKET_ERROR.exec(message);
+    if (!m)
+        return null;
+    const cps = Array.from(source);
+    const open = Number(m[1]);
+    if (cps[open] !== "[")
+        return null;
+    let i = open + 1;
+    let members = 0;
+    for (;;) {
+        i = skipSpaces(cps, i);
+        const end = literalEnd(cps, i);
+        if (end === null)
+            return null;
+        members++;
+        i = skipSpaces(cps, end);
+        if (cps[i] === ",") {
+            i++;
+            continue;
+        }
+        if (cps[i] === "]")
+            break;
+        return null;
+    }
+    if (members < 2)
+        return null;
+    cps[open] = "(";
+    cps[i] = ")";
+    return cps.join("");
+}
+function skipSpaces(cps, i) {
+    while (i < cps.length && /\s/.test(cps[i]))
+        i++;
+    return i;
+}
+/** The index just past one OQX literal starting at `i` (a string in either quote with `\<c>` escapes, an unsigned number, `true`/`false`/`null`), or null. */
+function literalEnd(cps, i) {
+    const c = cps[i];
+    if (c === undefined)
+        return null;
+    if (c === '"' || c === "'") {
+        let j = i + 1;
+        while (j < cps.length) {
+            if (cps[j] === "\\")
+                j += 2;
+            else if (cps[j] === c)
+                return j + 1;
+            else
+                j++;
+        }
+        return null;
+    }
+    if (/[0-9]/.test(c)) {
+        const m = /^[0-9]+(\.[0-9]+)?([eE][+-]?[0-9]+)?/.exec(cps.slice(i).join(""));
+        return m ? i + Array.from(m[0]).length : null;
+    }
+    for (const word of ["true", "false", "null"]) {
+        if (cps.slice(i, i + word.length).join("") === word && !/[A-Za-z0-9_$]/.test(cps[i + word.length] ?? ""))
+            return i + word.length;
+    }
+    return null;
+}
+/** The surface's `filter_invalid` for a parse error: the library's message, plus the tuple hint and `fix` when the bracket rule applies. */
+function parseInvalid(source, e, request) {
+    const rewritten = bracketListAsTuple(source, e.message);
+    if (rewritten === null)
+        return new FilterInvalid(e.message, "OQX");
+    const fix = request !== undefined ? canonicalJson({ ...request, query: rewritten }) : undefined;
+    return new FilterInvalid(e.message + TUPLE_HINT, "OQX", fix);
+}
 function oqxRunInner(store, repoId, source, opts) {
     const raw = parse(source);
     const reserved = reservedAlias(raw.select);
@@ -384,6 +470,21 @@ function runResolved(store, repoId, raw, opts) {
     // under a custom `order by`). `distinct` cannot occur (a parse error).
     if (parsed.groupBy)
         return runGrouped(engine, parsed, consumer, opts);
+    // A flattened query (oqx 0.25, SEMANTICS §25) yields the parent rows, one per
+    // element: a hit is still a store row, so the envelope is injected as usual
+    // and repeats per element (Dataview's `TABLE … FLATTEN`). What changes is
+    // uniqueness — `(path, id)` no longer names one hit — so the keyset cursor
+    // cannot land inside a document's elements: a flattened query pages
+    // positionally with a null cursor, as a grouped query and a custom `order by`
+    // do (a keyset extended with the flatten ordinal is a later round). A bound
+    // name of `id` or `path` would shadow the envelope's own reads (the name
+    // shadows a same-named row property on the flattened row): refused, like a
+    // projection that collides with the envelope.
+    const flattened = parsed.flatten.length > 0;
+    for (const f of parsed.flatten) {
+        if (ENVELOPE_KEYS.has(f.name))
+            throw new FilterInvalid(`flatten \`as ${f.name}\` collides with the hit envelope — a flattened row is still the row, whose \`${f.name}\` the envelope reads; bind another name`, "OQX");
+    }
     // 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
@@ -437,7 +538,7 @@ function runResolved(store, repoId, raw, opts) {
     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 custom = (!!parsed.orderBy && parsed.orderBy.length > 0) || flattened;
     const cap = opts.limit ?? 50;
     let page = rows;
     if (!custom && opts.cursor) {