@chipmobilesdk/rn-local-db 0.4.0 → 0.5.0

package/lib/commonjs/diagnostics/map-native.js

@@ -0,0 +1,98 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.mapNativeError = mapNativeError;
+exports.raiseNative = raiseNative;
+var _errors = require("../contract/errors.js");
+var _errors2 = require("./errors.js");
+/**
+ * Native error to diagnostic code.
+ *
+ * The three failures FR-076 insists stay apart — a full disk, a filesystem
+ * the app cannot reach, and a corrupt database — arrive from SQLite and from
+ * the filesystem peer as ordinary errors with a string on them. Collapsing
+ * them into one write failure would be the easy thing and the wrong one: an
+ * app frees space for the first, retries after unlock for the second, and has
+ * to offer a reset for the third.
+ *
+ * Only the code is derived here. The message never travels — it is redacted
+ * at construction by `StorageError` (FR-079).
+ */
+
+function textOf(error) {
+  if (error instanceof Error) {
+    return `${error.message} ${error.code ?? ''}`;
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  return '';
+}
+const DISK_FULL = /SQLITE_FULL|database or disk is full|ENOSPC|no space left/i;
+const NOT_A_DATABASE = /SQLITE_NOTADB|file is not a database|encrypted or is not a database/i;
+const CORRUPT = /SQLITE_CORRUPT|database disk image is malformed|malformed database/i;
+const CONFLICT = /UNIQUE constraint failed|PRIMARY KEY must be unique|SQLITE_CONSTRAINT_PRIMARYKEY/i;
+const ACCESS = /SQLITE_CANTOPEN|SQLITE_READONLY|SQLITE_PERM|SQLITE_AUTH|EACCES|EPERM|EROFS|ENOENT|EISDIR/i;
+const BUSY = /SQLITE_BUSY|SQLITE_LOCKED|database is locked/i;
+function mapNativeError(error, context) {
+  const text = textOf(error);
+  if (DISK_FULL.test(text)) {
+    return _errors.DiagnosticCodes.DISK_FULL;
+  }
+  if (NOT_A_DATABASE.test(text)) {
+    // A wrong key and a corrupt file are indistinguishable from the engine's
+    // answer alone. Reporting corruption for a wrong key would push an app
+    // towards destroying recoverable data, so the encrypted case wins.
+    return context.encrypted ? _errors.DiagnosticCodes.KEY_INVALID : _errors.DiagnosticCodes.CORRUPTION;
+  }
+  if (CORRUPT.test(text)) {
+    return _errors.DiagnosticCodes.CORRUPTION;
+  }
+  if (CONFLICT.test(text)) {
+    return _errors.DiagnosticCodes.RECORD_CONFLICT;
+  }
+  if (ACCESS.test(text)) {
+    return _errors.DiagnosticCodes.STORAGE_ACCESS;
+  }
+  if (BUSY.test(text)) {
+    // Retryable, and distinct from a permanent write failure.
+    return context.operation === 'transaction' ? _errors.DiagnosticCodes.TRANSACTION_FAILED : _errors.DiagnosticCodes.WRITE_FAILED;
+  }
+  switch (context.operation) {
+    case 'open':
+      return _errors.DiagnosticCodes.OPEN_FAILED;
+    case 'read':
+      return _errors.DiagnosticCodes.STORAGE_ACCESS;
+    case 'transaction':
+      return _errors.DiagnosticCodes.TRANSACTION_FAILED;
+    case 'attachment':
+      return _errors.DiagnosticCodes.ATTACHMENT_WRITE_FAILED;
+    case 'delete':
+    case 'write':
+    default:
+      return _errors.DiagnosticCodes.WRITE_FAILED;
+  }
+}
+
+/**
+ * Re-raise a native failure as a typed one, preserving an error the package
+ * already classified rather than reclassifying it as a generic write failure.
+ */
+function raiseNative(error, context) {
+  if ((0, _errors2.isStorageError)(error)) {
+    throw error;
+  }
+  (0, _errors2.raise)(mapNativeError(error, context), {
+    // The native message is deliberately not the error's message. It goes
+    // through `cause`, which redacts it — passing it here as well would be
+    // two chances to leak the same string for no extra information.
+    message: `native ${context.operation} failed`,
+    detail: {
+      operation: context.operation
+    },
+    cause: error
+  });
+}
+//# sourceMappingURL=map-native.js.map

package/lib/commonjs/diagnostics/map-native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_errors","require","_errors2","textOf","error","Error","message","code","DISK_FULL","NOT_A_DATABASE","CORRUPT","CONFLICT","ACCESS","BUSY","mapNativeError","context","text","test","DiagnosticCodes","encrypted","KEY_INVALID","CORRUPTION","RECORD_CONFLICT","STORAGE_ACCESS","operation","TRANSACTION_FAILED","WRITE_FAILED","OPEN_FAILED","ATTACHMENT_WRITE_FAILED","raiseNative","isStorageError","raise","detail","cause"],"sourceRoot":"../../../src","sources":["diagnostics/map-native.ts"],"mappings":";;;;;;;AAcA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,QAAA,GAAAD,OAAA;AAfA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAgBA,SAASE,MAAMA,CAACC,KAAc,EAAU;EACvC,IAAIA,KAAK,YAAYC,KAAK,EAAE;IAC3B,OAAO,GAAGD,KAAK,CAACE,OAAO,IAAKF,KAAK,CAAuBG,IAAI,IAAI,EAAE,EAAE;EACrE;EACA,IAAI,OAAOH,KAAK,KAAK,QAAQ,EAAE;IAC9B,OAAOA,KAAK;EACb;EACA,OAAO,EAAE;AACV;AAEA,MAAMI,SAAS,GAAG,4DAA4D;AAC9E,MAAMC,cAAc,GAAG,sEAAsE;AAC7F,MAAMC,OAAO,GAAG,qEAAqE;AACrF,MAAMC,QAAQ,GACb,mFAAmF;AACpF,MAAMC,MAAM,GACX,2FAA2F;AAC5F,MAAMC,IAAI,GAAG,+CAA+C;AAErD,SAASC,cAAcA,CAACV,KAAc,EAAEW,OAAsB,EAAkB;EACtF,MAAMC,IAAI,GAAGb,MAAM,CAACC,KAAK,CAAC;EAE1B,IAAII,SAAS,CAACS,IAAI,CAACD,IAAI,CAAC,EAAE;IACzB,OAAOE,uBAAe,CAACV,SAAS;EACjC;EACA,IAAIC,cAAc,CAACQ,IAAI,CAACD,IAAI,CAAC,EAAE;IAC9B;IACA;IACA;IACA,OAAOD,OAAO,CAACI,SAAS,GAAGD,uBAAe,CAACE,WAAW,GAAGF,uBAAe,CAACG,UAAU;EACpF;EACA,IAAIX,OAAO,CAACO,IAAI,CAACD,IAAI,CAAC,EAAE;IACvB,OAAOE,uBAAe,CAACG,UAAU;EAClC;EACA,IAAIV,QAAQ,CAACM,IAAI,CAACD,IAAI,CAAC,EAAE;IACxB,OAAOE,uBAAe,CAACI,eAAe;EACvC;EACA,IAAIV,MAAM,CAACK,IAAI,CAACD,IAAI,CAAC,EAAE;IACtB,OAAOE,uBAAe,CAACK,cAAc;EACtC;EACA,IAAIV,IAAI,CAACI,IAAI,CAACD,IAAI,CAAC,EAAE;IACpB;IACA,OAAOD,OAAO,CAACS,SAAS,KAAK,aAAa,GACvCN,uBAAe,CAACO,kBAAkB,GAClCP,uBAAe,CAACQ,YAAY;EAChC;EAEA,QAAQX,OAAO,CAACS,SAAS;IACxB,KAAK,MAAM;MACV,OAAON,uBAAe,CAACS,WAAW;IACnC,KAAK,MAAM;MACV,OAAOT,uBAAe,CAACK,cAAc;IACtC,KAAK,aAAa;MACjB,OAAOL,uBAAe,CAACO,kBAAkB;IAC1C,KAAK,YAAY;MAChB,OAAOP,uBAAe,CAACU,uBAAuB;IAC/C,KAAK,QAAQ;IACb,KAAK,OAAO;IACZ;MACC,OAAOV,uBAAe,CAACQ,YAAY;EACrC;AACD;;AAEA;AACA;AACA;AACA;AACO,SAASG,WAAWA,CAACzB,KAAc,EAAEW,OAAsB,EAAS;EAC1E,IAAI,IAAAe,uBAAc,EAAC1B,KAAK,CAAC,EAAE;IAC1B,MAAMA,KAAK;EACZ;EACA,IAAA2B,cAAK,EAACjB,cAAc,CAACV,KAAK,EAAEW,OAAO,CAAC,EAAE;IACrC;IACA;IACA;IACAT,OAAO,EAAE,UAAUS,OAAO,CAACS,SAAS,SAAS;IAC7CQ,MAAM,EAAE;MAAER,SAAS,EAAET,OAAO,CAACS;IAAU,CAAC;IACxCS,KAAK,EAAE7B;EACR,CAAC,CAAC;AACH","ignoreList":[]}

package/lib/commonjs/diagnostics/redact.js

@@ -0,0 +1,110 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SAFE_DETAIL_KEYS = void 0;
+exports.redactCause = redactCause;
+exports.redactDetail = redactDetail;
+exports.redactForeignText = redactForeignText;
+exports.sanitizeAuthoredMessage = sanitizeAuthoredMessage;
+exports.sanitizeIdentifier = sanitizeIdentifier;
+var _rnCore = require("@chipmobilesdk/rn-core");
+/**
+ * Redaction, applied at construction rather than at logging time.
+ *
+ * The distinction matters: an error object that never held a payload cannot
+ * leak one through a consumer's crash reporter, which is where these leaks
+ * actually happen in practice. Redacting on the way out of a logger would
+ * still leave the values sitting on the object for anything else to pick up
+ * (FR-079, FR-099).
+ */
+
+/**
+ * The allowlist IS the mechanism. Every key here has been reviewed as
+ * incapable of carrying user data: identifiers the app already knows, sizes,
+ * counts, and version numbers.
+ *
+ * A denylist was tried and removed. It rejected `recordId` because the name
+ * contains "record", which is the failure mode denylists always have — they
+ * guess from names. A closed allowlist cannot guess, and adding to it is a
+ * deliberate act with a reviewer attached.
+ */
+const SAFE_DETAIL_KEYS = exports.SAFE_DETAIL_KEYS = new Set(['code', 'collection', 'recordId', 'attachmentId', 'scopeKey', 'version', 'recordedVersion', 'failingVersion', 'outcome', 'operation', 'adapter', 'platform', 'sizeBytes', 'limitBytes', 'count', 'limit']);
+
+/**
+ * Reduce foreign text to an identifier, or to nothing.
+ *
+ * "Foreign" means text this package did not author: a SQLite message, a
+ * filesystem error, an `Error` a consumer's own migration threw. Any of them
+ * can contain anything — SQLite quotes bound parameters back, and a migration
+ * that fails on a constraint routinely names the value that violated it.
+ *
+ * An earlier version of this tried to keep the readable part: the text before
+ * the first colon, if it "looked like a class of failure". That heuristic
+ * fails on the case that matters. `Patient reported chest pain` looks exactly
+ * like a class of failure — short, no punctuation, no digits — and is a
+ * medical record. There is no shape test that separates prose describing a
+ * failure from prose describing a person, so there is no version of the
+ * heuristic worth keeping.
+ *
+ * What survives is a leading `SQLITE_*` / `ENOENT`-style identifier, which is
+ * a closed vocabulary of engine and libc constants and cannot be a value.
+ * Everything else becomes `[redacted]`. A developer who needs more can
+ * reproduce with the development logger; a crash report cannot.
+ */
+function redactForeignText(text) {
+  return (0, _rnCore.leadingIdentifier)(text);
+}
+const MAX_AUTHORED_MESSAGE = 160;
+
+/**
+ * A message this package wrote itself.
+ *
+ * Every `raise()` call site passes a string literal, and the handful that
+ * interpolate do so with a value from a closed set — an operator name, a
+ * fault point, a sanitized identifier. `authored-messages.test.ts` enforces
+ * that mechanically against the source, so this is a checked property rather
+ * than a convention someone has to remember.
+ *
+ * So no filtering happens here: filtering a message the package wrote would
+ * destroy the only readable part of the error for no gain. Foreign text never
+ * reaches this function — it goes through `redactForeignText` above.
+ */
+function sanitizeAuthoredMessage(message) {
+  return message.split('\n')[0].trim().slice(0, MAX_AUTHORED_MESSAGE);
+}
+
+/**
+ * Reduce a consumer-supplied identifier to a bounded, punctuation-free token.
+ *
+ * A field name is worth naming — FR-034 exists so a typo is distinguishable
+ * from a deliberate choice, and "which field?" is the whole answer. But the
+ * name arrives from the consumer, so it is capped and stripped rather than
+ * trusted verbatim.
+ */
+function sanitizeIdentifier(identifier) {
+  const cleaned = identifier.replace(/\W/g, '').slice(0, 64);
+  return cleaned.length > 0 ? cleaned : _rnCore.REDACTED;
+}
+
+/** Keep only keys on the allowlist, and only primitive values. */
+function redactDetail(detail) {
+  const safe = (0, _rnCore.pickAllowed)(detail, SAFE_DETAIL_KEYS);
+  return safe && Object.keys(safe).length > 0 ? safe : undefined;
+}
+
+/** Reduce an unknown thrown value to a message-shaped string, redacted. */
+function redactCause(cause) {
+  if (cause === undefined || cause === null) {
+    return undefined;
+  }
+  if (cause instanceof Error) {
+    return redactForeignText(cause.message);
+  }
+  if (typeof cause === 'string') {
+    return redactForeignText(cause);
+  }
+  return _rnCore.REDACTED;
+}
+//# sourceMappingURL=redact.js.map

package/lib/commonjs/diagnostics/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_rnCore","require","SAFE_DETAIL_KEYS","exports","Set","redactForeignText","text","leadingIdentifier","MAX_AUTHORED_MESSAGE","sanitizeAuthoredMessage","message","split","trim","slice","sanitizeIdentifier","identifier","cleaned","replace","length","REDACTED","redactDetail","detail","safe","pickAllowed","Object","keys","undefined","redactCause","cause","Error"],"sourceRoot":"../../../src","sources":["diagnostics/redact.ts"],"mappings":";;;;;;;;;;;AAUA,IAAAA,OAAA,GAAAC,OAAA;AAVA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMC,gBAAgB,GAAAC,OAAA,CAAAD,gBAAA,GAAG,IAAIE,GAAG,CAAC,CACvC,MAAM,EACN,YAAY,EACZ,UAAU,EACV,cAAc,EACd,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,SAAS,EACT,UAAU,EACV,WAAW,EACX,YAAY,EACZ,OAAO,EACP,OAAO,CACP,CAAC;;AAEF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,iBAAiBA,CAACC,IAAY,EAAU;EACvD,OAAO,IAAAC,yBAAiB,EAACD,IAAI,CAAC;AAC/B;AAEA,MAAME,oBAAoB,GAAG,GAAG;;AAEhC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,uBAAuBA,CAACC,OAAe,EAAU;EAChE,OAAOA,OAAO,CAACC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAEC,IAAI,CAAC,CAAC,CAACC,KAAK,CAAC,CAAC,EAAEL,oBAAoB,CAAC;AACrE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASM,kBAAkBA,CAACC,UAAkB,EAAU;EAC9D,MAAMC,OAAO,GAAGD,UAAU,CAACE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAACJ,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;EAC1D,OAAOG,OAAO,CAACE,MAAM,GAAG,CAAC,GAAGF,OAAO,GAAGG,gBAAQ;AAC/C;;AAEA;AACO,SAASC,YAAYA,CAC3BC,MAA2C,EACa;EACxD,MAAMC,IAAI,GAAG,IAAAC,mBAAW,EAACF,MAAM,EAAEnB,gBAAgB,CAAC;EAClD,OAAOoB,IAAI,IAAIE,MAAM,CAACC,IAAI,CAACH,IAAI,CAAC,CAACJ,MAAM,GAAG,CAAC,GAAGI,IAAI,GAAGI,SAAS;AAC/D;;AAEA;AACO,SAASC,WAAWA,CAACC,KAAc,EAAsB;EAC/D,IAAIA,KAAK,KAAKF,SAAS,IAAIE,KAAK,KAAK,IAAI,EAAE;IAC1C,OAAOF,SAAS;EACjB;EACA,IAAIE,KAAK,YAAYC,KAAK,EAAE;IAC3B,OAAOxB,iBAAiB,CAACuB,KAAK,CAAClB,OAAO,CAAC;EACxC;EACA,IAAI,OAAOkB,KAAK,KAAK,QAAQ,EAAE;IAC9B,OAAOvB,iBAAiB,CAACuB,KAAK,CAAC;EAChC;EACA,OAAOT,gBAAQ;AAChB","ignoreList":[]}

package/lib/commonjs/index.js

@@ -0,0 +1,70 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "Budgets", {
+  enumerable: true,
+  get: function () {
+    return _config.Budgets;
+  }
+});
+Object.defineProperty(exports, "DiagnosticCodes", {
+  enumerable: true,
+  get: function () {
+    return _errors.DiagnosticCodes;
+  }
+});
+Object.defineProperty(exports, "StorageError", {
+  enumerable: true,
+  get: function () {
+    return _errors.StorageError;
+  }
+});
+Object.defineProperty(exports, "deleteDatabase", {
+  enumerable: true,
+  get: function () {
+    return _index.deleteDatabase;
+  }
+});
+Object.defineProperty(exports, "deleteScopeData", {
+  enumerable: true,
+  get: function () {
+    return _index.deleteScopeData;
+  }
+});
+Object.defineProperty(exports, "isCode", {
+  enumerable: true,
+  get: function () {
+    return _errors.isCode;
+  }
+});
+Object.defineProperty(exports, "isStorageError", {
+  enumerable: true,
+  get: function () {
+    return _errors.isStorageError;
+  }
+});
+Object.defineProperty(exports, "openDatabase", {
+  enumerable: true,
+  get: function () {
+    return _index.openDatabase;
+  }
+});
+Object.defineProperty(exports, "resetScope", {
+  enumerable: true,
+  get: function () {
+    return _index.resetScope;
+  }
+});
+Object.defineProperty(exports, "setDiagnosticLogger", {
+  enumerable: true,
+  get: function () {
+    return _devLog.setDiagnosticLogger;
+  }
+});
+var _index = require("./adapter/index.js");
+var _errors = require("./diagnostics/errors.js");
+var _devLog = require("./diagnostics/dev-log.js");
+var _config = require("./contract/config.js");
+//# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_index","require","_errors","_devLog","_config"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAeA,IAAAA,MAAA,GAAAC,OAAA;AAGA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AAGA,IAAAG,OAAA,GAAAH,OAAA","ignoreList":[]}

package/lib/commonjs/migration/executor.js

@@ -0,0 +1,136 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.runMigrations = runMigrations;
+var _errors = require("../contract/errors.js");
+var _errors2 = require("../diagnostics/errors.js");
+var _faults = require("../diagnostics/faults.js");
+var _collection = require("../adapter/collection.js");
+var _ledger = require("./ledger.js");
+var _validateChain = require("./validate-chain.js");
+/**
+ * The migration executor.
+ *
+ * Four rules, each of which exists because the alternative loses data:
+ *
+ * - **Ascending, and pending only.** A migration whose version is at or below
+ *   the recorded one has already run against this scope (FR-047, FR-049).
+ * - **One transaction per migration.** A failure unwinds that migration and
+ *   nothing else, so the recorded version and the data always agree.
+ * - **The recorded version moves only on success**, inside the same
+ *   transaction as the migration's own writes. Writing it separately would
+ *   leave a window where a crash records a migration that did not happen.
+ * - **A failure returns no handle** (FR-050). Half-migrated data behind a
+ *   working handle is the failure this whole design exists to prevent, and it
+ *   is worse than being unable to open at all: the app writes to it.
+ *
+ * A retry starts from the same version rather than skipping ahead (FR-051),
+ * which is what makes a transient failure — a locked keychain, a full disk
+ * mid-migration — recoverable on the next launch instead of permanent.
+ */
+
+function migrationContextFor(context, executor) {
+  return {
+    collection(name) {
+      return (0, _collection.createSqlCollection)({
+        executor: () => executor,
+        schema: context.schemaFor(name),
+        now: context.now,
+        // Inside a migration the handle does not exist yet, so there is
+        // no closed-handle or deleted-scope state to guard against.
+        assertUsable: () => {}
+      });
+    },
+    async abort() {
+      // A migration that wants to give up should throw; aborting the
+      // transaction from inside while the executor still believes it is
+      // running would record an outcome that never happened.
+      (0, _errors2.raise)(_errors.DiagnosticCodes.TRANSACTION_STATE, {
+        message: 'a migration cannot abort its own transaction'
+      });
+    },
+    async execute(sql, params) {
+      await executor.execute(sql, params);
+    }
+  };
+}
+async function runMigrations(context) {
+  const {
+    config,
+    connection
+  } = context;
+  (0, _validateChain.validateMigrationChain)(config);
+  // Skipped when the open already found its bookkeeping tables in place.
+  if (context.ledgerReady !== true) {
+    await (0, _ledger.ensureLedger)(connection);
+  }
+  const {
+    schema: recorded,
+    format
+  } = await (0, _ledger.readVersions)(connection);
+  if (format > _ledger.FORMAT_VERSION) {
+    // A file laid out by a newer release of this package. Reading it with
+    // older code is the same hazard as a schema downgrade, one layer down.
+    await context.closeOnFailure();
+    (0, _errors2.raise)(_errors.DiagnosticCodes.SCHEMA_DOWNGRADE, {
+      message: 'database was written by a newer version of this package',
+      detail: {
+        recordedVersion: format,
+        version: _ledger.FORMAT_VERSION
+      }
+    });
+  }
+  if (recorded > config.schemaVersion) {
+    // Opening anyway would mean newer data read by older code, which drops
+    // whatever the newer schema added — silently, and on write (FR-052).
+    await context.closeOnFailure();
+    (0, _errors2.raise)(_errors.DiagnosticCodes.SCHEMA_DOWNGRADE, {
+      message: 'recorded schema version is newer than the declared one',
+      detail: {
+        recordedVersion: recorded,
+        version: config.schemaVersion
+      }
+    });
+  }
+  let current = recorded;
+  for (const migration of (0, _validateChain.pendingMigrations)(config, recorded)) {
+    try {
+      await connection.transaction(async tx => {
+        (0, _faults.throwIfFaulted)('migration');
+        await migration.migrate(migrationContextFor(context, tx));
+        await (0, _ledger.writeSchemaVersion)(tx, migration.version);
+        await (0, _ledger.recordAttempt)(tx, {
+          version: migration.version,
+          attemptedAt: context.now(),
+          outcome: 'applied'
+        });
+      });
+      current = migration.version;
+    } catch (error) {
+      // Recorded outside the rolled-back transaction, or it would vanish
+      // with the migration it describes.
+      await (0, _ledger.recordAttempt)(connection, {
+        version: migration.version,
+        attemptedAt: context.now(),
+        outcome: 'failed',
+        failureCode: error.code ?? _errors.DiagnosticCodes.MIGRATION_FAILED
+      });
+      await context.closeOnFailure();
+      (0, _errors2.raise)(_errors.DiagnosticCodes.MIGRATION_FAILED, {
+        message: 'migration failed',
+        migration: {
+          // Unchanged: the next open retries from here rather than
+          // skipping the migration that failed.
+          recordedVersion: current,
+          failingVersion: migration.version,
+          outcome: 'failed'
+        },
+        cause: error
+      });
+    }
+  }
+  return current;
+}
+//# sourceMappingURL=executor.js.map

package/lib/commonjs/migration/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_errors","require","_errors2","_faults","_collection","_ledger","_validateChain","migrationContextFor","context","executor","collection","name","createSqlCollection","schema","schemaFor","now","assertUsable","abort","raise","DiagnosticCodes","TRANSACTION_STATE","message","execute","sql","params","runMigrations","config","connection","validateMigrationChain","ledgerReady","ensureLedger","recorded","format","readVersions","FORMAT_VERSION","closeOnFailure","SCHEMA_DOWNGRADE","detail","recordedVersion","version","schemaVersion","current","migration","pendingMigrations","transaction","tx","throwIfFaulted","migrate","writeSchemaVersion","recordAttempt","attemptedAt","outcome","error","failureCode","code","MIGRATION_FAILED","failingVersion","cause"],"sourceRoot":"../../../src","sources":["migration/executor.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/migration/ledger.js

@@ -0,0 +1,64 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.FORMAT_VERSION = void 0;
+exports.ensureLedger = ensureLedger;
+exports.readVersions = readVersions;
+exports.recordAttempt = recordAttempt;
+exports.writeSchemaVersion = writeSchemaVersion;
+var _values = require("../sqlite/values.js");
+/**
+ * The per-scope migration ledger.
+ *
+ * Per scope, not per database, and that is the whole reason FR-054 works: a
+ * scope created after a migration shipped starts at version 0 and is migrated
+ * on first open, rather than being assumed current because some other scope
+ * already ran the chain.
+ *
+ * The ledger records a **code**, never a message (FR-079). A migration that
+ * failed because a domain constraint was violated could otherwise write the
+ * offending value into a table that outlives the failure — a payload leak
+ * with a long half-life, sitting in a file the next crash report might carry.
+ */
+
+/** Physical layout version, independent of the app's schema version. */
+const FORMAT_VERSION = exports.FORMAT_VERSION = 1;
+const CREATE_META = `CREATE TABLE IF NOT EXISTS _meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+)`;
+const CREATE_MIGRATIONS = `CREATE TABLE IF NOT EXISTS _migrations (
+  version      INTEGER PRIMARY KEY,
+  attempted_at INTEGER NOT NULL,
+  outcome      TEXT NOT NULL,
+  failure_code TEXT
+)`;
+async function ensureLedger(executor) {
+  await executor.execute(CREATE_META);
+  await executor.execute(CREATE_MIGRATIONS);
+  await executor.execute('INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING', ['format_version', String(FORMAT_VERSION)]);
+  await executor.execute('INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING', ['schema_version', '0']);
+}
+/** Both versions in one read: every open asks for them. */
+async function readVersions(executor) {
+  const result = await executor.execute("SELECT key, value FROM _meta WHERE key IN ('schema_version', 'format_version')");
+  const values = new Map(result.rows.map(row => [(0, _values.text)(row.key), Number((0, _values.text)(row.value))]));
+  return {
+    schema: values.get('schema_version') ?? 0,
+    format: values.get('format_version') ?? FORMAT_VERSION
+  };
+}
+async function writeSchemaVersion(executor, version) {
+  await executor.execute('INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value', ['schema_version', String(version)]);
+}
+async function recordAttempt(executor, entry) {
+  await executor.execute(`INSERT INTO _migrations (version, attempted_at, outcome, failure_code)
+		 VALUES (?, ?, ?, ?)
+		 ON CONFLICT(version) DO UPDATE SET
+		   attempted_at = excluded.attempted_at,
+		   outcome = excluded.outcome,
+		   failure_code = excluded.failure_code`, [entry.version, entry.attemptedAt, entry.outcome, entry.failureCode ?? null]);
+}
+//# sourceMappingURL=ledger.js.map

package/lib/commonjs/migration/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_values","require","FORMAT_VERSION","exports","CREATE_META","CREATE_MIGRATIONS","ensureLedger","executor","execute","String","readVersions","result","values","Map","rows","map","row","text","key","Number","value","schema","get","format","writeSchemaVersion","version","recordAttempt","entry","attemptedAt","outcome","failureCode"],"sourceRoot":"../../../src","sources":["migration/ledger.ts"],"mappings":";;;;;;;;;;AAgBA,IAAAA,OAAA,GAAAC,OAAA;AAhBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACO,MAAMC,cAAc,GAAAC,OAAA,CAAAD,cAAA,GAAG,CAAC;AAE/B,MAAME,WAAW,GAAG;AACpB;AACA;AACA,EAAE;AAEF,MAAMC,iBAAiB,GAAG;AAC1B;AACA;AACA;AACA;AACA,EAAE;AAEK,eAAeC,YAAYA,CAACC,QAAkB,EAAiB;EACrE,MAAMA,QAAQ,CAACC,OAAO,CAACJ,WAAW,CAAC;EACnC,MAAMG,QAAQ,CAACC,OAAO,CAACH,iBAAiB,CAAC;EACzC,MAAME,QAAQ,CAACC,OAAO,CACrB,0EAA0E,EAC1E,CAAC,gBAAgB,EAAEC,MAAM,CAACP,cAAc,CAAC,CAC1C,CAAC;EACD,MAAMK,QAAQ,CAACC,OAAO,CACrB,0EAA0E,EAC1E,CAAC,gBAAgB,EAAE,GAAG,CACvB,CAAC;AACF;AASA;AACO,eAAeE,YAAYA,CAACH,QAAkB,EAA6B;EACjF,MAAMI,MAAM,GAAG,MAAMJ,QAAQ,CAACC,OAAO,CACpC,gFACD,CAAC;EACD,MAAMI,MAAM,GAAG,IAAIC,GAAG,CAACF,MAAM,CAACG,IAAI,CAACC,GAAG,CAACC,GAAG,IAAI,CAAC,IAAAC,YAAI,EAACD,GAAG,CAACE,GAAG,CAAC,EAAEC,MAAM,CAAC,IAAAF,YAAI,EAACD,GAAG,CAACI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;EACxF,OAAO;IACNC,MAAM,EAAET,MAAM,CAACU,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC;IACzCC,MAAM,EAAEX,MAAM,CAACU,GAAG,CAAC,gBAAgB,CAAC,IAAIpB;EACzC,CAAC;AACF;AAEO,eAAesB,kBAAkBA,CAACjB,QAAkB,EAAEkB,OAAe,EAAiB;EAC5F,MAAMlB,QAAQ,CAACC,OAAO,CACrB,oGAAoG,EACpG,CAAC,gBAAgB,EAAEC,MAAM,CAACgB,OAAO,CAAC,CACnC,CAAC;AACF;AAEO,eAAeC,aAAaA,CAClCnB,QAAkB,EAClBoB,KAAgG,EAChF;EAChB,MAAMpB,QAAQ,CAACC,OAAO,CACrB;AACF;AACA;AACA;AACA;AACA,0CAA0C,EACxC,CAACmB,KAAK,CAACF,OAAO,EAAEE,KAAK,CAACC,WAAW,EAAED,KAAK,CAACE,OAAO,EAAEF,KAAK,CAACG,WAAW,IAAI,IAAI,CAC5E,CAAC;AACF","ignoreList":[]}

package/lib/commonjs/migration/validate-chain.js

@@ -0,0 +1,76 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.orderedMigrations = orderedMigrations;
+exports.pendingMigrations = pendingMigrations;
+exports.validateMigrationChain = validateMigrationChain;
+var _errors = require("../contract/errors.js");
+var _errors2 = require("../diagnostics/errors.js");
+/**
+ * Migration chain validation, run before any migration executes (FR-053).
+ *
+ * Validating first is what stops a half-run chain from being the thing that
+ * discovers the problem. A duplicate version, a gap, or a chain that does not
+ * reach the declared `schemaVersion` are all configuration errors the
+ * developer can fix; discovering them after migration 3 of 5 has already
+ * rewritten a user's data is not.
+ *
+ * A gap is refused rather than skipped over deliberately. A user upgrading
+ * from the version inside the gap has no path across it, and opening anyway
+ * would hand them a database the code believes is current and is not.
+ */
+
+function invalid(message, detail) {
+  (0, _errors2.raise)(_errors.DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+    message,
+    detail
+  });
+}
+function validateMigrationChain(config) {
+  const migrations = config.migrations ?? [];
+  if (!Number.isInteger(config.schemaVersion) || config.schemaVersion < 1) {
+    invalid('schemaVersion must be a positive integer');
+  }
+  const versions = new Set();
+  for (const migration of migrations) {
+    if (!Number.isInteger(migration.version) || migration.version < 1) {
+      invalid('migration version must be a positive integer');
+    }
+    if (versions.has(migration.version)) {
+      invalid('duplicate migration version', {
+        version: migration.version
+      });
+    }
+    versions.add(migration.version);
+    if (typeof migration.migrate !== 'function') {
+      invalid('migration has no migrate function', {
+        version: migration.version
+      });
+    }
+  }
+  for (let version = 1; version <= config.schemaVersion; version += 1) {
+    if (!versions.has(version)) {
+      invalid('migration chain has a gap', {
+        version
+      });
+    }
+  }
+  for (const version of versions) {
+    if (version > config.schemaVersion) {
+      invalid('migration version exceeds the declared schemaVersion', {
+        version
+      });
+    }
+  }
+}
+
+/** Ascending, because the order a consumer declared them in is not a contract. */
+function orderedMigrations(config) {
+  return [...(config.migrations ?? [])].sort((a, b) => a.version - b.version);
+}
+function pendingMigrations(config, recordedVersion) {
+  return orderedMigrations(config).filter(migration => migration.version > recordedVersion);
+}
+//# sourceMappingURL=validate-chain.js.map

package/lib/commonjs/migration/validate-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_errors","require","_errors2","invalid","message","detail","raise","DiagnosticCodes","MIGRATION_CONFIG_INVALID","validateMigrationChain","config","migrations","Number","isInteger","schemaVersion","versions","Set","migration","version","has","add","migrate","orderedMigrations","sort","a","b","pendingMigrations","recordedVersion","filter"],"sourceRoot":"../../../src","sources":["migration/validate-chain.ts"],"mappings":";;;;;;;;AAeA,IAAAA,OAAA,GAAAC,OAAA;AAEA,IAAAC,QAAA,GAAAD,OAAA;AAjBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAOA,SAASE,OAAOA,CAACC,OAAe,EAAEC,MAAgC,EAAS;EAC1E,IAAAC,cAAK,EAACC,uBAAe,CAACC,wBAAwB,EAAE;IAAEJ,OAAO;IAAEC;EAAO,CAAC,CAAC;AACrE;AAEO,SAASI,sBAAsBA,CAACC,MAAsB,EAAQ;EACpE,MAAMC,UAAU,GAAGD,MAAM,CAACC,UAAU,IAAI,EAAE;EAE1C,IAAI,CAACC,MAAM,CAACC,SAAS,CAACH,MAAM,CAACI,aAAa,CAAC,IAAIJ,MAAM,CAACI,aAAa,GAAG,CAAC,EAAE;IACxEX,OAAO,CAAC,0CAA0C,CAAC;EACpD;EAEA,MAAMY,QAAQ,GAAG,IAAIC,GAAG,CAAS,CAAC;EAClC,KAAK,MAAMC,SAAS,IAAIN,UAAU,EAAE;IACnC,IAAI,CAACC,MAAM,CAACC,SAAS,CAACI,SAAS,CAACC,OAAO,CAAC,IAAID,SAAS,CAACC,OAAO,GAAG,CAAC,EAAE;MAClEf,OAAO,CAAC,8CAA8C,CAAC;IACxD;IACA,IAAIY,QAAQ,CAACI,GAAG,CAACF,SAAS,CAACC,OAAO,CAAC,EAAE;MACpCf,OAAO,CAAC,6BAA6B,EAAE;QAAEe,OAAO,EAAED,SAAS,CAACC;MAAQ,CAAC,CAAC;IACvE;IACAH,QAAQ,CAACK,GAAG,CAACH,SAAS,CAACC,OAAO,CAAC;IAC/B,IAAI,OAAOD,SAAS,CAACI,OAAO,KAAK,UAAU,EAAE;MAC5ClB,OAAO,CAAC,mCAAmC,EAAE;QAAEe,OAAO,EAAED,SAAS,CAACC;MAAQ,CAAC,CAAC;IAC7E;EACD;EAEA,KAAK,IAAIA,OAAO,GAAG,CAAC,EAAEA,OAAO,IAAIR,MAAM,CAACI,aAAa,EAAEI,OAAO,IAAI,CAAC,EAAE;IACpE,IAAI,CAACH,QAAQ,CAACI,GAAG,CAACD,OAAO,CAAC,EAAE;MAC3Bf,OAAO,CAAC,2BAA2B,EAAE;QAAEe;MAAQ,CAAC,CAAC;IAClD;EACD;EAEA,KAAK,MAAMA,OAAO,IAAIH,QAAQ,EAAE;IAC/B,IAAIG,OAAO,GAAGR,MAAM,CAACI,aAAa,EAAE;MACnCX,OAAO,CAAC,sDAAsD,EAAE;QAAEe;MAAQ,CAAC,CAAC;IAC7E;EACD;AACD;;AAEA;AACO,SAASI,iBAAiBA,CAACZ,MAAsB,EAAe;EACtE,OAAO,CAAC,IAAIA,MAAM,CAACC,UAAU,IAAI,EAAE,CAAC,CAAC,CAACY,IAAI,CAAC,CAACC,CAAC,EAAEC,CAAC,KAAKD,CAAC,CAACN,OAAO,GAAGO,CAAC,CAACP,OAAO,CAAC;AAC5E;AAEO,SAASQ,iBAAiBA,CAAChB,MAAsB,EAAEiB,eAAuB,EAAe;EAC/F,OAAOL,iBAAiB,CAACZ,MAAM,CAAC,CAACkB,MAAM,CAACX,SAAS,IAAIA,SAAS,CAACC,OAAO,GAAGS,eAAe,CAAC;AAC1F","ignoreList":[]}

package/lib/commonjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}