@libredb/libredb 0.0.1

package/dist/lens/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../src/lens/document.ts"],"names":[],"mappings":"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"}

package/dist/lens/kv.d.ts

@@ -0,0 +1,59 @@
+/**
+ * lens/kv.ts — the key-value lens, LibreDB's proof lens.
+ *
+ * The kernel (core.ts) is already an ordered byte key-value store, so this lens
+ * is the thinnest one possible: it does not add storage, transactions, or
+ * recovery — it only puts an ergonomic face on what the kernel already does.
+ * That makes it the honest proof of the architecture (DESIGN.md section 6):
+ * "here is the ordered KV core, usable directly."
+ *
+ * What the lens adds, and nothing more:
+ *   - STRING ergonomics. The kernel speaks raw bytes on purpose; this lens
+ *     encodes string keys/values as UTF-8 on the way in and decodes on the way
+ *     out, so it reads like the `Map<string, string>` it means to replace.
+ *   - The SHARED ENVELOPE. Reads return a {@link Result}, writes return a
+ *     {@link WriteResult} (lens/types.ts), the shapes every later lens reuses.
+ *
+ * Each operation runs in its own transaction (auto-commit), so the lens behaves
+ * like a durable map: a write is atomic and, on a file-backed database, fsync'd
+ * before it returns. Multi-key atomicity is a conscious omission for the proof
+ * lens — a caller that needs it reaches the kernel's `transact` directly. The
+ * lens is a view: it depends only on the {@link Store} seam (`transact`), never
+ * on the store's lifecycle; whoever opened the store closes it.
+ */
+import { type Result, type WriteResult } from "./types.ts";
+import type { Store } from "../adapter/store.ts";
+/** One key/value pair from a range scan, decoded to strings. The kv-lens
+ * counterpart of the kernel's byte-level {@link import("../core.ts").Entry}. */
+export interface KvEntry {
+    readonly key: string;
+    readonly value: string;
+}
+/**
+ * The key-value lens surface: a durable, ordered, string-keyed map.
+ *
+ * Keys are ordered by the UTF-8 byte order the kernel sorts on, so `range`
+ * yields entries in ascending key order over the half-open interval
+ * `[start, end)` — `start` included, `end` excluded.
+ */
+export interface Kv {
+    /** The value stored for `key`, or `undefined` if it is not set. */
+    get(key: string): string | undefined;
+    /** Store `value` under `key`, overwriting any existing value. Always reports
+     * one changed entry. */
+    set(key: string, value: string): WriteResult;
+    /** Remove `key`. Reports one changed entry if it existed, zero if it did not. */
+    delete(key: string): WriteResult;
+    /** Scan `[start, end)` in ascending key order. The {@link Result} is lazy and
+     * re-iterable: each pass re-runs the scan against the current state. */
+    range(start: string, end: string): Result<KvEntry>;
+    /** Scan every key beginning with `prefix`, in ascending key order — the
+     * canonical ordered-KV query. Throws if `prefix` is empty (it has no finite
+     * upper bound; use {@link range} to scan an explicit interval). The
+     * {@link Result} is lazy and re-iterable, like {@link range}. */
+    prefix(prefix: string): Result<KvEntry>;
+}
+/** Build a {@link Kv} lens over a {@link Store} (the kernel's `Database`
+ * satisfies it, as does any object that can run a transaction). */
+export declare function kv(store: Store): Kv;
+//# sourceMappingURL=kv.d.ts.map

package/dist/lens/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../src/lens/kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,EAAU,KAAK,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAEnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;gFACgF;AAChF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,EAAE;IACjB,mEAAmE;IACnE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC;4BACwB;IACxB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IAC7C,iFAAiF;IACjF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC;IACjC;4EACwE;IACxE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACnD;;;qEAGiE;IACjE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;CACzC;AAOD;mEACmE;AACnE,wBAAgB,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,EAAE,CAmCnC"}

package/dist/lens/kv.js

@@ -0,0 +1,87 @@
+/**
+ * lens/kv.ts — the key-value lens, LibreDB's proof lens.
+ *
+ * The kernel (core.ts) is already an ordered byte key-value store, so this lens
+ * is the thinnest one possible: it does not add storage, transactions, or
+ * recovery — it only puts an ergonomic face on what the kernel already does.
+ * That makes it the honest proof of the architecture (DESIGN.md section 6):
+ * "here is the ordered KV core, usable directly."
+ *
+ * What the lens adds, and nothing more:
+ *   - STRING ergonomics. The kernel speaks raw bytes on purpose; this lens
+ *     encodes string keys/values as UTF-8 on the way in and decodes on the way
+ *     out, so it reads like the `Map<string, string>` it means to replace.
+ *   - The SHARED ENVELOPE. Reads return a {@link Result}, writes return a
+ *     {@link WriteResult} (lens/types.ts), the shapes every later lens reuses.
+ *
+ * Each operation runs in its own transaction (auto-commit), so the lens behaves
+ * like a durable map: a write is atomic and, on a file-backed database, fsync'd
+ * before it returns. Multi-key atomicity is a conscious omission for the proof
+ * lens — a caller that needs it reaches the kernel's `transact` directly. The
+ * lens is a view: it depends only on the {@link Store} seam (`transact`), never
+ * on the store's lifecycle; whoever opened the store closes it.
+ */
+import { result } from "./types.js";
+import { prefixRange } from "../query/range.js";
+const utf8 = new TextEncoder();
+const fromUtf8 = new TextDecoder();
+const encode = (s) => utf8.encode(s);
+const decode = (b) => fromUtf8.decode(b);
+/** Build a {@link Kv} lens over a {@link Store} (the kernel's `Database`
+ * satisfies it, as does any object that can run a transaction). */
+export function kv(store) {
+    return {
+        get(key) {
+            return store.transact((tx) => {
+                const value = tx.get(encode(key));
+                return value === undefined ? undefined : decode(value);
+            });
+        },
+        set(key, value) {
+            store.transact((tx) => {
+                tx.set(encode(key), encode(value));
+            });
+            return { changed: 1 };
+        },
+        delete(key) {
+            const changed = store.transact((tx) => {
+                const k = encode(key);
+                const existed = tx.get(k) !== undefined;
+                tx.delete(k);
+                return existed ? 1 : 0;
+            });
+            return { changed };
+        },
+        range(start, end) {
+            return scan(store, encode(start), encode(end));
+        },
+        prefix(p) {
+            // prefixRange computes the [start, end) bounds on bytes so they agree with
+            // the kernel's order, and rejects a prefix with no finite end (an empty
+            // string). It runs at call time, so a bad prefix fails here, not on a
+            // later iteration; the scan itself stays lazy.
+            const { start, end } = prefixRange(encode(p));
+            return scan(store, start, end);
+        },
+    };
+}
+/**
+ * A lazy, re-iterable {@link Result} over the kernel's half-open `[start, end)`
+ * byte scan, decoded to string {@link KvEntry} rows. Shared by `range` and
+ * `prefix` so the decode-and-materialize step has one definition.
+ *
+ * The thunk runs on each iteration (laziness + re-iterability come from
+ * result()), so every pass observes the current committed state. Rows are
+ * materialized inside the read transaction because the kernel's range is only
+ * valid within the transaction body; nothing runs until the Result is iterated.
+ */
+function scan(store, start, end) {
+    return result(() => store.transact((tx) => {
+        const rows = [];
+        for (const entry of tx.getRange(start, end)) {
+            rows.push({ key: decode(entry.key), value: decode(entry.value) });
+        }
+        return rows;
+    }));
+}
+//# sourceMappingURL=kv.js.map

package/dist/lens/kv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.js","sourceRoot":"","sources":["../../src/lens/kv.ts"],"names":[],"mappings":"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"}

package/dist/lens/relational.d.ts

@@ -0,0 +1,119 @@
+import { type Result, type WriteResult } from "./types.ts";
+import type { Store } from "../adapter/store.ts";
+/**
+ * A column's declared type. These are the JSON shapes a relational column can
+ * hold (DESIGN.md section 6.2): the three scalars plus a nested object. Arrays
+ * and `null` are deliberately not column types in v1 — `"object"` means a plain
+ * JSON object, and nullable/optional columns are an honest deferral.
+ */
+export type ColumnType = "string" | "number" | "boolean" | "object";
+/**
+ * A table schema: the primary-key column name and the declared columns with
+ * their types. `primaryKey` must name a declared column whose type is `"string"`
+ * (it becomes the kernel key `<table>:<pk>`), checked when the {@link table}
+ * handle is built.
+ */
+export interface TableSchema {
+    readonly primaryKey: string;
+    readonly columns: {
+        readonly [name: string]: ColumnType;
+    };
+}
+/**
+ * A table row: a JSON object whose fields are the schema's columns. The value
+ * type mirrors {@link ColumnType} (string/number/boolean/object). A row is
+ * validated against the schema on insert before it is stored.
+ */
+export type Row = {
+    [column: string]: string | number | boolean | object;
+};
+/**
+ * A lazy, chainable query over a table's rows.
+ *
+ * A Query IS a {@link Result} (it is iterable and has `toArray`), so it can be
+ * consumed directly; it additionally offers `where` and `select`, each returning
+ * a new Query so operations compose (`table.where(...).select(...)`). Like every
+ * lens read it stays lazy and re-iterable: nothing runs until iterated, and each
+ * pass re-runs the underlying table scan against current state.
+ */
+export interface Query extends Result<Row> {
+    /** Keep only the rows whose top-level fields all equal `predicate`'s (deep
+     * structural equality, type-sensitive — the same matcher the document lens
+     * uses). Multiple predicate fields are an implicit AND; an empty predicate
+     * keeps every row. Chained `where`s narrow further (also an AND). */
+    where(predicate: Row): Query;
+    /** Project each row down to only the named `columns`. A requested column that
+     * a row does not have is simply omitted from that row's projection. On a joined
+     * result the columns are the qualified `table.column` names, which `select`
+     * matches literally — so projecting `"users.id"` works the same as any column. */
+    select(...columns: string[]): Query;
+    /**
+     * Inner equi-join this query's rows against `other`'s on `this[leftField]`
+     * deeply equal to `other[rightField]`, returning a chainable {@link Query} of
+     * the matched, combined rows. Each result row carries every column of both
+     * sides, qualified as `table.column` (e.g. `users.id`, `orders.total`), so the
+     * two sides never collide and `select`/`where` can name a column unambiguously.
+     *
+     * Inner means unmatched rows on either side are dropped; one left key matching
+     * several right rows fans out to several result rows (and vice versa). Joining
+     * on a key that a row lacks never matches that row (a missing key is not a join
+     * value), so it cannot produce a cross product by accident.
+     *
+     * Cost: O(n*m) — a nested loop over this query's `n` rows and `other`'s `m`
+     * rows, the honest minimal join with no indexes (DESIGN.md section 6.2).
+     */
+    join(other: Table, leftField: string, rightField: string): Query;
+}
+/**
+ * A handle on one typed table over a {@link Store}.
+ *
+ * Like the other lenses, the handle is a view: it depends only on the `Store`
+ * seam and never touches lifecycle. `insert` auto-commits in its own kernel
+ * transaction (a file-backed write is fsync'd before it returns). Read-side
+ * operations are added in later phases.
+ */
+export interface Table {
+    /** This table's name — the qualifier its columns take in a join
+     * (`<name>.<column>`). A join reads it off the right-hand table. */
+    readonly name: string;
+    /**
+     * Validate `row` against the schema and store it under `<table>:<pk>`,
+     * overwriting any existing row at that primary key. Throws if the row is
+     * invalid (missing/wrong-typed column, or an unknown field). Reports one
+     * changed entry.
+     */
+    insert(row: Row): WriteResult;
+    /** The row stored under primary key `pk`, or `undefined` if none exists. The
+     * returned row is the whole stored object, including the primary-key column. */
+    get(pk: string): Row | undefined;
+    /** Remove the row at primary key `pk`. Reports one changed entry if it
+     * existed, zero if it did not. */
+    delete(pk: string): WriteResult;
+    /** Every row in the table, in ascending primary-key (byte) order, as a
+     * chainable {@link Query}. Each row is the whole stored object (the primary key
+     * is a declared column, so it is part of the row — there is no separate id).
+     * The Query is lazy and re-iterable: each pass re-runs the scan against current
+     * state. The scan sees only this table's rows — the `<table>:` byte prefix is a
+     * sound boundary, so a sibling whose name shares a prefix (`users` vs `users2`)
+     * is never included. */
+    all(): Query;
+    /** The rows matching `predicate` (top-level field equality). Sugar for
+     * `all().where(predicate)`; returns a chainable {@link Query}. */
+    where(predicate: Row): Query;
+    /** Every row projected to only `columns`. Sugar for `all().select(...columns)`;
+     * returns a chainable {@link Query}. */
+    select(...columns: string[]): Query;
+    /** Inner equi-join every row of this table against `other` on
+     * `this[leftField]` equal to `other[rightField]`. Sugar for
+     * `all().join(other, leftField, rightField)`; returns a chainable {@link Query}
+     * of qualified `table.column` rows. */
+    join(other: Table, leftField: string, rightField: string): Query;
+}
+/**
+ * Build a {@link Table} handle for `name` with `schema` over a {@link Store}
+ * (the kernel's `Database` satisfies it). The schema is validated immediately:
+ * the `primaryKey` must name a declared column whose type is `"string"`, since
+ * the primary key becomes the string kernel key.
+ */
+export declare function table(store: Store, name: string, schema: TableSchema): Table;
+//# sourceMappingURL=relational.d.ts.map

package/dist/lens/relational.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relational.d.ts","sourceRoot":"","sources":["../../src/lens/relational.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAU,KAAK,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,CAAC;CAC3D;AAED;;;;GAIG;AACH,MAAM,MAAM,GAAG,GAAG;IAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAA;CAAE,CAAC;AA0C3E;;;;;;;;GAQG;AACH,MAAM,WAAW,KAAM,SAAQ,MAAM,CAAC,GAAG,CAAC;IACxC;;;yEAGqE;IACrE,KAAK,CAAC,SAAS,EAAE,GAAG,GAAG,KAAK,CAAC;IAC7B;;;sFAGkF;IAClF,MAAM,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACpC;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC;CAClE;AAuGD;;;;;;;GAOG;AACH,MAAM,WAAW,KAAK;IACpB;wEACoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,WAAW,CAAC;IAC9B;oFACgF;IAChF,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;IACjC;sCACkC;IAClC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC;IAChC;;;;;;4BAMwB;IACxB,GAAG,IAAI,KAAK,CAAC;IACb;sEACkE;IAClE,KAAK,CAAC,SAAS,EAAE,GAAG,GAAG,KAAK,CAAC;IAC7B;4CACwC;IACxC,MAAM,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACpC;;;2CAGuC;IACvC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,CAAC;CAClE;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,KAAK,CAoD5E"}

package/dist/lens/relational.js

@@ -0,0 +1,213 @@
+/**
+ * lens/relational.ts — the relational lens, LibreDB's reach lens.
+ *
+ * This is a deliberately minimal *relational view*, NOT a SQL engine (DESIGN.md
+ * section 6.2): there is no SQL text, lexer, or planner. A table is a typed,
+ * schema-validated collection of rows stored as JSON objects under a
+ * `<table>:<pk>` kernel key — the exact storage scheme the document lens uses,
+ * reusing its JSON codec. The relational value the lens adds over the document
+ * lens is the *schema*: declared columns with declared types, enforced at insert.
+ *
+ * Schema validation lives here; row STORAGE is delegated to the document lens.
+ * Because a validated row is just a JSON object stored at `<table>:<pk>` — the
+ * exact key the document lens uses for `<collection>:<id>` — a table is literally
+ * a schema-validated document collection. The relational lens holds a
+ * {@link doc} handle for the same name and reads/writes rows through it, so it
+ * inherits the document lens's codec and its collection-isolation-safe prefix
+ * scan for free (a sibling like `users2` never leaks into `users`).
+ *
+ * On top of the schema/row vocabulary, the {@link table} handle, insert-time
+ * validation, and by-pk CRUD (`get`/`delete`/`all`), this lens adds a small
+ * chainable query surface: `where` (top-level field-equality filter, reusing the
+ * document lens's matcher), `select` (column projection), and `join` (inner
+ * equi-join via nested loop, producing rows with columns qualified as
+ * `table.column`). The kernel is unchanged.
+ */
+import { doc, matches } from "./document.js";
+import { result } from "./types.js";
+/** Whether `value` matches the declared `type`. `"object"` is a plain JSON
+ * object — `null` (typeof `"object"`) and arrays are rejected, since v1 has
+ * neither nullable columns nor an array column type. */
+function matchesType(value, type) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number";
+        case "boolean":
+            return typeof value === "boolean";
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+    }
+}
+/**
+ * Validate `row` against `schema`, throwing on the first violation (DESIGN.md
+ * section 6.2: declared columns required, types checked, unknown fields
+ * rejected). Strict by design — there is no silent coercion or dropping.
+ */
+function validateRow(schema, row) {
+    // Unknown fields: every row key must be a declared column.
+    for (const key of Object.keys(row)) {
+        if (!Object.prototype.hasOwnProperty.call(schema.columns, key)) {
+            throw new Error(`unknown column "${key}" (not declared in the table schema)`);
+        }
+    }
+    // Declared columns: each must be present and match its declared type. A
+    // missing or null value fails here (no nullable/optional columns in v1).
+    for (const [name, type] of Object.entries(schema.columns)) {
+        if (!Object.prototype.hasOwnProperty.call(row, name)) {
+            throw new Error(`missing required column "${name}"`);
+        }
+        if (!matchesType(row[name], type)) {
+            throw new Error(`column "${name}" expected ${type}, got ${typeof row[name]}`);
+        }
+    }
+}
+/** Whether `row` matches `predicate` by the document lens's field-equality
+ * matcher. The casts are the same Row/Doc type-system artifact `table` uses
+ * elsewhere (their value unions overlap but neither is a subtype of the other);
+ * the runtime values are plain JSON. */
+function rowMatches(row, predicate) {
+    return matches(row, predicate);
+}
+/** A row containing only `columns` that are actually present on `row`. A row's
+ * values are always defined (it comes from JSON, which has no `undefined`), so an
+ * absent column reads as `undefined` and is omitted from the projection. */
+function project(row, columns) {
+    const out = {};
+    for (const column of columns) {
+        const value = row[column];
+        if (value !== undefined) {
+            out[column] = value;
+        }
+    }
+    return out;
+}
+/** Whether a left row joins to a right row: `left[leftField]` deeply equals
+ * `right[rightField]`. A join match is literally "the left row matches a
+ * predicate built from the right row's join value", so it reuses the document
+ * lens's `matches` for the exact same deep, type-sensitive equality `where` uses.
+ * A field a row lacks reads as `undefined`, which is never a join value (a row
+ * from JSON never holds `undefined`), so a missing key on either side never
+ * matches — an inner join, not an accidental cross product. */
+function joinKeyEqual(left, leftField, right, rightField) {
+    const rightValue = right[rightField];
+    if (left[leftField] === undefined || rightValue === undefined)
+        return false;
+    return matches(left, { [leftField]: rightValue });
+}
+/** Combine a matched left/right pair into one row whose columns are qualified by
+ * their table name (`<table>.<column>`), so columns of the same name on the two
+ * sides stay distinct and a later `select`/`where` can name either unambiguously. */
+function qualify(leftName, left, rightName, right) {
+    const out = {};
+    for (const [column, value] of Object.entries(left))
+        out[`${leftName}.${column}`] = value;
+    for (const [column, value] of Object.entries(right))
+        out[`${rightName}.${column}`] = value;
+    return out;
+}
+/** The inner equi-join itself: a nested loop pairing each left row with each
+ * right row that shares the join key, emitting qualified rows in left-major order
+ * (every match for the first left row, then the second, ...). O(n*m). */
+function joinRows(leftName, leftRows, other, leftField, rightField) {
+    const rightRows = other.all().toArray();
+    const out = [];
+    for (const left of leftRows) {
+        for (const right of rightRows) {
+            if (joinKeyEqual(left, leftField, right, rightField)) {
+                out.push(qualify(leftName, left, other.name, right));
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Wrap a lazy row source as a {@link Query}. `where`/`select`/`join` build new
+ * Queries over the materialized rows of this one, so they re-run the source each
+ * pass (laziness and re-iterability carry through the whole chain). All filtering,
+ * projection, and joining happen in-engine over the rows — there are no indexes,
+ * so a `where` is O(n) in the table size and a `join` is O(n*m), the same cost as
+ * the underlying scans.
+ *
+ * `name` is the qualifier the rows belong to — the table name. It is carried so
+ * a later `join` can prefix this side's columns as `<name>.<column>`; `where` and
+ * `select` do not use it (they match/project by literal column name), so it rides
+ * through them unchanged.
+ */
+function query(name, source) {
+    const base = result(source);
+    return {
+        [Symbol.iterator]() {
+            return base[Symbol.iterator]();
+        },
+        toArray() {
+            return base.toArray();
+        },
+        where(predicate) {
+            return query(name, () => base.toArray().filter((row) => rowMatches(row, predicate)));
+        },
+        select(...columns) {
+            return query(name, () => base.toArray().map((row) => project(row, columns)));
+        },
+        join(other, leftField, rightField) {
+            return query(name, () => joinRows(name, base.toArray(), other, leftField, rightField));
+        },
+    };
+}
+/**
+ * Build a {@link Table} handle for `name` with `schema` over a {@link Store}
+ * (the kernel's `Database` satisfies it). The schema is validated immediately:
+ * the `primaryKey` must name a declared column whose type is `"string"`, since
+ * the primary key becomes the string kernel key.
+ */
+export function table(store, name, schema) {
+    const pkType = schema.columns[schema.primaryKey];
+    if (pkType === undefined) {
+        throw new Error(`primaryKey "${schema.primaryKey}" is not a declared column`);
+    }
+    if (pkType !== "string") {
+        throw new Error(`primaryKey "${schema.primaryKey}" must be a string column, but is ${pkType}`);
+    }
+    // A table is a schema-validated document collection: rows are stored, read,
+    // deleted, and scanned through the document lens at `<table>:<pk>`. This is
+    // what reuses the document codec and the collection-isolation-safe prefix scan;
+    // a row is a Doc whose fields happen to be the declared columns. The Row/Doc
+    // casts are type-system artifacts (their value unions overlap but neither is a
+    // subtype of the other); validation guarantees what crosses the boundary.
+    const rows = doc(store, name);
+    // Every read starts from the full table scan re-wrapped as a chainable Query:
+    // drop the document lens's DocEntry id wrapper (the pk lives in the row), then
+    // let where/select compose over it. Each call rebuilds the Query so laziness
+    // and re-iterability carry through from the document scan.
+    const allRows = () => query(name, () => rows.all().toArray().map((entry) => entry.doc));
+    return {
+        name,
+        insert(row) {
+            validateRow(schema, row);
+            // The primary-key column is validated as a string above and required, so
+            // this read is a checked string, safe as the document id.
+            const pk = row[schema.primaryKey];
+            return rows.put(pk, row);
+        },
+        get(pk) {
+            return rows.get(pk);
+        },
+        delete(pk) {
+            return rows.delete(pk);
+        },
+        all() {
+            return allRows();
+        },
+        where(predicate) {
+            return allRows().where(predicate);
+        },
+        select(...columns) {
+            return allRows().select(...columns);
+        },
+        join(other, leftField, rightField) {
+            return allRows().join(other, leftField, rightField);
+        },
+    };
+}
+//# sourceMappingURL=relational.js.map

package/dist/lens/relational.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relational.js","sourceRoot":"","sources":["../../src/lens/relational.ts"],"names":[],"mappings":"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"}

package/dist/lens/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * lens/types.ts — the shared query/result shape every lens reuses.
+ *
+ * A lens (kv, document, relational) is a typed view over the kernel in core.ts.
+ * Lenses differ wildly in HOW you ask for data — a kv key range, a document
+ * filter, a relational SELECT — and that is on purpose: DESIGN.md section 2 (and
+ * the founding brainstorm in HANDOFF.md) reject a single unified query
+ * *language* as a lowest-common-denominator trap. So what lenses share is not
+ * the query syntax but the RESULT envelope: every read hands back a
+ * {@link Result}, every write reports a {@link WriteResult}. Pinning these two
+ * shapes once lets later lenses — and the universal tooling above them (Studio,
+ * Platform) — consume any lens uniformly without flattening their differences.
+ *
+ * This file is an edge, not the kernel: it holds no durability logic, only the
+ * vocabulary the lenses speak.
+ */
+/**
+ * What every lens read returns: a lazy, typed, re-iterable sequence of rows.
+ *
+ * `Row` is the lens's own unit — a kv {@link import("../core.ts").Entry}, a
+ * document, a relational tuple — so the shape is shared without erasing what
+ * each lens actually yields.
+ *
+ * Lazy and re-iterable are deliberate. The kernel's range scan is itself lazy
+ * (`Iterable<Entry>`), so a Result must not force a large scan to materialize
+ * just to be wrapped. Re-iterable means a Result behaves like the query it
+ * stands for: iterating it twice runs the read twice, instead of the classic
+ * generator footgun where the second pass silently yields nothing. Because of
+ * that, the Result *is* the deferred query — there is no separate query object
+ * to define.
+ */
+export interface Result<Row> extends Iterable<Row> {
+    /** Materialize every row into a fresh array. Convenience over iterating; the
+     * returned array is the caller's to keep and mutate. */
+    toArray(): Row[];
+}
+/**
+ * The outcome of a lens write.
+ *
+ * `changed` is the number of stored entries the write created, overwrote, or
+ * removed. It is uniform across lenses (a kv set is 1, a delete of an absent
+ * key is 0, a relational UPDATE is its matched-row count) and keeps writes
+ * visible by default (DESIGN.md principle 2): a caller can always see what a
+ * write actually did.
+ */
+export interface WriteResult {
+    readonly changed: number;
+}
+/**
+ * Build a {@link Result} from a source of rows.
+ *
+ * `source` is a thunk, not an iterable, so the read is deferred and repeatable:
+ * nothing runs until the Result is iterated, and each iteration calls `source`
+ * again for a fresh pass. Every lens constructs its reads through this one
+ * helper so "what a Result is" has a single definition.
+ */
+export declare function result<Row>(source: () => Iterable<Row>): Result<Row>;
+//# sourceMappingURL=types.d.ts.map

package/dist/lens/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lens/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,MAAM,CAAC,GAAG,CAAE,SAAQ,QAAQ,CAAC,GAAG,CAAC;IAChD;4DACwD;IACxD,OAAO,IAAI,GAAG,EAAE,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CASpE"}

package/dist/lens/types.js

@@ -0,0 +1,35 @@
+/**
+ * lens/types.ts — the shared query/result shape every lens reuses.
+ *
+ * A lens (kv, document, relational) is a typed view over the kernel in core.ts.
+ * Lenses differ wildly in HOW you ask for data — a kv key range, a document
+ * filter, a relational SELECT — and that is on purpose: DESIGN.md section 2 (and
+ * the founding brainstorm in HANDOFF.md) reject a single unified query
+ * *language* as a lowest-common-denominator trap. So what lenses share is not
+ * the query syntax but the RESULT envelope: every read hands back a
+ * {@link Result}, every write reports a {@link WriteResult}. Pinning these two
+ * shapes once lets later lenses — and the universal tooling above them (Studio,
+ * Platform) — consume any lens uniformly without flattening their differences.
+ *
+ * This file is an edge, not the kernel: it holds no durability logic, only the
+ * vocabulary the lenses speak.
+ */
+/**
+ * Build a {@link Result} from a source of rows.
+ *
+ * `source` is a thunk, not an iterable, so the read is deferred and repeatable:
+ * nothing runs until the Result is iterated, and each iteration calls `source`
+ * again for a fresh pass. Every lens constructs its reads through this one
+ * helper so "what a Result is" has a single definition.
+ */
+export function result(source) {
+    return {
+        [Symbol.iterator]() {
+            return source()[Symbol.iterator]();
+        },
+        toArray() {
+            return [...source()];
+        },
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/lens/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lens/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoCH;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAM,MAA2B;IACrD,OAAO;QACL,CAAC,MAAM,CAAC,QAAQ,CAAC;YACf,OAAO,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrC,CAAC;QACD,OAAO;YACL,OAAO,CAAC,GAAG,MAAM,EAAE,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}