@chipmobilesdk/rn-local-db 0.4.0 → 0.5.0

package/lib/module/sqlite/row-codec.js

@@ -0,0 +1,176 @@
+"use strict";
+
+/**
+ * Table shape, and the payload-as-truth rule.
+ *
+ * Every read reconstructs the record from `payload` alone. The projected
+ * `f_*` columns are written on every write and consulted only by `WHERE` and
+ * `ORDER BY` — never by a read path (research.md R6).
+ *
+ * That single rule is what makes two requirements structural rather than
+ * carefully maintained. FR-018's byte fidelity holds because nothing else is
+ * consulted to rebuild a record, and FR-019's explicit-null versus
+ * absent-field distinction holds because a NULL projected column cannot be
+ * ambiguous if no read ever looks at it.
+ */
+
+import { collectionTable, hasSoftDelete, hasTimestamps, projectedColumn } from "../schema/declare.js";
+import { num, text } from "./values.js";
+export const RESERVED_COLUMNS = ['id', 'payload', 'created_at', 'updated_at', 'deleted_at'];
+
+/** SQLite affinity for a declared field type. */
+function affinityOf(field) {
+  switch (field.type) {
+    case 'number':
+    case 'timestamp':
+      return 'REAL';
+    case 'boolean':
+      return 'INTEGER';
+    case 'string':
+    default:
+      return 'TEXT';
+  }
+}
+export function createTableSql(schema) {
+  const columns = ['id TEXT PRIMARY KEY', 'payload TEXT NOT NULL', 'created_at INTEGER', 'updated_at INTEGER', 'deleted_at INTEGER', ...(schema.fields ?? []).map(field => `"${projectedColumn(field.name)}" ${affinityOf(field)}`)];
+  return `CREATE TABLE IF NOT EXISTS "${collectionTable(schema.name)}" (${columns.join(', ')})`;
+}
+export function addColumnSql(schema, field) {
+  return `ALTER TABLE "${collectionTable(schema.name)}" ADD COLUMN "${projectedColumn(field.name)}" ${affinityOf(field)}`;
+}
+
+/**
+ * The name an index has in the database file.
+ *
+ * Index names are database-wide in SQLite, but declared per collection. Until
+ * 0.2.0 the declared name was used as is, so a second collection declaring an
+ * index of the same name hit `IF NOT EXISTS` and silently got no index — a
+ * UNIQUE constraint included. The double underscore keeps a declared name from
+ * colliding with the package's own `<table>_live` index.
+ */
+export function physicalIndexName(schema, declaredName) {
+  return `${collectionTable(schema.name)}__${declaredName}`;
+}
+
+/** The declared name back from a physical one, for reporting to the app. */
+export function declaredIndexName(schema, physicalName) {
+  const prefix = `${collectionTable(schema.name)}__`;
+  return physicalName.startsWith(prefix) ? physicalName.slice(prefix.length) : physicalName;
+}
+export function createIndexSql(schema) {
+  const table = collectionTable(schema.name);
+  const statements = (schema.indexes ?? []).map(index => {
+    const columns = index.fields.map(field => `"${projectedColumn(field)}"`).join(', ');
+    return `CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX IF NOT EXISTS "${physicalIndexName(schema, index.name)}" ON "${table}" (${columns})`;
+  });
+  if (hasSoftDelete(schema)) {
+    // Every default query carries `deleted_at IS NULL`, so without this the
+    // exclusion turns the cheapest possible filter into a full scan.
+    statements.push(`CREATE INDEX IF NOT EXISTS "${table}_live" ON "${table}" (deleted_at)`);
+  }
+  return statements;
+}
+
+/**
+ * Project a declared field for the WHERE and ORDER BY columns.
+ *
+ * Anything that is not a comparable primitive projects to NULL. A nested
+ * object has no defensible ordering, and inventing one would make a filter
+ * silently match records a consumer never meant to select.
+ */
+export function projectValue(data, field) {
+  if (!Object.prototype.hasOwnProperty.call(data, field.name)) {
+    return null;
+  }
+  const value = data[field.name];
+  if (value === null) {
+    return null;
+  }
+  switch (typeof value) {
+    case 'boolean':
+      return value ? 1 : 0;
+    case 'number':
+      return Number.isFinite(value) ? value : null;
+    case 'string':
+      return value;
+    default:
+      return null;
+  }
+}
+export function projectedValues(schema, data) {
+  return (schema.fields ?? []).map(field => projectValue(data, field));
+}
+export function projectedColumnNames(schema) {
+  return (schema.fields ?? []).map(field => projectedColumn(field.name));
+}
+
+/** Serialize on the way in, so a caller mutating its object cannot change
+ * what is stored (FR-022). */
+export function encodePayload(data) {
+  return JSON.stringify(data ?? {});
+}
+/**
+ * Rebuild a record from the payload column and nothing else.
+ *
+ * The timestamp and soft-delete fields are surfaced only when the collection
+ * declared them, so a consumer cannot come to depend on a field the schema
+ * never promised.
+ */
+export function decodeRow(schema, row) {
+  const record = {
+    id: text(row.id),
+    data: JSON.parse(text(row.payload))
+  };
+  if (hasTimestamps(schema)) {
+    if (row.created_at != null) {
+      record.createdAt = num(row.created_at);
+    }
+    if (row.updated_at != null) {
+      record.updatedAt = num(row.updated_at);
+    }
+  }
+  if (hasSoftDelete(schema)) {
+    record.deletedAt = row.deleted_at == null ? null : num(row.deleted_at);
+  }
+  return record;
+}
+export function insertColumns(schema, id, data, now, /** The payload already serialized by the budget check, to avoid a second pass. */
+payload = encodePayload(data)) {
+  const columns = ['id', 'payload'];
+  const values = [id, payload];
+  if (hasTimestamps(schema)) {
+    columns.push('created_at', 'updated_at');
+    values.push(now, now);
+  }
+  if (hasSoftDelete(schema)) {
+    columns.push('deleted_at');
+    values.push(null);
+  }
+  const projected = projectedValues(schema, data);
+  for (const [index, name] of projectedColumnNames(schema).entries()) {
+    columns.push(name);
+    values.push(projected[index]);
+  }
+  return {
+    columns,
+    values
+  };
+}
+export function updateAssignments(schema, data, now, payload = encodePayload(data)) {
+  const columns = ['payload'];
+  const values = [payload];
+  if (hasTimestamps(schema)) {
+    columns.push('updated_at');
+    values.push(now);
+  }
+  const projected = projectedValues(schema, data);
+  for (const [index, name] of projectedColumnNames(schema).entries()) {
+    columns.push(name);
+    values.push(projected[index]);
+  }
+  return {
+    columns,
+    values
+  };
+}
+//# sourceMappingURL=row-codec.js.map

package/lib/module/sqlite/row-codec.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["collectionTable","hasSoftDelete","hasTimestamps","projectedColumn","num","text","RESERVED_COLUMNS","affinityOf","field","type","createTableSql","schema","columns","fields","map","name","join","addColumnSql","physicalIndexName","declaredName","declaredIndexName","physicalName","prefix","startsWith","slice","length","createIndexSql","table","statements","indexes","index","unique","push","projectValue","data","Object","prototype","hasOwnProperty","call","value","Number","isFinite","projectedValues","projectedColumnNames","encodePayload","JSON","stringify","decodeRow","row","record","id","parse","payload","created_at","createdAt","updated_at","updatedAt","deletedAt","deleted_at","insertColumns","now","values","projected","entries","updateAssignments"],"sourceRoot":"../../../src","sources":["sqlite/row-codec.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/sqlite/sql-builder.js

@@ -0,0 +1,247 @@
+"use strict";
+
+/**
+ * Filter tree to parameterized SQL.
+ *
+ * Nothing a consumer supplies is ever concatenated into a statement. Field
+ * names are resolved through the schema first — validation has already run
+ * and rejected anything undeclared (FR-034) — so the only identifiers that
+ * reach SQL are ones this package generated from a declaration it checked.
+ * Values bind as parameters, without exception. Injection stops being a thing
+ * to remember and becomes a thing the shape of the code prevents.
+ *
+ * The other half of this file is keyset pagination. `OFFSET` was rejected for
+ * two measured reasons (research.md R6): it degrades linearly at the 100,000
+ * record budget because the engine still walks the skipped rows, and it
+ * shifts pages under concurrent writes so a record can be skipped or returned
+ * twice — the exact failure SC-007 forbids.
+ */
+
+import { projectedColumn } from "../schema/declare.js";
+const TRUE = {
+  sql: '1',
+  params: []
+};
+const FALSE = {
+  sql: '0',
+  params: []
+};
+function columnFor(field) {
+  return field === 'id' ? 'id' : `"${projectedColumn(field)}"`;
+}
+
+/**
+ * The JSON path for a declared field.
+ *
+ * Safe to interpolate: the field name came from a schema declaration that
+ * validation already matched against `^[A-Za-z][A-Za-z0-9_]{0,62}$`, so it
+ * cannot carry a quote, a dollar sign, or a path separator.
+ */
+function jsonType(field) {
+  return `json_type(payload, '$.${field}')`;
+}
+
+/** Present, and holding something a comparison can be defined over. */
+function presentPrimitive(field) {
+  return `(${jsonType(field)} IS NOT NULL AND ${jsonType(field)} NOT IN ('object', 'array'))`;
+}
+
+/** Present and explicitly null — the condition `isNull` actually means. */
+function isExplicitNull(field) {
+  return `${jsonType(field)} = 'null'`;
+}
+
+/** Booleans project to 0/1, so a bound parameter has to match. */
+function bind(value) {
+  return typeof value === 'boolean' ? value ? 1 : 0 : value;
+}
+function comparison(node) {
+  const field = node.field;
+  const column = columnFor(field);
+  switch (node.op) {
+    case 'exists':
+      return {
+        sql: node.value ? `${jsonType(field)} IS NOT NULL` : `${jsonType(field)} IS NULL`,
+        params: []
+      };
+    case 'isNull':
+      return {
+        sql: isExplicitNull(field),
+        params: []
+      };
+    case 'isNotNull':
+      return {
+        sql: `(${jsonType(field)} IS NOT NULL AND ${jsonType(field)} != 'null')`,
+        params: []
+      };
+    case 'eq':
+      // Matching an explicit null needs the JSON type: `col = NULL` is
+      // NULL in SQL, which is not true, and a projected NULL cannot tell
+      // "absent" from "null" on its own.
+      return node.value === null ? {
+        sql: isExplicitNull(field),
+        params: []
+      } : {
+        sql: `${column} = ?`,
+        params: [bind(node.value)]
+      };
+    case 'ne':
+      return node.value === null ? {
+        sql: `(${presentPrimitive(field)} AND ${jsonType(field)} != 'null')`,
+        params: []
+      } : {
+        sql: `(${presentPrimitive(field)} AND ${column} IS NOT ?)`,
+        params: [bind(node.value)]
+      };
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      {
+        if (node.value === null) {
+          // An ordered comparison against null has no answer; SQL would
+          // return NULL and the in-memory adapter returns false. Being
+          // explicit keeps the two identical.
+          return FALSE;
+        }
+        const operator = {
+          lt: '<',
+          lte: '<=',
+          gt: '>',
+          gte: '>='
+        }[node.op];
+        return {
+          sql: `(${column} IS NOT NULL AND ${column} ${operator} ?)`,
+          params: [bind(node.value)]
+        };
+      }
+    case 'between':
+      {
+        const [low, high] = node.value;
+        if (low === null || high === null) {
+          return FALSE;
+        }
+        return {
+          sql: `(${column} IS NOT NULL AND ${column} BETWEEN ? AND ?)`,
+          params: [bind(low), bind(high)]
+        };
+      }
+    case 'in':
+    case 'nin':
+      {
+        const values = node.value;
+        const nonNull = values.filter(value => value !== null);
+        const acceptsNull = values.length !== nonNull.length;
+        const clauses = [];
+        const params = [];
+        if (nonNull.length > 0) {
+          clauses.push(`${column} IN (${nonNull.map(() => '?').join(', ')})`);
+          params.push(...nonNull.map(value => bind(value)));
+        }
+        if (acceptsNull) {
+          clauses.push(isExplicitNull(field));
+        }
+        const membership = clauses.length > 0 ? `(${clauses.join(' OR ')})` : '0';
+        if (node.op === 'in') {
+          return {
+            sql: membership,
+            params
+          };
+        }
+        // `nin` excludes, but only among records that have the field at
+        // all: an absent field satisfies no comparison, negated or not.
+        return {
+          sql: `(${presentPrimitive(field)} AND NOT IFNULL(${membership}, 0))`,
+          params
+        };
+      }
+    default:
+      return FALSE;
+  }
+}
+export function buildFilter(node) {
+  if (!node) {
+    return TRUE;
+  }
+  switch (node.op) {
+    case 'and':
+    case 'or':
+      {
+        const parts = node.nodes.map(child => buildFilter(child));
+        return {
+          sql: `(${parts.map(part => part.sql).join(node.op === 'and' ? ' AND ' : ' OR ')})`,
+          params: parts.flatMap(part => part.params)
+        };
+      }
+    case 'not':
+      {
+        const inner = buildFilter(node.node);
+        // IFNULL, because NOT NULL is NULL in SQL and would quietly drop
+        // rows the in-memory adapter keeps.
+        return {
+          sql: `(NOT IFNULL(${inner.sql}, 0))`,
+          params: inner.params
+        };
+      }
+    default:
+      return comparison(node);
+  }
+}
+export function buildOrderBy(sort) {
+  return sort.map(key => `${columnFor(key.field)} ${key.direction === 'desc' ? 'DESC' : 'ASC'}`).join(', ');
+}
+
+/**
+ * The keyset predicate: everything strictly after the cursor position.
+ *
+ * Lexicographic across the sort keys — equal on the first means the second
+ * decides, down to the `id` tiebreaker that guarantees a total order. NULL is
+ * treated as smaller than every value, matching both SQLite's default
+ * ordering and `compareValues`, so the two adapters page identically.
+ */
+export function buildKeysetPredicate(sort, anchor) {
+  const params = [];
+  const build = index => {
+    if (index >= sort.length) {
+      return '0';
+    }
+    const key = sort[index];
+    const column = columnFor(key.field);
+    const value = anchor[index] ?? null;
+    const descending = key.direction === 'desc';
+    let strictly;
+    if (descending) {
+      if (value === null) {
+        // Nothing sorts before null, so a descending walk anchored on
+        // null has nothing left ahead of it on this key.
+        strictly = '0';
+      } else {
+        strictly = `(${column} IS NULL OR ${column} < ?)`;
+        params.push(bind(value));
+      }
+    } else if (value === null) {
+      strictly = `${column} IS NOT NULL`;
+    } else {
+      strictly = `${column} > ?`;
+      params.push(bind(value));
+    }
+    const equal = `${column} IS ?`;
+    const equalParam = bind(value);
+    if (index === sort.length - 1) {
+      return strictly;
+    }
+
+    // Params are pushed in the order the fragments are concatenated, so the
+    // equality parameter has to land between this key's comparison and the
+    // next key's fragment.
+    const head = `(${strictly} OR (${equal} AND `;
+    params.push(equalParam);
+    const tail = build(index + 1);
+    return `${head}${tail}))`;
+  };
+  return {
+    sql: build(0),
+    params
+  };
+}
+//# sourceMappingURL=sql-builder.js.map

package/lib/module/sqlite/sql-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["projectedColumn","TRUE","sql","params","FALSE","columnFor","field","jsonType","presentPrimitive","isExplicitNull","bind","value","comparison","node","column","op","operator","lt","lte","gt","gte","low","high","values","nonNull","filter","acceptsNull","length","clauses","push","map","join","membership","buildFilter","parts","nodes","child","part","flatMap","inner","buildOrderBy","sort","key","direction","buildKeysetPredicate","anchor","build","index","descending","strictly","equal","equalParam","head","tail"],"sourceRoot":"../../../src","sources":["sqlite/sql-builder.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/sqlite/statements.js

@@ -0,0 +1,49 @@
+"use strict";
+
+/**
+ * The write statements, built in one place (LDB-12).
+ *
+ * The collection API and the batch each used to assemble their own INSERT and
+ * UPDATE text. Two copies of the same rule is how a batch upsert came to treat
+ * a soft-deleted row differently from a collection upsert.
+ */
+
+import { collectionTable, hasSoftDelete } from "../schema/declare.js";
+import { insertColumns, updateAssignments } from "./row-codec.js";
+// Built once per table and column list rather than on every write (PERF-10).
+const insertTexts = new Map();
+function insertText(table, columns) {
+  const key = `${table}|${columns.join(',')}`;
+  let sql = insertTexts.get(key);
+  if (sql === undefined) {
+    sql = `INSERT INTO "${table}" (${columns.map(name => `"${name}"`).join(', ')}) VALUES (${columns.map(() => '?').join(', ')})`;
+    insertTexts.set(key, sql);
+  }
+  return sql;
+}
+
+/**
+ * `ignore` leaves a row that already holds the id untouched and reports zero
+ * rows affected, so a conflict is detected without a SELECT beforehand.
+ */
+export function insertStatement(schema, id, data, now, payload, onConflict = 'fail') {
+  const {
+    columns,
+    values
+  } = insertColumns(schema, id, data, now, payload);
+  const sql = insertText(collectionTable(schema.name), columns);
+  return [onConflict === 'ignore' ? `${sql} ON CONFLICT(id) DO NOTHING` : sql, values];
+}
+export function updateStatement(schema, id, data, now, payload, options = {}) {
+  const {
+    columns,
+    values
+  } = updateAssignments(schema, data, now, payload);
+  const assignments = columns.map(name => `"${name}" = ?`);
+  if (options.restore === true && hasSoftDelete(schema)) {
+    assignments.push('deleted_at = NULL');
+  }
+  const live = options.liveOnly === true ? ' AND deleted_at IS NULL' : '';
+  return [`UPDATE "${collectionTable(schema.name)}" SET ${assignments.join(', ')} WHERE id = ?${live}`, [...values, id]];
+}
+//# sourceMappingURL=statements.js.map

package/lib/module/sqlite/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["collectionTable","hasSoftDelete","insertColumns","updateAssignments","insertTexts","Map","insertText","table","columns","key","join","sql","get","undefined","map","name","set","insertStatement","schema","id","data","now","payload","onConflict","values","updateStatement","options","assignments","restore","push","live","liveOnly"],"sourceRoot":"../../../src","sources":["sqlite/statements.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,eAAe,EAAEC,aAAa,QAAQ,sBAAmB;AAElE,SAASC,aAAa,EAAEC,iBAAiB,QAAQ,gBAAa;AAM9D;AACA,MAAMC,WAAW,GAAG,IAAIC,GAAG,CAAiB,CAAC;AAE7C,SAASC,UAAUA,CAACC,KAAa,EAAEC,OAA0B,EAAU;EACtE,MAAMC,GAAG,GAAG,GAAGF,KAAK,IAAIC,OAAO,CAACE,IAAI,CAAC,GAAG,CAAC,EAAE;EAC3C,IAAIC,GAAG,GAAGP,WAAW,CAACQ,GAAG,CAACH,GAAG,CAAC;EAC9B,IAAIE,GAAG,KAAKE,SAAS,EAAE;IACtBF,GAAG,GAAG,gBAAgBJ,KAAK,MAAMC,OAAO,CAACM,GAAG,CAACC,IAAI,IAAI,IAAIA,IAAI,GAAG,CAAC,CAACL,IAAI,CAAC,IAAI,CAAC,aAAaF,OAAO,CAC9FM,GAAG,CAAC,MAAM,GAAG,CAAC,CACdJ,IAAI,CAAC,IAAI,CAAC,GAAG;IACfN,WAAW,CAACY,GAAG,CAACP,GAAG,EAAEE,GAAG,CAAC;EAC1B;EACA,OAAOA,GAAG;AACX;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASM,eAAeA,CAC9BC,MAAwB,EACxBC,EAAU,EACVC,IAAgB,EAChBC,GAAW,EACXC,OAAe,EACfC,UAA6B,GAAG,MAAM,EAC1B;EACZ,MAAM;IAAEf,OAAO;IAAEgB;EAAO,CAAC,GAAGtB,aAAa,CAACgB,MAAM,EAAEC,EAAE,EAAEC,IAAI,EAAEC,GAAG,EAAEC,OAAO,CAAC;EACzE,MAAMX,GAAG,GAAGL,UAAU,CAACN,eAAe,CAACkB,MAAM,CAACH,IAAI,CAAC,EAAEP,OAAO,CAAC;EAC7D,OAAO,CAACe,UAAU,KAAK,QAAQ,GAAG,GAAGZ,GAAG,6BAA6B,GAAGA,GAAG,EAAEa,MAAM,CAAC;AACrF;AASA,OAAO,SAASC,eAAeA,CAC9BP,MAAwB,EACxBC,EAAU,EACVC,IAAgB,EAChBC,GAAW,EACXC,OAAe,EACfI,OAAsB,GAAG,CAAC,CAAC,EACf;EACZ,MAAM;IAAElB,OAAO;IAAEgB;EAAO,CAAC,GAAGrB,iBAAiB,CAACe,MAAM,EAAEE,IAAI,EAAEC,GAAG,EAAEC,OAAO,CAAC;EACzE,MAAMK,WAAW,GAAGnB,OAAO,CAACM,GAAG,CAACC,IAAI,IAAI,IAAIA,IAAI,OAAO,CAAC;EACxD,IAAIW,OAAO,CAACE,OAAO,KAAK,IAAI,IAAI3B,aAAa,CAACiB,MAAM,CAAC,EAAE;IACtDS,WAAW,CAACE,IAAI,CAAC,mBAAmB,CAAC;EACtC;EACA,MAAMC,IAAI,GAAGJ,OAAO,CAACK,QAAQ,KAAK,IAAI,GAAG,yBAAyB,GAAG,EAAE;EACvE,OAAO,CACN,WAAW/B,eAAe,CAACkB,MAAM,CAACH,IAAI,CAAC,SAASY,WAAW,CAACjB,IAAI,CAAC,IAAI,CAAC,gBAAgBoB,IAAI,EAAE,EAC5F,CAAC,GAAGN,MAAM,EAAEL,EAAE,CAAC,CACf;AACF","ignoreList":[]}

package/lib/module/sqlite/transaction-queue.js

@@ -0,0 +1,75 @@
+"use strict";
+
+/**
+ * The per-handle queue that keeps a transaction to itself.
+ *
+ * A transaction holds the queue until it settles; work arriving meanwhile
+ * through the handle waits its turn and then runs on its own, instead of
+ * joining the transaction and vanishing with its rollback (LDB-01). Shared by
+ * the SQLite connection and the memory adapter so both isolate the same way.
+ *
+ * Pure: no engine, no React, so the memory adapter can use it without loading
+ * native code.
+ */
+
+import { DiagnosticCodes } from "../contract/errors.js";
+import { raise } from "../diagnostics/errors.js";
+
+/**
+ * How long work through the handle waits behind a transaction before it is
+ * refused.
+ *
+ * Not a performance budget: it exists for the one wait that never ends. A
+ * transaction body that awaits the handle's own `collection()` or
+ * `attachments()` is waiting on work queued behind itself. Until 0.2.0 that
+ * work ran inside the transaction; now it is refused after this long with a
+ * message naming `tx.collection()` / `tx.attachments()`, and the transaction
+ * rolls back, rather than both waiting forever.
+ */
+export const TRANSACTION_WAIT_LIMIT_MS = 10_000;
+export function createTransactionQueue(waitLimitMs = TRANSACTION_WAIT_LIMIT_MS) {
+  /** Tail of the queue. Never rejects, so one failure cannot stall the rest. */
+  let tail = Promise.resolve();
+  /** Transactions queued or running. Only work behind one of them can deadlock. */
+  let transactions = 0;
+  const enqueue = work => {
+    const run = tail.then(work, work);
+    tail = run.catch(() => undefined);
+    return run;
+  };
+  return {
+    run(work) {
+      if (transactions === 0) {
+        return enqueue(work);
+      }
+      let abandoned = false;
+      let timer;
+      const started = enqueue(() => {
+        clearTimeout(timer);
+        // Refused while waiting: it must not run late, after its caller was
+        // already told it failed.
+        return abandoned ? Promise.resolve(undefined) : work();
+      });
+      const refused = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          abandoned = true;
+          try {
+            raise(DiagnosticCodes.TRANSACTION_STATE, {
+              message: 'waited too long behind an in-flight transaction; inside a transaction body use tx.collection() and tx.attachments(), not the handle'
+            });
+          } catch (error) {
+            reject(error);
+          }
+        }, waitLimitMs);
+      });
+      return Promise.race([started, refused]);
+    },
+    runTransaction(work) {
+      transactions += 1;
+      return enqueue(work).finally(() => {
+        transactions -= 1;
+      });
+    }
+  };
+}
+//# sourceMappingURL=transaction-queue.js.map

package/lib/module/sqlite/transaction-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DiagnosticCodes","raise","TRANSACTION_WAIT_LIMIT_MS","createTransactionQueue","waitLimitMs","tail","Promise","resolve","transactions","enqueue","work","run","then","catch","undefined","abandoned","timer","started","clearTimeout","refused","_","reject","setTimeout","TRANSACTION_STATE","message","error","race","runTransaction","finally"],"sourceRoot":"../../../src","sources":["sqlite/transaction-queue.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,eAAe,QAAQ,uBAAoB;AACpD,SAASC,KAAK,QAAQ,0BAAuB;;AAE7C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,yBAAyB,GAAG,MAAM;AAS/C,OAAO,SAASC,sBAAsBA,CACrCC,WAAmB,GAAGF,yBAAyB,EAC5B;EACnB;EACA,IAAIG,IAAsB,GAAGC,OAAO,CAACC,OAAO,CAAC,CAAC;EAC9C;EACA,IAAIC,YAAY,GAAG,CAAC;EAEpB,MAAMC,OAAO,GAAOC,IAAsB,IAAiB;IAC1D,MAAMC,GAAG,GAAGN,IAAI,CAACO,IAAI,CAACF,IAAI,EAAEA,IAAI,CAAC;IACjCL,IAAI,GAAGM,GAAG,CAACE,KAAK,CAAC,MAAMC,SAAS,CAAC;IACjC,OAAOH,GAAG;EACX,CAAC;EAED,OAAO;IACNA,GAAGA,CAAID,IAAsB,EAAc;MAC1C,IAAIF,YAAY,KAAK,CAAC,EAAE;QACvB,OAAOC,OAAO,CAACC,IAAI,CAAC;MACrB;MAEA,IAAIK,SAAS,GAAG,KAAK;MACrB,IAAIC,KAAgD;MACpD,MAAMC,OAAO,GAAGR,OAAO,CAAC,MAAM;QAC7BS,YAAY,CAACF,KAAK,CAAC;QACnB;QACA;QACA,OAAOD,SAAS,GAAGT,OAAO,CAACC,OAAO,CAACO,SAAc,CAAC,GAAGJ,IAAI,CAAC,CAAC;MAC5D,CAAC,CAAC;MACF,MAAMS,OAAO,GAAG,IAAIb,OAAO,CAAQ,CAACc,CAAC,EAAEC,MAAM,KAAK;QACjDL,KAAK,GAAGM,UAAU,CAAC,MAAM;UACxBP,SAAS,GAAG,IAAI;UAChB,IAAI;YACHd,KAAK,CAACD,eAAe,CAACuB,iBAAiB,EAAE;cACxCC,OAAO,EACN;YACF,CAAC,CAAC;UACH,CAAC,CAAC,OAAOC,KAAK,EAAE;YACfJ,MAAM,CAACI,KAAK,CAAC;UACd;QACD,CAAC,EAAErB,WAAW,CAAC;MAChB,CAAC,CAAC;MACF,OAAOE,OAAO,CAACoB,IAAI,CAAC,CAACT,OAAO,EAAEE,OAAO,CAAC,CAAC;IACxC,CAAC;IAEDQ,cAAcA,CAAIjB,IAAsB,EAAc;MACrDF,YAAY,IAAI,CAAC;MACjB,OAAOC,OAAO,CAACC,IAAI,CAAC,CAACkB,OAAO,CAAC,MAAM;QAClCpB,YAAY,IAAI,CAAC;MAClB,CAAC,CAAC;IACH;EACD,CAAC;AACF","ignoreList":[]}

package/lib/module/sqlite/transactions.js

@@ -0,0 +1,29 @@
+"use strict";
+
+/**
+ * The transaction primitive.
+ *
+ * A transaction never spans two scopes, and not because a check forbids it:
+ * a transaction runs on one connection, a connection is opened against one
+ * scope's file, and the public surface offers no way to reach a second one
+ * from inside. FR-038 is a type error rather than a runtime one (research.md
+ * R2).
+ *
+ * Rollback fidelity is SQLite's, not this package's. A failure at any step
+ * unwinds through the engine's own `ROLLBACK`, which is the only way SC-006's
+ * "identical to its pre-transaction state, every time" survives a process
+ * kill halfway through.
+ */
+
+/**
+ * Run `body` inside one transaction on one scope.
+ *
+ * Deliberately thin. The interesting behavior — read-your-own-writes,
+ * terminal-state rejection, what a settled transaction does when used again —
+ * belongs to `adapter/transaction.ts`, where both adapters can be held to the
+ * same rules.
+ */
+export function runInTransaction(connection, body) {
+  return connection.transaction(body);
+}
+//# sourceMappingURL=transactions.js.map

package/lib/module/sqlite/transactions.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["runInTransaction","connection","body","transaction"],"sourceRoot":"../../../src","sources":["sqlite/transactions.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,gBAAgBA,CAC/BC,UAAsB,EACtBC,IAA6C,EAChC;EACb,OAAOD,UAAU,CAACE,WAAW,CAACD,IAAI,CAAC;AACpC","ignoreList":[]}

package/lib/module/sqlite/values.js

@@ -0,0 +1,24 @@
+"use strict";
+
+/**
+ * Reading values back out of a result row.
+ *
+ * The engine hands back `unknown` per column, and every read site would
+ * otherwise repeat the same `String(...)` / `Number(...)` coercion with a
+ * slightly different null check. One place to do it means one place where the
+ * "NULL means absent, not empty string" rule is decided.
+ */
+
+export function text(value) {
+  return typeof value === 'string' ? value : String(value);
+}
+export function num(value) {
+  return typeof value === 'number' ? value : Number(value);
+}
+export function maybeText(value) {
+  return value == null ? null : text(value);
+}
+export function maybeNum(value) {
+  return value == null ? null : num(value);
+}
+//# sourceMappingURL=values.js.map

package/lib/module/sqlite/values.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["text","value","String","num","Number","maybeText","maybeNum"],"sourceRoot":"../../../src","sources":["sqlite/values.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,OAAO,SAASA,IAAIA,CAACC,KAAc,EAAU;EAC5C,OAAO,OAAOA,KAAK,KAAK,QAAQ,GAAGA,KAAK,GAAGC,MAAM,CAACD,KAAkC,CAAC;AACtF;AAEA,OAAO,SAASE,GAAGA,CAACF,KAAc,EAAU;EAC3C,OAAO,OAAOA,KAAK,KAAK,QAAQ,GAAGA,KAAK,GAAGG,MAAM,CAACH,KAAwB,CAAC;AAC5E;AAEA,OAAO,SAASI,SAASA,CAACJ,KAAc,EAAiB;EACxD,OAAOA,KAAK,IAAI,IAAI,GAAG,IAAI,GAAGD,IAAI,CAACC,KAAK,CAAC;AAC1C;AAEA,OAAO,SAASK,QAAQA,CAACL,KAAc,EAAiB;EACvD,OAAOA,KAAK,IAAI,IAAI,GAAG,IAAI,GAAGE,GAAG,CAACF,KAAK,CAAC;AACzC","ignoreList":[]}