litedbmodel 1.2.9 → 2.0.0

package/dist/scp/write-runtime.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — write-time transaction runtime (WS5, #25; spec §6 / §3 / §11).
+ *
+ * Executes a derived {@link TransactionPlan} against REAL SQLite as ONE transaction with
+ * gate-first short-circuit (spec §6). It renders each ordered statement with the SAME normative
+ * {@link renderOperation} the read path uses (fragment tree + Expression-IR param slots), and
+ * drives an explicit `BEGIN` / `COMMIT` / `ROLLBACK` envelope through the SAME synchronous
+ * driver seam ({@link SqliteDb}) the WS3 runtime uses — no mock, no separate interpreter.
+ *
+ * ## The transaction envelope (spec §6) — Tx is derived, not authored
+ *
+ *   BEGIN;
+ *     for each ordered statement:
+ *       render (input + accumulated $.entity row) → execute REAL SQL
+ *       if it is a GATE and its rule FAILS  → ROLLBACK and stop (remaining SQL never runs)
+ *   COMMIT;   (or ROLLBACK on a driver failure / gate fail)
+ *
+ * The body write's RETURNING row is captured and exposed to the derive/edges/emits stages under
+ * `$.entity.*` ({@link ENTITY_ROOT}) — the §6 example's `$.entity.id`.
+ *
+ * ## Gate-first is a REAL behavior (spec §6 "Gate First"), proven, not textual
+ *
+ * A gate statement's {@link GateRule} is evaluated on its actual driver result:
+ *   - `existsElseRollback` — `SELECT 1 …` returned ZERO rows ⇒ the required row is absent ⇒
+ *     ROLLBACK; the body + all later statements are NEVER prepared/executed (a real query-count
+ *     drop, observable via a counting driver, and the DB is unchanged).
+ *   - `insertedElseRollback` — a `unique` guard `INSERT … ON CONFLICT DO NOTHING` affected ZERO
+ *     rows ⇒ a collision ⇒ ROLLBACK.
+ *   - `insertedElseNoop` — an `idempotency` token INSERT affected ZERO rows ⇒ a DUPLICATE request
+ *     ⇒ short-circuit as a no-op: ROLLBACK the (empty-so-far) transaction, so a duplicate
+ *     `request_id` performs NO double write (idempotent).
+ *
+ * A short-circuit returns a structured {@link TransactionResult} (`committed:false`) rather than
+ * throwing — the caller distinguishes a legitimate gate outcome (absent requires / unique
+ * collision / duplicate) from a driver Failure (which IS mapped + thrown, spec §11 item 5).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeTransaction = executeTransaction;
+exports.countingDriver = countingDriver;
+const render_1 = require("./render");
+const errors_1 = require("./errors");
+const writes_1 = require("./writes");
+const dialect_1 = require("./dialect");
+/** bc evaluates ints to bigint; convert a rendered param to a driver-bindable value. */
+function toDriverParam(v) {
+    if (typeof v === 'bigint') {
+        if (v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER))
+            return Number(v);
+        return v;
+    }
+    // An emit payload evaluates to a plain object (`{obj:{…}}`); serialize it to the outbox JSON
+    // text column. Arrays are IN-list elements (not used in the write path); pass through.
+    if (v !== null && typeof v === 'object' && !Array.isArray(v))
+        return JSON.stringify(v);
+    return v;
+}
+/**
+ * Execute one statement's compiled op against the driver in the given scope, returning the
+ * rows (SELECT / RETURNING) plus the affected-row count (non-returning writes). A driver error
+ * is mapped and thrown (the caller ROLLBACKs). This is the SAME render→bind→execute pipeline as
+ * the WS3 read/write handlers; only the transaction envelope + gate interpretation is new.
+ */
+function execStatement(db, op, scope, dialect) {
+    const rendered = (0, render_1.renderOperation)(op, scope, dialect);
+    const params = rendered.params.map(toDriverParam);
+    const stmt = db.prepare(rendered.sql);
+    const hasReturn = op.component === 'Select' || /\breturning\b/i.test(rendered.sql);
+    if (hasReturn) {
+        const rows = stmt.all(...params);
+        return { rows, changes: rows.length };
+    }
+    const info = stmt.run(...params);
+    return { rows: [], changes: info.changes };
+}
+/** Evaluate a gate rule on a statement result → the short-circuit reason, or null to continue. */
+function gateShortCircuit(gate, result) {
+    switch (gate) {
+        case 'existsElseRollback':
+            return result.rows.length === 0 ? 'requires_absent' : null;
+        case 'insertedElseRollback':
+            return result.changes === 0 ? 'unique_collision' : null;
+        case 'insertedElseNoop':
+            return result.changes === 0 ? 'idempotent_duplicate' : null;
+    }
+}
+/**
+ * Execute a derived {@link TransactionPlan} as ONE real SQLite transaction with gate-first
+ * short-circuit (spec §6). Statements run in the plan's fixed order (requires → idempotency →
+ * unique → body → derive → edges → emits); a failing gate ROLLBACKs and the remaining statements
+ * are never executed. On success COMMITs and returns the `$.entity` RETURNING row.
+ *
+ * @param db     the synchronous SQLite driver (better-sqlite3 `Database`), supporting `BEGIN` /
+ *               `COMMIT` / `ROLLBACK` via `prepare(...).run()`.
+ * @param plan   the derived transaction plan (pure JSON; from `deriveTransactionPlan` or the bundle).
+ * @param input  the Command input scope (`$.input.*` = bc flat scope).
+ * @throws {SqlFailure} a mapped driver failure (the transaction is ROLLBACKed first, spec §11).
+ */
+function executeTransaction(db, plan, input, dialect = dialect_1.SQLITE) {
+    db.prepare('BEGIN').run();
+    const executed = [];
+    // The evolving scope: input names at the top level (bc flat scope) + the body RETURNING row
+    // exposed under `__entity` once the body runs. Defaults live in the declaration/schema, so no
+    // ad-hoc code default is injected here.
+    const scope = { ...input };
+    let entity = null;
+    try {
+        for (const stmt of plan.statements) {
+            const result = runOne(db, stmt, scope, executed, dialect);
+            // Gate-first: a failing gate short-circuits — ROLLBACK and STOP (tail never executes).
+            if (stmt.gate !== undefined) {
+                const reason = gateShortCircuit(stmt.gate, result);
+                if (reason !== null) {
+                    db.prepare('ROLLBACK').run();
+                    return { committed: false, shortCircuit: { statementId: stmt.id, reason }, entity: null, executed };
+                }
+            }
+            // Capture the SOLE body RETURNING row as `$.entity` (WS5 single-write back-compat).
+            if (stmt.id === plan.entityFrom) {
+                entity = result.rows.length > 0 ? result.rows[0] : null;
+                if (entity !== null)
+                    scope[writes_1.ENTITY_ROOT] = entity;
+            }
+            // Composite (WS8a): bind THIS statement's RETURNING row under its `binds` name so a later
+            // `$.ref.<binds>.<field>` resolves against it (the DAG's data-dependency edge). Self-
+            // describing: the runtime just binds the row the plan told it to — no re-derivation.
+            if (stmt.binds !== undefined && result.rows.length > 0) {
+                scope[stmt.binds] = result.rows[0];
+            }
+        }
+        db.prepare('COMMIT').run();
+        return { committed: true, entity, executed };
+    }
+    catch (e) {
+        // A driver failure: ROLLBACK, then map + re-throw the structured SqlFailure (spec §11).
+        try {
+            db.prepare('ROLLBACK').run();
+        }
+        catch {
+            /* ROLLBACK best-effort; surface the original failure below */
+        }
+        throw (0, errors_1.mapSqliteError)(e);
+    }
+}
+/** Render + execute one statement, recording it as executed. */
+function runOne(db, stmt, scope, executed, dialect) {
+    const result = execStatement(db, stmt.op, scope, dialect);
+    executed.push(stmt.id);
+    return result;
+}
+/**
+ * A counting {@link SqliteDb} wrapper: forwards every call to the wrapped driver but records
+ * each PREPARED SQL string. Tests use it to PROVE gate-first short-circuit — after an absent
+ * `requires`, the body/derive/edges/emits SQL is never prepared (a real, observable query-count
+ * drop), not merely absent from a text list. This is a test aid living beside the runtime.
+ */
+function countingDriver(db) {
+    const prepared = [];
+    const wrapped = {
+        prepare(sql) {
+            prepared.push(sql);
+            return db.prepare(sql);
+        },
+    };
+    return { db: wrapped, prepared };
+}
+//# sourceMappingURL=write-runtime.js.map

package/dist/scp/write-runtime.js.map

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

package/dist/scp/writes.d.ts

@@ -0,0 +1,251 @@
+/**
+ * litedbmodel v2 SCP — write-time relations declaration vocabulary (WS5, #25; spec §6 / §2.2).
+ *
+ * `entityWrites` / `edgeWrites` declare the **write-side invariants / effects required for
+ * an entity to stay consistent** when it is created / updated / removed — the SQL-backend
+ * counterpart of graphddb's `entityWrites` save contract (`graphddb/src/define/entity-writes.ts`,
+ * same shape: a per-lifecycle map of `w.lifecycle({requires,unique,derive,edges,emits,idempotency})`).
+ * This module produces a PORTABLE declaration (pure data, no closures): every value that
+ * references the write is a **path-rooted string** (`$.input.<field>` = the mutation input,
+ * `$.entity.<field>` = the written row's RETURNING result). {@link ../write-plan} lowers the
+ * declaration + a base write op into an ordered, gate-first SQL transaction plan (§6 table).
+ *
+ * ## Path roots (spec §6 example) — the SSoT for every derived value
+ *
+ * A leaf value binds to an explicit root so its source is unambiguous and no engine-code
+ * fallback is ever needed (hard rule: defaults live in the declaration):
+ *   - `$.input.<field>`  — the Command's input port value (bc flat scope: `{ref:['<field>']}`).
+ *   - `$.entity.<field>` — the just-written row (the body write's RETURNING row), exposed to
+ *     the derive/edges/emits stages under the reserved `{@link ENTITY_ROOT}` binding.
+ *
+ * The declaration is INITIAL-scope (spec §6 / §13): single-statement Command + fixed-order
+ * write-time relations. It does NOT model the complex DAG derivation (WS8).
+ */
+/** The reserved scope binding under which the body write's RETURNING row is exposed (`$.entity.*`). */
+export declare const ENTITY_ROOT = "__entity";
+/**
+ * The path root a write-relation value binds from:
+ *   - `input`  — the Command input port (bc flat scope).
+ *   - `entity` — the SOLE body write's RETURNING row (the WS5 single-base-write shorthand),
+ *     bound under {@link ENTITY_ROOT}.
+ *   - `ref`    — a NAMED upstream write's RETURNING row (`$.ref.<writeName>.<field>`, WS8a
+ *     composite/DAG scope). `entity` is exactly `ref` targeting the sole base write; keeping
+ *     it distinct preserves the WS5 vocabulary while composite writes address writes by name.
+ */
+export type PathRoot = 'input' | 'entity' | 'ref';
+/** A parsed, path-rooted write-relation value (`$.input.x` / `$.entity.x` / `$.ref.w.x`). */
+export interface EffectPath {
+    readonly root: PathRoot;
+    /**
+     * For `ref`: the upstream write's NAME (the statement whose RETURNING row is referenced).
+     * Absent for `input` / `entity` (those have a single implicit source).
+     */
+    readonly writeName?: string;
+    /** The field name after the root (a single physical column; no nested paths in α). */
+    readonly field: string;
+}
+/**
+ * Parse a path-rooted write-relation value string into an {@link EffectPath}. Fail-closed on
+ * a malformed path — a write-relation value MUST be `$.input.<field>`, `$.entity.<field>`, or
+ * `$.ref.<writeName>.<field>` (no free-form paths, no implicit root), so a typo is a loud build
+ * error, never a silent default (hard rule).
+ */
+export declare function parseEffectPath(value: string): EffectPath;
+/**
+ * A referential-integrity requirement (§6 `requires`): the named `table` must contain a row
+ * whose columns equal the bound keys. Lowered to a gate-first `SELECT 1 FROM <table> WHERE …`
+ * existence guard that ROLLBACKs when absent (spec §6 example line 1).
+ */
+export interface RequiresEffect {
+    readonly kind: 'requires';
+    /** The table whose row must exist. */
+    readonly table: string;
+    /** target column → path-rooted source value (the existence key). */
+    readonly keys: Readonly<Record<string, string>>;
+}
+/**
+ * A uniqueness guard (§6 `unique`): the combined `fields` must be unique within `scope`.
+ * Lowered to a guard-row `INSERT INTO <guardTable> … ON CONFLICT DO NOTHING` whose affected-
+ * row count is checked (0 rows ⇒ collision ⇒ ROLLBACK) — the SQL idiom of §6 (`ON CONFLICT
+ * DO NOTHING` + affected 検査).
+ */
+export interface UniqueEffect {
+    readonly kind: 'unique';
+    /** The guard-row name (its discriminator column value in the guard table). */
+    readonly name: string;
+    /** The guard table that materializes the uniqueness rows. */
+    readonly guardTable: string;
+    /** The scope the uniqueness is partitioned by (path-rooted values). */
+    readonly scope: readonly string[];
+    /** The fields whose combined value must be unique within the scope (path-rooted values). */
+    readonly fields: readonly string[];
+}
+/**
+ * A derived / cascading counter update (§6 `derive`): `SET <attribute> = <attribute> ± amount`
+ * on the `table` row keyed by `keys`. Lowered to `UPDATE <table> SET c = c + :amount WHERE …`
+ * (spec §6 example line "derive"). `amount` is the SSoT for the increment — never a code default.
+ */
+export interface DeriveEffect {
+    readonly kind: 'derive';
+    /** The table whose counter attribute is derived-updated. */
+    readonly table: string;
+    /** target column → path-rooted source value (the updated row's key). */
+    readonly keys: Readonly<Record<string, string>>;
+    /** The counter column to increment. */
+    readonly attribute: string;
+    /** The signed amount added to the counter (the declaration IS the source of truth). */
+    readonly amount: number;
+}
+/**
+ * An edge write (§6 `edges`). A many-to-many edge materializes as an intermediate-table
+ * `INSERT` (create) / `DELETE` (remove); a one-to-many edge as a foreign-key column `UPDATE`
+ * on the related table. Lowered per {@link EdgeEffect.relation} (spec §6 table row `edges`).
+ */
+export interface EdgeEffect {
+    readonly kind: 'edge';
+    /** `m2m` → intermediate-table INSERT/DELETE; `fk` → related-table FK column UPDATE. */
+    readonly relation: 'm2m' | 'fk';
+    /** The write action for this lifecycle: `set` (create/link) or `unset` (remove/unlink). */
+    readonly action: 'set' | 'unset';
+    /**
+     * For `m2m`: the intermediate (join) table. For `fk`: the related table whose FK column is set.
+     */
+    readonly table: string;
+    /**
+     * For `m2m`: the join-row columns → path-rooted source values (both endpoint keys).
+     * For `fk`: the FK column → path-rooted source value AND the matched-row key columns.
+     */
+    readonly columns: Readonly<Record<string, string>>;
+    /**
+     * For `fk` only: the WHERE key columns (matched-row identity) → path-rooted source values.
+     * `columns` then holds ONLY the FK column(s) to SET. For `m2m` this is absent.
+     */
+    readonly where?: Readonly<Record<string, string>>;
+}
+/**
+ * A domain event (§6 `emits`): an outbox `INSERT INTO <outboxTable>(type, payload)` in the
+ * SAME transaction (spec §6 example line "emits"). The payload is a path-rooted map serialized
+ * to a JSON text column at render time.
+ */
+export interface EmitEffect {
+    readonly kind: 'emit';
+    /** The event type discriminator (e.g. `PostCreated`). */
+    readonly name: string;
+    /** The outbox table the event row is inserted into. */
+    readonly outboxTable: string;
+    /** The event payload: field → path-rooted source value. */
+    readonly payload: Readonly<Record<string, string>>;
+}
+/**
+ * An idempotency guard (§6 `idempotency`): a client-token guard `INSERT INTO <table>(token)`
+ * whose UNIQUE violation detects a duplicate request (spec §6 example line "idempotency").
+ * Runs gate-first: a duplicate token short-circuits the whole transaction (no double write).
+ */
+export interface IdempotencyEffect {
+    readonly kind: 'idempotency';
+    /** The idempotency-key table (a single UNIQUE token column). */
+    readonly table: string;
+    /** The token column name. */
+    readonly column: string;
+    /** The path-rooted client-token value (e.g. `$.input.request_id`). */
+    readonly token: string;
+}
+/**
+ * The §6 effect set a {@link LifecycleContract} carries. Every field is optional; an omitted
+ * field is the empty effect set. Fixed derivation order (spec §6 example): gate-first
+ * (requires → idempotency → unique), body, then derive → edges → emits.
+ */
+export interface LifecycleEffects {
+    /** Referential-integrity requirements (→ gate-first existence guard). */
+    readonly requires?: readonly RequiresEffect[];
+    /** Idempotency guard (→ gate-first token INSERT; duplicate short-circuits). */
+    readonly idempotency?: IdempotencyEffect;
+    /** Uniqueness guards (→ gate-first guard-row INSERT ON CONFLICT DO NOTHING + affected check). */
+    readonly unique?: readonly UniqueEffect[];
+    /** Derived / cascading counter updates (→ UPDATE … SET c = c ± n). */
+    readonly derive?: readonly DeriveEffect[];
+    /** Edge writes (→ M:N intermediate INSERT/DELETE or 1:N FK UPDATE). */
+    readonly edges?: readonly EdgeEffect[];
+    /** Domain events (→ outbox INSERT, same tx). */
+    readonly emits?: readonly EmitEffect[];
+}
+/** One lifecycle's save contract — the §6 effect set for a single phase. */
+export interface LifecycleContract {
+    readonly effects: LifecycleEffects;
+}
+/** The lifecycle phase a save-contract entry declares (the Command intent selects it). */
+export type WriteLifecyclePhase = 'create' | 'update' | 'remove';
+/** A model's per-lifecycle save contract (`entityWrites(...)` result). */
+export interface EntityWritesDefinition {
+    readonly create?: LifecycleContract;
+    readonly update?: LifecycleContract;
+    readonly remove?: LifecycleContract;
+}
+/**
+ * The recorder handed to the {@link entityWrites} / {@link edgeWrites} builder. Each method
+ * builds ONE §6 effect (pure data). `w.lifecycle({...})` gathers the effect arrays into a
+ * {@link LifecycleContract}. Every path-rooted value is validated eagerly ({@link parseEffectPath}).
+ */
+export interface WriteRecorder {
+    /** Build one lifecycle's save contract from its §6 effect arrays (each field optional). */
+    lifecycle(effects?: LifecycleEffects): LifecycleContract;
+    /** `requires` — a referential-integrity existence guard (§6). */
+    exists(table: string, keys: Readonly<Record<string, string>>): RequiresEffect;
+    /** `unique` — a composite-scope uniqueness guard (§6). */
+    unique(spec: {
+        readonly name: string;
+        readonly guardTable: string;
+        readonly scope: readonly string[];
+        readonly fields: readonly string[];
+    }): UniqueEffect;
+    /** `derive` — a cascade counter increment (§6). `amount` is the SSoT (no code default). */
+    increment(table: string, keys: Readonly<Record<string, string>>, attribute: string, amount: number): DeriveEffect;
+    /** `edges` — a many-to-many intermediate-table link/unlink (§6). */
+    edge(spec: {
+        readonly relation: 'm2m';
+        readonly action: 'set' | 'unset';
+        readonly table: string;
+        readonly columns: Readonly<Record<string, string>>;
+    }): EdgeEffect;
+    /** `edges` — a one-to-many foreign-key column set/unset on a related row (§6). */
+    edge(spec: {
+        readonly relation: 'fk';
+        readonly action: 'set' | 'unset';
+        readonly table: string;
+        readonly columns: Readonly<Record<string, string>>;
+        readonly where: Readonly<Record<string, string>>;
+    }): EdgeEffect;
+    /** `emits` — a domain event into an outbox table, same tx (§6). */
+    event(name: string, outboxTable: string, payload: Readonly<Record<string, string>>): EmitEffect;
+    /** `idempotency` — a client-token duplicate guard (§6). */
+    idempotentBy(table: string, column: string, token: string): IdempotencyEffect;
+}
+/** The per-lifecycle map an {@link entityWrites} builder returns. */
+export interface EntityWritesShape {
+    readonly create?: LifecycleContract;
+    readonly update?: LifecycleContract;
+    readonly remove?: LifecycleContract;
+}
+/**
+ * Declare a model's reusable write-time-relations save contract (spec §2.2 / §6): a
+ * per-lifecycle map `{ create?, update?, remove? }`, each value a `w.lifecycle({...})`
+ * carrying the §6 effect arrays. Stored on the model as
+ * `static readonly writes = entityWrites<Model>((w) => ({ … }))`.
+ *
+ * @typeParam M documentary model type (the recorder is structural).
+ * @throws if no lifecycle is declared, or a lifecycle is not built with `w.lifecycle(...)`.
+ */
+export declare function entityWrites<M = unknown>(builder: (w: WriteRecorder) => EntityWritesShape): EntityWritesDefinition;
+/**
+ * Declare an adjacency entity's edge-only write contract (spec §2.2 / §6 — the `edgeWrites`
+ * counterpart of graphddb's #82). It is a thin specialization of {@link entityWrites} whose
+ * lifecycles carry ONLY `edges` effects — the write side of a many-to-many / one-to-many
+ * relation entity. Kept distinct so an author signals intent (an edge entity vs a full
+ * save contract), matching graphddb's two coexisting `writes` forms.
+ *
+ * @throws if a lifecycle declares a non-edge effect (an edge entity has only edge writes).
+ */
+export declare function edgeWrites<M = unknown>(builder: (w: WriteRecorder) => EntityWritesShape): EntityWritesDefinition;
+/** Resolve the {@link LifecycleContract} for a Command intent, or undefined if not declared. */
+export declare function lifecycleFor(def: EntityWritesDefinition, phase: WriteLifecyclePhase): LifecycleContract | undefined;
+//# sourceMappingURL=writes.d.ts.map

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

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

package/dist/scp/writes.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * litedbmodel v2 SCP — write-time relations declaration vocabulary (WS5, #25; spec §6 / §2.2).
+ *
+ * `entityWrites` / `edgeWrites` declare the **write-side invariants / effects required for
+ * an entity to stay consistent** when it is created / updated / removed — the SQL-backend
+ * counterpart of graphddb's `entityWrites` save contract (`graphddb/src/define/entity-writes.ts`,
+ * same shape: a per-lifecycle map of `w.lifecycle({requires,unique,derive,edges,emits,idempotency})`).
+ * This module produces a PORTABLE declaration (pure data, no closures): every value that
+ * references the write is a **path-rooted string** (`$.input.<field>` = the mutation input,
+ * `$.entity.<field>` = the written row's RETURNING result). {@link ../write-plan} lowers the
+ * declaration + a base write op into an ordered, gate-first SQL transaction plan (§6 table).
+ *
+ * ## Path roots (spec §6 example) — the SSoT for every derived value
+ *
+ * A leaf value binds to an explicit root so its source is unambiguous and no engine-code
+ * fallback is ever needed (hard rule: defaults live in the declaration):
+ *   - `$.input.<field>`  — the Command's input port value (bc flat scope: `{ref:['<field>']}`).
+ *   - `$.entity.<field>` — the just-written row (the body write's RETURNING row), exposed to
+ *     the derive/edges/emits stages under the reserved `{@link ENTITY_ROOT}` binding.
+ *
+ * The declaration is INITIAL-scope (spec §6 / §13): single-statement Command + fixed-order
+ * write-time relations. It does NOT model the complex DAG derivation (WS8).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENTITY_ROOT = void 0;
+exports.parseEffectPath = parseEffectPath;
+exports.entityWrites = entityWrites;
+exports.edgeWrites = edgeWrites;
+exports.lifecycleFor = lifecycleFor;
+/** The reserved scope binding under which the body write's RETURNING row is exposed (`$.entity.*`). */
+exports.ENTITY_ROOT = '__entity';
+const PATH_RE = /^\$\.(input|entity)\.([A-Za-z_][A-Za-z0-9_]*)$/;
+const REF_PATH_RE = /^\$\.ref\.([A-Za-z_][A-Za-z0-9_]*)\.([A-Za-z_][A-Za-z0-9_]*)$/;
+/**
+ * Parse a path-rooted write-relation value string into an {@link EffectPath}. Fail-closed on
+ * a malformed path — a write-relation value MUST be `$.input.<field>`, `$.entity.<field>`, or
+ * `$.ref.<writeName>.<field>` (no free-form paths, no implicit root), so a typo is a loud build
+ * error, never a silent default (hard rule).
+ */
+function parseEffectPath(value) {
+    const m = PATH_RE.exec(value);
+    if (m !== null)
+        return { root: m[1], field: m[2] };
+    const r = REF_PATH_RE.exec(value);
+    if (r !== null)
+        return { root: 'ref', writeName: r[1], field: r[2] };
+    throw new Error(`write-time relations: '${value}' is not a valid path-rooted value; use ` +
+        `'$.input.<field>' (the Command input), '$.entity.<field>' (the sole written row), or ` +
+        `'$.ref.<writeName>.<field>' (a named upstream write's RETURNING row).`);
+}
+/** Assert every value in a path-rooted map parses (fail-closed on a malformed path). */
+function assertPaths(map) {
+    for (const v of Object.values(map))
+        parseEffectPath(v); // throws on malformed
+}
+const recorder = {
+    lifecycle(effects = {}) {
+        // Validate every declared effect's paths eagerly (build-time fail-closed).
+        for (const r of effects.requires ?? [])
+            assertPaths(r.keys);
+        if (effects.idempotency !== undefined)
+            parseEffectPath(effects.idempotency.token);
+        for (const u of effects.unique ?? []) {
+            u.scope.forEach((p) => parseEffectPath(p));
+            u.fields.forEach((p) => parseEffectPath(p));
+        }
+        for (const d of effects.derive ?? [])
+            assertPaths(d.keys);
+        for (const e of effects.edges ?? []) {
+            assertPaths(e.columns);
+            if (e.where !== undefined)
+                assertPaths(e.where);
+        }
+        for (const em of effects.emits ?? [])
+            assertPaths(em.payload);
+        return { effects: freezeEffects(effects) };
+    },
+    exists(table, keys) {
+        return { kind: 'requires', table, keys };
+    },
+    unique(spec) {
+        return { kind: 'unique', name: spec.name, guardTable: spec.guardTable, scope: spec.scope, fields: spec.fields };
+    },
+    increment(table, keys, attribute, amount) {
+        if (!Number.isFinite(amount)) {
+            throw new Error(`entityWrites: increment amount for '${table}.${attribute}' must be a finite number (got ${String(amount)})`);
+        }
+        return { kind: 'derive', table, keys, attribute, amount };
+    },
+    edge(spec) {
+        if (spec.relation === 'fk' && spec.where === undefined) {
+            throw new Error(`entityWrites: a 'fk' edge on '${spec.table}' requires a 'where' key map (the matched row's identity)`);
+        }
+        return {
+            kind: 'edge',
+            relation: spec.relation,
+            action: spec.action,
+            table: spec.table,
+            columns: spec.columns,
+            ...(spec.where !== undefined ? { where: spec.where } : {}),
+        };
+    },
+    event(name, outboxTable, payload) {
+        return { kind: 'emit', name, outboxTable, payload };
+    },
+    idempotentBy(table, column, token) {
+        return { kind: 'idempotency', table, column, token };
+    },
+};
+/** Keep only the present effect fields (an empty `w.lifecycle()` carries an empty set). */
+function freezeEffects(effects) {
+    const out = {};
+    if (effects.requires !== undefined)
+        out.requires = effects.requires;
+    if (effects.idempotency !== undefined)
+        out.idempotency = effects.idempotency;
+    if (effects.unique !== undefined)
+        out.unique = effects.unique;
+    if (effects.derive !== undefined)
+        out.derive = effects.derive;
+    if (effects.edges !== undefined)
+        out.edges = effects.edges;
+    if (effects.emits !== undefined)
+        out.emits = effects.emits;
+    return out;
+}
+/**
+ * Declare a model's reusable write-time-relations save contract (spec §2.2 / §6): a
+ * per-lifecycle map `{ create?, update?, remove? }`, each value a `w.lifecycle({...})`
+ * carrying the §6 effect arrays. Stored on the model as
+ * `static readonly writes = entityWrites<Model>((w) => ({ … }))`.
+ *
+ * @typeParam M documentary model type (the recorder is structural).
+ * @throws if no lifecycle is declared, or a lifecycle is not built with `w.lifecycle(...)`.
+ */
+function entityWrites(builder) {
+    void undefined;
+    const shape = builder(recorder);
+    if (shape.create === undefined && shape.update === undefined && shape.remove === undefined) {
+        throw new Error('entityWrites(...) must declare at least one lifecycle (`create` / `update` / `remove`).');
+    }
+    return {
+        ...(shape.create !== undefined ? { create: shape.create } : {}),
+        ...(shape.update !== undefined ? { update: shape.update } : {}),
+        ...(shape.remove !== undefined ? { remove: shape.remove } : {}),
+    };
+}
+/**
+ * Declare an adjacency entity's edge-only write contract (spec §2.2 / §6 — the `edgeWrites`
+ * counterpart of graphddb's #82). It is a thin specialization of {@link entityWrites} whose
+ * lifecycles carry ONLY `edges` effects — the write side of a many-to-many / one-to-many
+ * relation entity. Kept distinct so an author signals intent (an edge entity vs a full
+ * save contract), matching graphddb's two coexisting `writes` forms.
+ *
+ * @throws if a lifecycle declares a non-edge effect (an edge entity has only edge writes).
+ */
+function edgeWrites(builder) {
+    const def = entityWrites(builder);
+    for (const phase of ['create', 'update', 'remove']) {
+        const c = def[phase];
+        if (c === undefined)
+            continue;
+        const e = c.effects;
+        if (e.requires !== undefined || e.unique !== undefined || e.derive !== undefined || e.emits !== undefined || e.idempotency !== undefined) {
+            throw new Error(`edgeWrites: the '${phase}' lifecycle may declare ONLY 'edges' effects ` +
+                `(an edge entity carries only edge writes; use entityWrites for a full save contract).`);
+        }
+    }
+    return def;
+}
+/** Resolve the {@link LifecycleContract} for a Command intent, or undefined if not declared. */
+function lifecycleFor(def, phase) {
+    return def[phase];
+}
+//# sourceMappingURL=writes.js.map

package/dist/scp/writes.js.map

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