@omgbase/core 0.19.0 → 0.23.0

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

@@ -13,7 +13,7 @@
 // pushes the hot predicates down; both must agree (conformance suite).
 import { semantics } from "@omgbase/oqx";
 import { storeIndexFor } from "./store-index.js";
-import { TARGETS, bareTargetMessage } from "./root-row.js";
+import { ROOTS, ROOT_NAMES, bareTargetMessage } from "./root-row.js";
 import { COLS, FROM, ORDER, guards } from "./sql/scan.js";
 import { detectRange } from "../core/store/properties.js";
 import { docsRead } from "../core/read/document.js";
@@ -23,6 +23,7 @@ import { sanitizeFtsQuery } from "../search/fts-query.js";
 import { cosineBytes } from "../core/vec.js";
 import { ctxHashHex } from "../search/embeddings.js";
 import { makeBlockContextResolver } from "../search/tasks.js";
+import { dateFunction, dateMethod } from "./dates.js";
 const TARGET = Symbol("oqx.target");
 const ROOT_ROW = Symbol("oqx.rootRow");
 const PROP_SOURCE = Symbol("oqx.propSource");
@@ -57,15 +58,31 @@ function tagAll(rows, t) {
 // `hash`/`raw` is simply the engine's attribute (before this batch of 3.0 the
 // attributes were `$`-prefixed and the bare spelling was an error, §9). A bare
 // 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 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
+// under the names `docs_history` already uses (`rev`, `seq`, `commit`, `origin`,
+// `actor`, `hash`), the commit's `ts` and `reason`, `is_current`, and (4.9)
+// `archived` — the revision's bodies live in an archive segment (spec/store §7
+// "Retention"; `docs_read { at }` reads through it when attached).
+const REVISION_ATTRIBUTES = new Set(["id", "path", "rev", "seq", "doc_id", "commit", "ts", "origin", "actor", "reason", "hash", "is_current", "archived"]);
 /** The engine attributes per kind (spec/surface §1.2 table). Exported so the
  * translator's tests pin the two against each other. */
 export const ATTRIBUTES = {
-    docs: DOC_ATTRIBUTES, blocks: BLOCK_ATTRIBUTES, nodes: NODE_ATTRIBUTES, links: EDGE_ATTRIBUTES,
+    docs: DOC_ATTRIBUTES, blocks: BLOCK_ATTRIBUTES, nodes: NODE_ATTRIBUTES, links: EDGE_ATTRIBUTES, revisions: REVISION_ATTRIBUTES,
 };
+// The revisions scan (spec/surface §1.1, 4.7): every revision of every document
+// of the repository — tombstoned documents included, history is history — with
+// its commit, in the keyset order `(path as of the revision, rev_id)`. The
+// `revisions` table carries no `repo_id`, so the repository guard joins `docs`.
+// `is_current` is `docs_history`'s `isCurrent`: the revision is the document's
+// `current_rev`.
+const REVISION_COLS = "r.rev_id, r.doc_id, r.seq, r.rendered_hash, r.path, r.commit_id, c.ts, c.origin, c.actor, c.reason, (d.current_rev = r.rev_id) AS is_current, (r.archive IS NOT NULL) AS archived";
+const REVISION_FROM = "revisions r JOIN docs d ON d.doc_id = r.doc_id JOIN commits c ON c.commit_id = r.commit_id";
 /** The source handles of a document (§1.2): `data` is the merged authored view
  * (frontmatter + inline), the other two one source each. */
 export const SOURCE_HANDLES = new Set(["data", "frontmatter", "inline"]);
@@ -87,11 +104,17 @@ export function makeStoreContext(store, repoId, opts = {}) {
         return Object.values(r)[0];
     };
     // ---- root collections (the shared scan shape of sql/scan.ts: live rows of
-    // this repo, ordered for a stable (path, id) default) -----------------------
+    // this repo, ordered for a stable (path, id) default; the revisions scan is
+    // its own statement above, in the same (path, id) keyset order) -------------
     const scan = (t) => {
+        if (t === "revisions")
+            return tagAll(all(`SELECT ${REVISION_COLS} FROM ${REVISION_FROM} WHERE d.repo_id = ? ORDER BY r.path, r.rev_id`, repoId), t);
         const g = guards(t, repoId);
         return tagAll(all(`SELECT ${COLS[t]} FROM ${FROM[t]} WHERE ${g.sql} ORDER BY ${ORDER[t]}`, ...g.params), t);
     };
+    // A document's revisions (the `revisions` relation of a docs row, §1.2, 4.7):
+    // oldest first, as `docs_history` lists them.
+    const docRevisions = (docId) => tagAll(all(`SELECT ${REVISION_COLS} FROM ${REVISION_FROM} WHERE r.doc_id = ? ORDER BY r.seq`, docId), "revisions");
     // A root scan is handed out LAZILY: an array (a `Proxy` over one — `Array.isArray`,
     // iteration, indexing, `length`, rendering all see a plain array of tagged
     // rows) that runs its SELECT on first use. The engine's optimizer asks
@@ -138,21 +161,14 @@ export function makeStoreContext(store, repoId, opts = {}) {
         rootScans.set(proxy, { target: t, rows: fill });
         return proxy;
     };
-    const rootFns = {
-        docs: () => lazyRoot("docs"), blocks: () => lazyRoot("blocks"), nodes: () => lazyRoot("nodes"), links: () => lazyRoot("links"),
-    };
+    const rootFns = Object.fromEntries(ROOT_NAMES.map((t) => [t, () => lazyRoot(t)]));
     // The root row (spec/surface §1.1, 2.0; spec/oqx 0.18 `rootObject`): the
     // repository, reached as `^$it` from a top-level row (`0^$it` from any depth).
-    // Its own enumerable keys are the four collections — lazy getters, so
-    // `entries(^$it)` names them without running a scan and `^$it.docs` is the
-    // same handle as `^docs` — and `get` answers `id` with the repository id (an
-    // attribute, not an entry). Tagged so `get` recognizes it.
-    const rootRow = Object.defineProperties({ [ROOT_ROW]: true }, {
-        docs: { enumerable: true, get: () => lazyRoot("docs") },
-        blocks: { enumerable: true, get: () => lazyRoot("blocks") },
-        nodes: { enumerable: true, get: () => lazyRoot("nodes") },
-        links: { enumerable: true, get: () => lazyRoot("links") },
-    });
+    // Its own enumerable keys are the five collections in `ROOT_NAMES` order —
+    // lazy getters, so `entries(^$it)` names them without running a scan and
+    // `^$it.docs` is the same handle as `^docs` — and `get` answers `id` with the
+    // repository id (an attribute, not an entry). Tagged so `get` recognizes it.
+    const rootRow = Object.defineProperties({ [ROOT_ROW]: true }, Object.fromEntries(ROOT_NAMES.map((t) => [t, { enumerable: true, get: () => lazyRoot(t) }])));
     // ---- attrs / property decoding --------------------------------------------
     const parseJson = (v) => {
         if (typeof v !== "string")
@@ -298,6 +314,8 @@ export function makeStoreContext(store, repoId, opts = {}) {
         docs: {
             nodes: (r) => docNodesInOrder(r.doc_id, r.path),
             blocks: (r) => tagAll(docBlocksPreorder(r.doc_id, r.path).map((x) => x.row), "blocks"),
+            // A document's revision list (spec/surface §1.2, 4.7), oldest first.
+            revisions: (r) => docRevisions(r.doc_id),
             // The linked / linking DOCUMENTS are reached through the link rows (3.0
             // follow-up, §9: the `out` / `in` relations are gone): `out_links collect
             // distinct { from dst }` and `in_links collect distinct { from doc }`.
@@ -351,6 +369,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
             },
         },
         links: {},
+        revisions: {},
     };
     const jattr = (row, k) => {
         const a = row.attrs;
@@ -417,6 +436,11 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return undefined;
         return tag(one(`SELECT * FROM docs WHERE doc_id = ?`, row.dst_node), "docs");
     };
+    // `doc` on a revision row (spec/surface §1.2, 4.7): the document's CURRENT
+    // live row — the revision's `path` may be an earlier one — and absent (the
+    // single-with-no-row marker, as `dst` on a dangling link) for a tombstoned
+    // document: its revisions are rows, `doc == null` tells them apart.
+    const revisionDoc = (row) => tag(one(`SELECT * FROM docs WHERE doc_id = ? AND deleted_commit IS NULL`, row.doc_id), "docs");
     const owningBlock = (row) => {
         if (!row.block_id)
             return undefined;
@@ -501,6 +525,23 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 case "dst_kind":
                 case "anchor": return row[name];
             }
+        if (t === "revisions")
+            switch (name) {
+                // the `revisions` × `commits` columns under docs_history's names (spec/surface §1.2, 4.7).
+                case "id":
+                case "rev": return row.rev_id;
+                case "path": return referencePath(String(row.path));
+                case "seq": return row.seq;
+                case "doc_id": return row.doc_id;
+                case "commit": return row.commit_id;
+                case "ts": return row.ts;
+                case "origin": return row.origin;
+                case "actor": return row.actor ?? null;
+                case "reason": return row.reason ?? null;
+                case "hash": return hex(row.rendered_hash);
+                case "is_current": return row.is_current === 1 || row.is_current === true;
+                case "archived": return row.archived === 1 || row.archived === true;
+            }
         return undefined;
     };
     // `tags` on a document: authored ∪ hashtags, each list as the property rule
@@ -561,8 +602,11 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return r;
         if (t === "nodes" && key === "section")
             return r;
-        // reach-through to owning entities, and from a link row to its destination —
-        // statically single relations: absent is the single-with-no-row marker.
+        // reach-through to owning entities, from a link row to its destination and
+        // from a revision to its document's current row — statically single
+        // relations: absent is the single-with-no-row marker.
+        if (t === "revisions" && key === "doc")
+            return revisionDoc(r) ?? ABSENT_SINGLE;
         if (t !== "docs" && key === "doc")
             return owningDoc(r) ?? ABSENT_SINGLE;
         if (t === "nodes" && key === "block")
@@ -576,9 +620,9 @@ export function makeStoreContext(store, repoId, opts = {}) {
         // A bare target name that is not one of this row's relations reads a
         // property the row has none of (spec/surface §1.1, 2.0): loud, naming the
         // root-row spelling. `docs`/`links` never get here (run.ts refuses them
-        // statically); `blocks` on a block or edge row and `nodes` on a node or
-        // edge row do.
-        if (TARGETS.has(key))
+        // statically); `blocks` on a block or edge row, `nodes` on a node or edge
+        // row and `revisions` on anything but a document do.
+        if (ROOTS.has(key))
             throw new FilterInvalid(bareTargetMessage(key, null), "OQX");
         // the author's data.
         if (t === "docs") {
@@ -652,8 +696,8 @@ export function makeStoreContext(store, repoId, opts = {}) {
         }
     };
     const textMatch = (t, r, terms) => {
-        if (t === "links")
-            throw new FilterInvalid("text(...) is not available on the links target", "10 §5");
+        if (t === "links" || t === "revisions")
+            throw new FilterInvalid(`text(...) is not available on the ${t} target`, "10 §5");
         const match = sanitizeFtsQuery(terms);
         if (match === "")
             return false;
@@ -676,7 +720,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
         return one(`SELECT vec FROM embeddings WHERE content_hash = ? AND ctx_hash = ? AND model = ?`, r.raw_hash, Buffer.from(ctxHashHex(ctx), "hex"), model);
     };
     const semanticScore = (t, r, phrase) => {
-        if (t === "nodes" || t === "links")
+        if (t === "nodes" || t === "links" || t === "revisions")
             throw new FilterInvalid("semantic(...) is available on the docs and blocks targets", "OQX semantic");
         const resolved = sv?.get(phrase);
         if (!resolved)
@@ -771,10 +815,12 @@ export function makeStoreContext(store, repoId, opts = {}) {
             return row.node_id;
         if (t === "links")
             return row.edge_id;
+        if (t === "revisions")
+            return row.rev_id;
         return row;
     };
     return {
-        // The root scope's names (spec/oqx §2 step 5 at the root): the four lazy
+        // The root scope's names (spec/oqx §2 step 5 at the root): the five lazy
         // scans and `id`, the repository id — so `^docs` / `0^docs` from any row is
         // the scan and `^id` / `0^id` the id.
         root(name) {
@@ -817,7 +863,9 @@ export function makeStoreContext(store, repoId, opts = {}) {
             if (collection === null || typeof collection !== "object")
                 return undefined;
             const root = rootScans.get(collection);
-            if (!root)
+            // The revisions scan has no store index (4.7): the engine builds its own
+            // over the materialized rows (one SELECT per context).
+            if (!root || root.target === "revisions")
                 return undefined;
             const key = `${root.target}\u0000${JSON.stringify(path)}`;
             let index = indexes.get(key);
@@ -844,6 +892,13 @@ export function makeStoreContext(store, repoId, opts = {}) {
             }
             if (name === "refs")
                 return { handled: true, value: refs(args[0]) };
+            // `date(x)` / `dur(x)` (spec/surface §1.3 "Dates and durations", 4.8):
+            // pure over their argument except the named points, which read the host
+            // clock (pinned by the spec clock seam). run.ts folds a literal argument
+            // before planning, so the arm here serves the non-literal ones.
+            const dated = dateFunction(name, args);
+            if (dated.handled)
+                return dated;
             if (name === "range") {
                 const s = args[0];
                 if (semantics.isRange(s))
@@ -854,12 +909,17 @@ export function makeStoreContext(store, repoId, opts = {}) {
             const fn = semantics.BUILTIN_FUNCTIONS[name];
             return fn ? { handled: true, value: fn(args) } : { handled: false };
         },
-        // Domain methods first; fall back to oqx-js builtin methods
-        // (contains/startsWith/endsWith/matches/size/lower/upper).
+        // Domain methods first, then the date methods (`plus`/`minus`/`until`/the
+        // fields/`format` on a date string, `dur_text`/`dur_iso` on a number —
+        // §1.3 4.8; total: any other receiver is absent); fall back to oqx-js
+        // builtin methods (contains/startsWith/endsWith/matches/size/lower/upper).
         callMethod(name, recv, args) {
             const r = method(name, recv, args);
             if (r.handled)
                 return r;
+            const dated = dateMethod(name, recv, args);
+            if (dated.handled)
+                return dated;
             const fn = semantics.BUILTIN_METHODS[name];
             return fn ? { handled: true, value: fn(recv, args) } : { handled: false };
         },
@@ -891,8 +951,10 @@ export function rowRef(value) {
     if (!t)
         return undefined;
     const r = value;
-    const id = t === "docs" ? r.doc_id : t === "blocks" ? r.block_id : t === "nodes" ? r.node_id : r.edge_id;
-    const path = t === "docs" ? r.path : r.__path;
+    const id = t === "docs" ? r.doc_id : t === "blocks" ? r.block_id : t === "nodes" ? r.node_id : t === "revisions" ? r.rev_id : r.edge_id;
+    // a revision's path is `revisions.path` — the path it was committed under
+    // (a move re-paths the current revision; §1.2, 4.7).
+    const path = t === "docs" || t === "revisions" ? r.path : r.__path;
     return { id: String(id), path: path == null ? "" : referencePath(String(path)) };
 }
 export { TARGET };

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

@@ -0,0 +1,105 @@
+import type { CallResult } from "@omgbase/oqx";
+/** A parsed date: the instant, the offset it was WRITTEN in (minutes east of
+ * UTC; `0` for `Z` and for a date-only value), whether it is date-only, and
+ * whether it carried a fraction of a second as written (kept on render). */
+export interface DateValue {
+    ms: number;
+    offset: number;
+    dateOnly: boolean;
+    fraction: boolean;
+}
+/** Parse an ISO-8601 date / datetime string; `null` for anything else (a
+ * non-string, a malformed string, an out-of-range field such as month 13 or
+ * hour 24). */
+export declare function parseDate(x: unknown): DateValue | null;
+interface Fields {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millis: number;
+    weekday: number;
+}
+/** The fields of the value in the offset it was written in (`weekday` 1 = Monday … 7 = Sunday). */
+export declare function fieldsOf(d: DateValue): Fields;
+/** The canonical string: `YYYY-MM-DD` for a date-only value; otherwise
+ * `YYYY-MM-DDThh:mm:ss` + `.fff` when the value carries a fraction (as written,
+ * or because arithmetic produced one) + `Z` for UTC or the written `±hh:mm`. */
+export declare function renderDate(d: DateValue): string | null;
+/** `date(x)` on a string that is not a named point: the canonical form, or null. */
+export declare function canonicalDate(x: unknown): string | null;
+/** The named points `date()` resolves against the clock. */
+export declare const NAMED_POINTS: ReadonlySet<string>;
+/** Resolve a named point at the instant `nowMs` (UTC): `now` is the instant
+ * with milliseconds (the form the store stamps commits in); the others are
+ * date-only — `sow`/`eow` the Monday/Sunday of the current week, `som`/`eom`
+ * the first/last day of the month, `soy`/`eoy` of the year. Null for a name
+ * that is not a point. */
+export declare function namedPoint(name: string, nowMs: number): DateValue | null;
+/** `date(x)`: a named point against the clock, else the canonical ISO form, else null. */
+export declare function dateOf(x: unknown, nowMs?: number): string | null;
+/** A parsed duration: the calendar counts `years` and `months` kept apart from
+ * the fixed-length `seconds`, so `plus` can be calendar-aware while `dur()`
+ * applies the 365-day / 30-day conventions. */
+export interface Duration {
+    years: number;
+    months: number;
+    seconds: number;
+}
+/** Days per month / year under the fixed conventions `dur()` applies. */
+export declare const MONTH_SECONDS: number;
+export declare const YEAR_SECONDS: number;
+/** Parse a duration string: Dataview's `<number> <unit>` pairs, each pair
+ * separated from the next by spaces, a comma, or nothing (`"1h30m"`, `"2 days,
+ * 3 hours"`; a trailing separator is malformed), units case-insensitive:
+ * y|yr|yrs|year|years, mo|mos|month|months, w|wk|wks|week|weeks, d|day|days,
+ * h|hr|hrs|hour|hours, m|min|mins|minute|minutes, s|sec|secs|second|seconds —
+ * or an ISO-8601 duration (`P1DT2H`, `PT90M`, `P2W`). Null when it is neither. */
+export declare function parseDuration(x: unknown): Duration | null;
+/** A duration's length in seconds under the conventions: a year is 365 days, a month 30. */
+export declare function durationSeconds(d: Duration): number;
+/** `dur(x)`: a number is that many seconds; a string is parsed; else null. */
+export declare function durOf(x: unknown): number | null;
+/** Shift a date by a whole number of calendar `months` (the month field moves
+ * and the day is clamped to the new month's length) and then by `seconds`. A
+ * date-only value stays date-only when the seconds are a whole number of days;
+ * otherwise it becomes a datetime in its offset (UTC for a date-only receiver). */
+export declare function shiftDate(d: DateValue, months: number, seconds: number): DateValue;
+/** A duration as `plus` applies it: the WHOLE years and months are calendar
+ * months; a fractional year or month count is not calendar — its fraction is
+ * 365-day / 30-day seconds — and joins the fixed-length seconds. */
+export declare function calendarParts(dur: Duration): {
+    months: number;
+    seconds: number;
+};
+/** `d.plus(x)` (`sign` 1) / `d.minus(x)` (`sign` -1). */
+export declare function plusMinus(recv: unknown, arg: unknown, sign: 1 | -1): string | null;
+/** `a.until(b)`: seconds from `a` to `b` (negative when `b` is earlier), by instant. */
+export declare function until(a: unknown, b: unknown): number | null;
+/** `d.format(pattern)`: `yyyy` year, `MM` month, `dd` day, `HH` hour, `mm`
+ * minute, `ss` second (two digits each), `MMM` the English month abbreviation
+ * (`Jan`), `EEE` the English weekday abbreviation (`Mon`); every other
+ * character is literal. Fields are read in the written offset; a date-only
+ * value has `00` time fields. */
+export declare function formatDate(recv: unknown, pattern: unknown): string | null;
+/** `n.dur_text()`: `"2d 3h"`, `"1h 30m"`, `"45s"` — days, hours, minutes,
+ * seconds, zero parts omitted, `"0s"` for zero, a leading `-` for a negative
+ * duration, a fractional second kept (`"1.5s"`). Null for a non-number. */
+export declare function durText(n: unknown): string | null;
+/** `n.dur_iso()`: the ISO-8601 duration `P[nD][T[nH][nM][nS]]` — `PT1H30M`,
+ * `P2DT3H`, `PT45S`, `PT0S` for zero, a leading `-` for a negative duration.
+ * Null for a non-number. */
+export declare function durIso(n: unknown): string | null;
+/** The free functions and their arity. */
+export declare const DATE_FUNCTIONS: Readonly<Record<string, number>>;
+/** The methods and their arity: on a date string, and (`dur_text`/`dur_iso`) on a number. */
+export declare const DATE_METHODS: Readonly<Record<string, number>>;
+/** `callFunction` arm: `date(x)` / `dur(x)`; `{ handled: false }` for any other name. */
+export declare function dateFunction(name: string, args: unknown[], nowMs?: number): CallResult;
+/** `callMethod` arm: the date methods on a string receiver and the duration
+ * renderers on a number; a receiver of any other kind yields absent (the
+ * methods are total). `{ handled: false }` for any other name. */
+export declare function dateMethod(name: string, recv: unknown, args: unknown[]): CallResult;
+export {};