litedbmodel 1.2.9 → 2.0.0

package/dist/scp/ir.d.ts

@@ -0,0 +1,92 @@
+/**
+ * litedbmodel v2 SCP — Backend Compile IR shapes (WS1, #21).
+ *
+ * These are the litedbmodel-specific SQL IR structures a Component-graph CRUD node
+ * carries AFTER Backend Compile (spec §8). They are the input a thin multi-language
+ * runtime reads (WS3) to produce byte-identical SQL. The normative rules for how a
+ * runtime expands them are `docs/proposal/sql-dynamic-expansion-spec.md`.
+ *
+ * ## Param slots (spec §8) — the closed Expression IR set only
+ *
+ * Every element of a `params` array is 1:1 with a `?` placeholder and is one of (using
+ * bc's FLAT scope — input ports and node results are top-level scope roots, matching
+ * `runBehavior`'s `{...input, ...results}`):
+ *   - an **input reference** `{ ref: ["authorId"] }`
+ *   - a **wire reference** `{ ref: ["<nodeId>", "field"] }`
+ *   - an **Expression IR operator node** `{ coalesce: [{ refOpt: ["limit"] }, 20] }`
+ *
+ * All three are Expression IR nodes from bc's CLOSED operator set (`PORTABLE_EXPR_OPERATORS`
+ * — `ref`/`refOpt`/`coalesce`/`add`/`eq`/… ~23 ops). NO litedbmodel-local opcodes are ever
+ * emitted; an un-lowerable SQL construct is the Raw SQL escape hatch's concern (spec §13),
+ * not a fake opcode. This is enforced by {@link assertParamsPortable}.
+ */
+/** An Expression IR node (bc closed set). Opaque here; validated by the guard. */
+export type ExprNode = unknown;
+/**
+ * A dynamic WHERE/SET fragment with an existence rule (spec §8).
+ *
+ * - `always: true` — the fragment is unconditionally present.
+ * - `when: <ExprNode>` — the fragment is present iff the Expression evaluates to a
+ *   truthy (present) binding. A `cond ? [...] : SKIP` in authoring lowers to a fragment
+ *   whose `when` tests the presence of the driving input (§8 / feasibility §4). SKIP is
+ *   NOT an Expression opcode — it is the ABSENCE of the fragment when `when` is false.
+ *
+ * `sql` is the fragment's literal SQL text (leading connector included, e.g. `" AND "`),
+ * with `?` placeholders. `params` are the fragment's param slots (1:1 with its `?`),
+ * appended to the assembled params array in fragment order only when the fragment is
+ * present. `expand` marks an IN-list slot whose single `?` expands to `(?, ?, …)` per the
+ * bound array's length (dynamic-expansion spec §5).
+ */
+export interface Fragment {
+    /** Unconditionally present. Exactly one of `always` / `when` is set. */
+    always?: true;
+    /** Presence guard (Expression IR). Present iff it evaluates truthy. */
+    when?: ExprNode;
+    /** Literal SQL text (includes the leading connector, e.g. `" AND status = ?"`). */
+    sql: string;
+    /** Param slots (Expression IR nodes), 1:1 with this fragment's `?`. */
+    params: ExprNode[];
+    /**
+     * IN-list expansion: index into `params` whose bound value is an array; its single `?`
+     * in `sql` (written `(?)`) expands to `(?, ?, …)` (dynamic-expansion spec §5).
+     */
+    expand?: number;
+}
+/**
+ * A compiled fragment tree (spec §8): ordered fragments combined by a single connector
+ * (`AND` / `OR`). Nested groups parenthesize (dynamic-expansion spec §4). A `null` tree
+ * means "no WHERE" (empty-WHERE degeneration, §3 of the spec).
+ */
+export interface FragmentTree {
+    connector: 'AND' | 'OR';
+    fragments: (Fragment | FragmentTree)[];
+}
+/** The assembly spec (row → logical model). WS1 emits the shape only. */
+export interface AssemblySpec {
+    shape: string;
+}
+/**
+ * The Backend Compile output of one CRUD node (spec §8). `sql` is the fully flattened
+ * static SQL with a single `{where}` splice point where the fragment tree renders (or no
+ * splice point at all for writes whose WHERE is static). `params` are the STATIC param
+ * slots (those outside the fragment tree — e.g. Insert values, LIMIT); fragment params
+ * are interleaved at render time per the dynamic-expansion spec.
+ */
+export interface CompiledOperation {
+    /** Catalog component name (`Select` / `Insert` / `Update` / `Delete`). */
+    component: string;
+    /** SQLite dialect SQL text with a `{where}` splice marker if a fragment tree applies. */
+    sql: string;
+    /** The dynamic WHERE/SET fragment tree, or null when the WHERE is fully static/absent. */
+    where: FragmentTree | null;
+    /**
+     * Static param slots outside the fragment tree, in SQL position order. Each is an
+     * Expression IR node (input-ref / wire-ref / operator) from the closed set.
+     */
+    params: ExprNode[];
+    /** Row → logical model assembly (shape only in WS1). */
+    assembly: AssemblySpec;
+}
+/** The literal `{where}` splice marker inside `CompiledOperation.sql`. */
+export declare const WHERE_SLOT = "{where}";
+//# sourceMappingURL=ir.d.ts.map

package/dist/scp/ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../../src/scp/ir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC;AAE/B;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,uEAAuE;IACvE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,mFAAmF;IACnF,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,KAAK,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,CAAC,QAAQ,GAAG,YAAY,CAAC,EAAE,CAAC;CACxC;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAC;IACZ,0FAA0F;IAC1F,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3B;;;OAGG;IACH,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,wDAAwD;IACxD,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,0EAA0E;AAC1E,eAAO,MAAM,UAAU,YAAY,CAAC"}

package/dist/scp/ir.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — Backend Compile IR shapes (WS1, #21).
+ *
+ * These are the litedbmodel-specific SQL IR structures a Component-graph CRUD node
+ * carries AFTER Backend Compile (spec §8). They are the input a thin multi-language
+ * runtime reads (WS3) to produce byte-identical SQL. The normative rules for how a
+ * runtime expands them are `docs/proposal/sql-dynamic-expansion-spec.md`.
+ *
+ * ## Param slots (spec §8) — the closed Expression IR set only
+ *
+ * Every element of a `params` array is 1:1 with a `?` placeholder and is one of (using
+ * bc's FLAT scope — input ports and node results are top-level scope roots, matching
+ * `runBehavior`'s `{...input, ...results}`):
+ *   - an **input reference** `{ ref: ["authorId"] }`
+ *   - a **wire reference** `{ ref: ["<nodeId>", "field"] }`
+ *   - an **Expression IR operator node** `{ coalesce: [{ refOpt: ["limit"] }, 20] }`
+ *
+ * All three are Expression IR nodes from bc's CLOSED operator set (`PORTABLE_EXPR_OPERATORS`
+ * — `ref`/`refOpt`/`coalesce`/`add`/`eq`/… ~23 ops). NO litedbmodel-local opcodes are ever
+ * emitted; an un-lowerable SQL construct is the Raw SQL escape hatch's concern (spec §13),
+ * not a fake opcode. This is enforced by {@link assertParamsPortable}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WHERE_SLOT = void 0;
+/** The literal `{where}` splice marker inside `CompiledOperation.sql`. */
+exports.WHERE_SLOT = '{where}';
+//# sourceMappingURL=ir.js.map

package/dist/scp/ir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ir.js","sourceRoot":"","sources":["../../src/scp/ir.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AA0EH,0EAA0E;AAC7D,QAAA,UAAU,GAAG,SAAS,CAAC"}

package/dist/scp/relation.d.ts

@@ -0,0 +1,136 @@
+/**
+ * litedbmodel v2 SCP — Relation ops (Read) + staged batch resolution (WS4, #24).
+ *
+ * Relations are NOT SQL JOINs by default (spec §5). They are the same
+ * staged-batch query-composition + object-assembly shape graphddb and v1 `LazyRelation`
+ * use: collect the parent key set of a result page, run ONE batched child SELECT
+ * (`fk IN (…)` / per-parent-limited `ROW_NUMBER()` window), then distribute the child rows
+ * back to their parents. This makes a relation load structurally bounded — one batched
+ * query per relation edge, NEVER one-per-parent (no N+1).
+ *
+ * ## The relation op is a pre-compiled artifact (spec §8)
+ *
+ * A {@link RelationOp} is compiled ONCE from a model {@link RelationDecl}, dialect-aware
+ * (SQLite for α), into the SAME {@link CompiledOperation} shape WS1 already emits for a
+ * Select — so it renders through the SAME normative {@link renderOperation} (fragment tree
+ * + IN-list `(?, ?, …)` expansion, spec §5). It carries NO functions and lands in the §8
+ * bundle (`SqlBundle.relations`) as pure JSON, so a thin per-language runtime (WS7) gets
+ * the relation batch SQL for free. The v1 `LazyRelation` batch-SQL assets (IN-list, the
+ * `ROW_NUMBER() OVER (PARTITION BY … )` per-parent limit) are reused here as the compiled
+ * content, not re-invented.
+ *
+ * ## ONE relation op, TWO surfaces (spec §5 / feasibility §9)
+ *
+ * Both read surfaces trigger the IDENTICAL compiled {@link RelationOp} via
+ * {@link runRelationOp} — there is exactly one batch-execution code path:
+ *
+ *   - **Declarative select** (`with: { author: true }`): the planner resolves sibling
+ *     relations eagerly, dedups the parent key set, prefetch-optimized (staged batch).
+ *   - **Lazy** (`await post.author`): a prototype getter + a non-enumerable Symbol batch
+ *     context (graphddb's `GRAPHDDB_KEY` technique) fires the SAME op at access time over
+ *     the whole sibling set (batch, so still no N+1 — it just can't prefetch).
+ *
+ * `runRelationOp` renders `op.query` once for the deduped parent key set and returns the
+ * child rows grouped by parent key. Both surfaces call it; a test asserts they resolve via
+ * the same compiled op (same SQL text), not two parallel code paths.
+ */
+import type { CompiledOperation } from './ir';
+/** A read relation cardinality (v1 parity). `belongsTo`/`hasOne` are single; `hasMany` many. */
+export type RelationKind = 'belongsTo' | 'hasMany' | 'hasOne';
+/**
+ * A model's read-relation declaration (the authored/decorated relation metadata, spec §4).
+ * This is the litedbmodel-consumer input the relation compiler lowers to a {@link RelationOp}.
+ * It mirrors v1's `@belongsTo`/`@hasMany`/`@hasOne` config (source/target key + optional
+ * per-parent order/limit), reduced to the fields the batch SQL needs.
+ */
+export interface RelationDecl {
+    /** Relation name (the property attached on the parent object). */
+    readonly name: string;
+    /** Cardinality. */
+    readonly kind: RelationKind;
+    /** The child (target) table name. */
+    readonly targetTable: string;
+    /** Child columns to project (the child typed-object own props). */
+    readonly select: readonly string[];
+    /**
+     * The PARENT column whose value is the batch key (e.g. `belongsTo` → the parent FK
+     * `author_id`; `hasMany`/`hasOne` → the parent PK `id`).
+     */
+    readonly parentKey: string;
+    /**
+     * The CHILD column matched against the parent key (e.g. `belongsTo` → child PK `id`;
+     * `hasMany`/`hasOne` → child FK `post_id`).
+     */
+    readonly targetKey: string;
+    /** Optional per-parent ORDER BY body (dialect-neutral text, e.g. `"created_at DESC"`). */
+    readonly order?: string;
+    /**
+     * Optional per-parent row limit (`hasMany` only). When set, the batch query uses a
+     * `ROW_NUMBER() OVER (PARTITION BY <targetKey> ORDER BY <order>)` window so each parent
+     * gets at most `limit` children in ONE query (v1's SQLite `batchLoadWithRowNumber`).
+     */
+    readonly limit?: number;
+}
+/**
+ * A pre-compiled relation batch op (spec §8 `relation ops`). Pure JSON — it carries the
+ * compiled batch SELECT ({@link CompiledOperation}, rendered by {@link renderOperation})
+ * plus the grouping metadata the runtime needs to distribute child rows to parents. No
+ * functions, so it round-trips through `JSON.stringify` inside the bundle.
+ */
+export interface RelationOp {
+    readonly name: string;
+    readonly kind: RelationKind;
+    /** Parent column supplying the batch key values (dedup key). */
+    readonly parentKey: string;
+    /** Child column the batch groups rows by (matches the parent key). */
+    readonly targetKey: string;
+    /**
+     * The batched child SELECT as a {@link CompiledOperation}. Its WHERE is a single IN-list
+     * fragment `targetKey IN (?)` whose one slot binds the deduped parent-key array and
+     * expands to `(?, ?, …)` at render time (spec §5). A `limit` decl compiles to a
+     * `ROW_NUMBER()` window CTE instead (per-parent limit).
+     */
+    readonly query: CompiledOperation;
+}
+/** The reserved input head the relation batch query binds its deduped key array to. */
+export declare const RELATION_KEYS_HEAD = "__keys";
+/**
+ * Compile ONE {@link RelationDecl} into a {@link RelationOp} for SQLite (α dialect). The
+ * batch query selects the child rows whose {@link RelationDecl.targetKey} is in the deduped
+ * parent-key set. Reuses the existing IN-list fragment + `renderOperation` expansion (no new
+ * SQL machinery). A `hasMany` with `limit` compiles to the v1 `ROW_NUMBER()` window form so
+ * the per-parent cap holds in a single batched statement.
+ */
+export declare function compileRelationOp(decl: RelationDecl): RelationOp;
+/** A minimal read-only driver surface (`prepare(sql).all(...params)`), the SQLite `Database`. */
+export interface RelationDriver {
+    prepare(sql: string): {
+        all(...params: unknown[]): unknown[];
+    };
+}
+/** The child rows grouped for a batch: parent-key value (stringified) → child rows. */
+export type RelationBatch = Map<string, Record<string, unknown>[]>;
+/**
+ * Run ONE {@link RelationOp} for a set of parent rows: dedup the parent keys, render + execute
+ * the batched child SELECT ONCE (real SQLite), and group the child rows by their target key.
+ * This is the single batch primitive BOTH the declarative-select and the lazy surface invoke —
+ * proving the "same relation op" invariant structurally (there is no second path).
+ *
+ * Returns `{ sql, keys, batch }`: the rendered SQL (so a caller can assert both surfaces
+ * produced the same text), the deduped keys bound, and the grouping. When there are no
+ * non-null parent keys the query is NOT issued (an empty batch, matching v1) — this is not a
+ * fallback default, it is the correct empty-set behavior (an IN over no keys selects nothing).
+ */
+export declare function runRelationOp(op: RelationOp, parents: readonly Record<string, unknown>[], db: RelationDriver): {
+    sql: string;
+    keys: unknown[];
+    batch: RelationBatch;
+};
+/**
+ * Distribute a resolved {@link RelationBatch} onto ONE parent per the relation cardinality:
+ * `hasMany` → the child list (`[]` when none); `belongsTo`/`hasOne` → the single child (or
+ * `null`). `null`/`undefined` is the correct absence value (an unresolved single relation),
+ * NOT an ad-hoc default — it is the declared cardinality's empty representation.
+ */
+export declare function distributeToParent(op: RelationOp, parent: Record<string, unknown>, batch: RelationBatch): Record<string, unknown>[] | Record<string, unknown> | null;
+//# sourceMappingURL=relation.d.ts.map

package/dist/scp/relation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation.d.ts","sourceRoot":"","sources":["../../src/scp/relation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAoC,MAAM,MAAM,CAAC;AAGhF,gGAAgG;AAChG,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mBAAmB;IACnB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC;AAED,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,CAYhE;AAuED,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAA;KAAE,CAAC;CAChE;AAED,uFAAuF;AACvF,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,UAAU,EACd,OAAO,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC3C,EAAE,EAAE,cAAc,GACjB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAmBxD;AAiBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,EAAE,aAAa,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAK5D"}

package/dist/scp/relation.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — Relation ops (Read) + staged batch resolution (WS4, #24).
+ *
+ * Relations are NOT SQL JOINs by default (spec §5). They are the same
+ * staged-batch query-composition + object-assembly shape graphddb and v1 `LazyRelation`
+ * use: collect the parent key set of a result page, run ONE batched child SELECT
+ * (`fk IN (…)` / per-parent-limited `ROW_NUMBER()` window), then distribute the child rows
+ * back to their parents. This makes a relation load structurally bounded — one batched
+ * query per relation edge, NEVER one-per-parent (no N+1).
+ *
+ * ## The relation op is a pre-compiled artifact (spec §8)
+ *
+ * A {@link RelationOp} is compiled ONCE from a model {@link RelationDecl}, dialect-aware
+ * (SQLite for α), into the SAME {@link CompiledOperation} shape WS1 already emits for a
+ * Select — so it renders through the SAME normative {@link renderOperation} (fragment tree
+ * + IN-list `(?, ?, …)` expansion, spec §5). It carries NO functions and lands in the §8
+ * bundle (`SqlBundle.relations`) as pure JSON, so a thin per-language runtime (WS7) gets
+ * the relation batch SQL for free. The v1 `LazyRelation` batch-SQL assets (IN-list, the
+ * `ROW_NUMBER() OVER (PARTITION BY … )` per-parent limit) are reused here as the compiled
+ * content, not re-invented.
+ *
+ * ## ONE relation op, TWO surfaces (spec §5 / feasibility §9)
+ *
+ * Both read surfaces trigger the IDENTICAL compiled {@link RelationOp} via
+ * {@link runRelationOp} — there is exactly one batch-execution code path:
+ *
+ *   - **Declarative select** (`with: { author: true }`): the planner resolves sibling
+ *     relations eagerly, dedups the parent key set, prefetch-optimized (staged batch).
+ *   - **Lazy** (`await post.author`): a prototype getter + a non-enumerable Symbol batch
+ *     context (graphddb's `GRAPHDDB_KEY` technique) fires the SAME op at access time over
+ *     the whole sibling set (batch, so still no N+1 — it just can't prefetch).
+ *
+ * `runRelationOp` renders `op.query` once for the deduped parent key set and returns the
+ * child rows grouped by parent key. Both surfaces call it; a test asserts they resolve via
+ * the same compiled op (same SQL text), not two parallel code paths.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELATION_KEYS_HEAD = void 0;
+exports.compileRelationOp = compileRelationOp;
+exports.runRelationOp = runRelationOp;
+exports.distributeToParent = distributeToParent;
+const render_1 = require("./render");
+const ir_1 = require("./ir");
+/** The reserved input head the relation batch query binds its deduped key array to. */
+exports.RELATION_KEYS_HEAD = '__keys';
+/**
+ * Compile ONE {@link RelationDecl} into a {@link RelationOp} for SQLite (α dialect). The
+ * batch query selects the child rows whose {@link RelationDecl.targetKey} is in the deduped
+ * parent-key set. Reuses the existing IN-list fragment + `renderOperation` expansion (no new
+ * SQL machinery). A `hasMany` with `limit` compiles to the v1 `ROW_NUMBER()` window form so
+ * the per-parent cap holds in a single batched statement.
+ */
+function compileRelationOp(decl) {
+    if (decl.kind !== 'hasMany' && decl.limit !== undefined) {
+        throw new Error(`relation '${decl.name}': a per-parent 'limit' is only valid for hasMany (got ${decl.kind})`);
+    }
+    const query = decl.limit !== undefined ? compileLimitedBatch(decl) : compilePlainBatch(decl);
+    return {
+        name: decl.name,
+        kind: decl.kind,
+        parentKey: decl.parentKey,
+        targetKey: decl.targetKey,
+        query,
+    };
+}
+/** The IN-list membership slot binding the deduped key array (`{ref:[RELATION_KEYS_HEAD]}`). */
+function keysRef() {
+    return { ref: [exports.RELATION_KEYS_HEAD] };
+}
+/**
+ * Plain batch (`belongsTo`/`hasOne`/unlimited `hasMany`):
+ *   `SELECT <cols> FROM <target>{where}[ ORDER BY <o>]` with `{where}` = `targetKey IN (?)`.
+ * The `(?)` expands to one `?` per deduped key at render time (dynamic-expansion spec §5).
+ */
+function compilePlainBatch(decl) {
+    const cols = decl.select.join(', ');
+    const inFragment = {
+        always: true,
+        sql: `${decl.targetKey} IN (?)`,
+        params: [keysRef()],
+        expand: 0,
+    };
+    const where = { connector: 'AND', fragments: [inFragment] };
+    let sql = `SELECT ${cols} FROM ${decl.targetTable}${ir_1.WHERE_SLOT}`;
+    if (decl.order !== undefined)
+        sql += ` ORDER BY ${decl.order}`;
+    return { component: 'Select', sql, where, params: [], assembly: { shape: 'items' } };
+}
+/**
+ * Per-parent-limited `hasMany` batch — v1's SQLite `ROW_NUMBER()` window form:
+ *
+ *   WITH ranked AS (
+ *     SELECT <cols>, ROW_NUMBER() OVER (PARTITION BY <targetKey> ORDER BY <order>) AS _rn
+ *     FROM <target>{where}                         -- {where} = targetKey IN (?)
+ *   )
+ *   SELECT <cols> FROM ranked WHERE _rn <= <limit>
+ *
+ * The `{where}` splice keeps the IN-list expansion (spec §5). `_rn` is a synthetic window
+ * column dropped from the final projection, so the child typed-object own props stay exactly
+ * `select`. `limit` is inlined as a literal integer (a compiled per-parent cap from the decl,
+ * NOT a runtime-bound value — the decl is the SSoT), mirroring v1's `_rn <= ${limit}`.
+ */
+function compileLimitedBatch(decl) {
+    const cols = decl.select.join(', ');
+    const limit = decl.limit;
+    if (!Number.isInteger(limit) || limit < 0) {
+        throw new Error(`relation '${decl.name}': per-parent limit must be a non-negative integer (got ${String(limit)})`);
+    }
+    // A per-parent limit REQUIRES a deterministic ORDER BY (the window decides WHICH `limit`
+    // rows each parent keeps). Absent order = fail-closed authoring error, NOT a silent default
+    // — the relation declaration is the SSoT for the per-parent ordering.
+    if (decl.order === undefined) {
+        throw new Error(`relation '${decl.name}': a per-parent 'limit' requires an explicit 'order' (the ROW_NUMBER() window needs a deterministic ordering to decide which ${limit} rows each parent keeps)`);
+    }
+    const order = decl.order;
+    const inFragment = {
+        always: true,
+        sql: `${decl.targetKey} IN (?)`,
+        params: [keysRef()],
+        expand: 0,
+    };
+    const where = { connector: 'AND', fragments: [inFragment] };
+    const sql = `WITH ranked AS (SELECT ${cols}, ROW_NUMBER() OVER (PARTITION BY ${decl.targetKey} ORDER BY ${order}) AS _rn ` +
+        `FROM ${decl.targetTable}${ir_1.WHERE_SLOT}) ` +
+        `SELECT ${cols} FROM ranked WHERE _rn <= ${limit}`;
+    return { component: 'Select', sql, where, params: [], assembly: { shape: 'items' } };
+}
+/**
+ * Run ONE {@link RelationOp} for a set of parent rows: dedup the parent keys, render + execute
+ * the batched child SELECT ONCE (real SQLite), and group the child rows by their target key.
+ * This is the single batch primitive BOTH the declarative-select and the lazy surface invoke —
+ * proving the "same relation op" invariant structurally (there is no second path).
+ *
+ * Returns `{ sql, keys, batch }`: the rendered SQL (so a caller can assert both surfaces
+ * produced the same text), the deduped keys bound, and the grouping. When there are no
+ * non-null parent keys the query is NOT issued (an empty batch, matching v1) — this is not a
+ * fallback default, it is the correct empty-set behavior (an IN over no keys selects nothing).
+ */
+function runRelationOp(op, parents, db) {
+    const keys = dedupeKeys(parents, op.parentKey);
+    const batch = new Map();
+    if (keys.length === 0) {
+        // No parent keys → no batched query issued, empty grouping. Still render the SQL (for
+        // the same-op assertion) against the empty key set so the IN-list `1 = 0` degeneration
+        // is observable, but do not touch the driver.
+        const rendered = (0, render_1.renderOperation)(op.query, { [exports.RELATION_KEYS_HEAD]: [] });
+        return { sql: rendered.sql, keys, batch };
+    }
+    const rendered = (0, render_1.renderOperation)(op.query, { [exports.RELATION_KEYS_HEAD]: keys });
+    const rows = db.prepare(rendered.sql).all(...rendered.params);
+    for (const row of rows) {
+        const k = String(row[op.targetKey]);
+        const list = batch.get(k);
+        if (list === undefined)
+            batch.set(k, [row]);
+        else
+            list.push(row);
+    }
+    return { sql: rendered.sql, keys, batch };
+}
+/** The deduped, non-null parent-key values (insertion order preserved — deterministic). */
+function dedupeKeys(parents, parentKey) {
+    const seen = new Set();
+    const out = [];
+    for (const p of parents) {
+        const v = p[parentKey];
+        if (v === undefined || v === null)
+            continue;
+        const s = String(v);
+        if (seen.has(s))
+            continue;
+        seen.add(s);
+        out.push(v);
+    }
+    return out;
+}
+/**
+ * Distribute a resolved {@link RelationBatch} onto ONE parent per the relation cardinality:
+ * `hasMany` → the child list (`[]` when none); `belongsTo`/`hasOne` → the single child (or
+ * `null`). `null`/`undefined` is the correct absence value (an unresolved single relation),
+ * NOT an ad-hoc default — it is the declared cardinality's empty representation.
+ */
+function distributeToParent(op, parent, batch) {
+    const key = parent[op.parentKey];
+    const rows = key === undefined || key === null ? undefined : batch.get(String(key));
+    if (op.kind === 'hasMany')
+        return rows ?? [];
+    return rows !== undefined && rows.length > 0 ? rows[0] : null;
+}
+//# sourceMappingURL=relation.js.map

package/dist/scp/relation.js.map

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

package/dist/scp/render.d.ts

@@ -0,0 +1,40 @@
+/**
+ * litedbmodel v2 SCP — fragment-tree render + param assembly (WS1, #21).
+ *
+ * The NORMATIVE reference implementation of `docs/proposal/sql-dynamic-expansion-spec.md`.
+ * Given a compiled operation and a bound input scope, it deterministically produces the
+ * final SQLite SQL text (`?` placeholders) and the flat params array. Every multi-language
+ * runtime (WS3) must reproduce this byte-for-byte; this TS implementation is the golden
+ * reference the conformance harness pins.
+ *
+ * The three moving parts (dynamic-expansion spec):
+ *   §2 SKIP → fragment existence: a fragment with `when` is present iff `when` evaluates
+ *       to a present (non-null / true) binding; an absent fragment contributes NO SQL and
+ *       NO params.
+ *   §3 empty-WHERE degeneration: if no fragment is present the whole `{where}` splice
+ *       (including the ` WHERE ` keyword) collapses to the empty string.
+ *   §4 AND/OR structure + parenthesization: a nested tree renders `(… <connector> …)`.
+ *   §5 IN-list array expansion: a fragment slot marked `expand` turns its `(?)` into
+ *       `(?, ?, …)` for each element of the bound array (0 elements → the `1 = 0`
+ *       always-false degeneration, byte-identical to litedbmodel v1's empty-IN handling).
+ */
+import { type Scope, type Value } from 'behavior-contracts';
+import type { CompiledOperation } from './ir';
+import { type Dialect } from './dialect';
+/** The result of rendering: final SQL text + flat params (1:1 with `?`). */
+export interface RenderedSql {
+    sql: string;
+    params: Value[];
+}
+/**
+ * Render a compiled operation to final SQLite SQL + params for a bound input scope.
+ *
+ * Param order (matches SQL text order, dynamic-expansion spec §6): the compiled `sql`
+ * splices the WHERE tree at `{where}`; static params before the marker are emitted first,
+ * then the fragment params in tree order, then static params after the marker. WS1's CRUD
+ * shapes place all pre-WHERE statics (Insert values, Update SET) before `{where}` and all
+ * post-WHERE statics (LIMIT / OFFSET) after — so a single left-to-right walk of the
+ * spliced SQL yields the canonical `?` order.
+ */
+export declare function renderOperation(op: CompiledOperation, input: Scope, dialect?: Dialect): RenderedSql;
+//# sourceMappingURL=render.d.ts.map

package/dist/scp/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/scp/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAsB,KAAK,KAAK,EAAE,KAAK,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAA0B,MAAM,MAAM,CAAC;AAEtE,OAAO,EAAU,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,EAAE,CAAC;CACjB;AAqFD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,GAAE,OAAgB,GAAG,WAAW,CA6B3G"}