@chipmobilesdk/rn-local-db 0.4.0 → 0.5.0

package/lib/commonjs/adapter/lifecycle.js

@@ -0,0 +1,176 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.openSqliteDatabase = openSqliteDatabase;
+var _errors = require("../contract/errors.js");
+var _keyProvider = require("../crypto/key-provider.js");
+var _provider = require("../crypto/provider.js");
+var _errors2 = require("../diagnostics/errors.js");
+var _faults = require("../diagnostics/faults.js");
+var _executor = require("../migration/executor.js");
+var _backupAndroidVerify = require("../platform/backup-android-verify.js");
+var _backupIos = require("../platform/backup-ios.js");
+var _location = require("../platform/location.js");
+var _declare = require("../schema/declare.js");
+var _validateConfig = require("../schema/validate-config.js");
+var _validate = require("../scope/validate.js");
+var _catalog = require("../sqlite/catalog.js");
+var _connection = require("../sqlite/connection.js");
+var _native = require("../sqlite/native.js");
+var _budgets = require("./budgets.js");
+var _deletion = require("./deletion.js");
+var _handle = require("./handle.js");
+var _schemaSync = require("./schema-sync.js");
+/**
+ * Opening and closing a database.
+ *
+ * The order of operations here is the design, not an implementation detail:
+ *
+ * 1. **Validate everything first.** Configuration, scope, and the migration
+ *    chain are checked before a file is touched, so a developer error is
+ *    reported against an untouched database (FR-006, FR-053).
+ * 2. **Consult the catalog before opening the scope file.** A posture
+ *    mismatch is detectable there; discovering it from SQLCipher's "file is
+ *    not a database" would report corruption for what is actually an app
+ *    configuration change (FR-101).
+ * 3. **Migrate before returning.** Nothing observes a half-migrated schema,
+ *    because there is no handle to observe it with until the chain completes
+ *    (FR-055). A failure returns no handle at all (FR-050).
+ *
+ * The handle itself is built in `handle.ts`.
+ */
+
+function resolveEncryption(config) {
+  if (config.encryption?.enabled !== true) {
+    return false;
+  }
+  // Writing plaintext to a file the app believes is encrypted is the one
+  // outcome worse than refusing to open (research.md R1a).
+  if (!(0, _native.isEncryptionAvailable)()) {
+    (0, _errors2.raise)(_errors.DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+      message: 'encryption was requested but SQLCipher is not compiled into this build'
+    });
+  }
+  if (!(0, _provider.isCipherAvailable)()) {
+    (0, _errors2.raise)(_errors.DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+      message: 'encryption was requested but the cipher peer is not installed'
+    });
+  }
+  return true;
+}
+async function assertPostureMatches(catalog, scope, encrypted) {
+  const entry = await (0, _catalog.readEntry)(catalog, scope.key);
+  if (!entry) {
+    return;
+  }
+  if (entry.deletionState === 'deleting') {
+    // An interrupted deletion is reported rather than opened over: the
+    // scope is neither present nor gone, and presenting it as healthy is
+    // the one answer FR-063 forbids. `deleteScopeData` finishes the job.
+    (0, _errors2.raise)(_errors.DiagnosticCodes.SCOPE_DELETED, {
+      message: 'a previous deletion of this scope was interrupted',
+      detail: {
+        scopeKey: scope.key
+      }
+    });
+  }
+  if (entry.encrypted !== encrypted) {
+    // In-place conversion is not supported this phase (FR-103). Reporting
+    // the mismatch lets an app migrate deliberately; opening would either
+    // fail obscurely or write the wrong posture.
+    (0, _errors2.raise)(_errors.DiagnosticCodes.ENCRYPTION_MISMATCH, {
+      message: 'encryption posture does not match the stored database',
+      detail: {
+        scopeKey: scope.key
+      }
+    });
+  }
+}
+async function openSqliteDatabase(config, options = {}) {
+  const now = options.now ?? (() => Date.now());
+  (0, _validateConfig.validateConfig)(config);
+  (0, _faults.throwIfFaulted)('open');
+  const scope = (0, _validate.resolveScope)(config.scope);
+  const encrypted = resolveEncryption(config);
+  const includeInBackup = config.backup?.includeInPlatformBackup === true;
+  const layout = (0, _location.layoutFor)(config.name);
+  await (0, _backupIos.ensureManagedRoot)(layout, includeInBackup);
+  const catalog = await (0, _connection.openConnection)({
+    path: layout.catalogPath
+  });
+  let key = null;
+  let connection = null;
+  let released = false;
+  const releaseConnection = async () => {
+    if (released || !connection) {
+      return;
+    }
+    released = true;
+    await connection.close();
+    (0, _budgets.releaseHandleSlot)();
+  };
+  try {
+    await (0, _catalog.ensureCatalog)(catalog);
+    await assertPostureMatches(catalog, scope, encrypted);
+    if (encrypted) {
+      key = await (0, _keyProvider.acquireKey)(config.encryption, scope);
+    }
+    (0, _budgets.acquireHandleSlot)();
+    try {
+      connection = await (0, _connection.openConnection)({
+        path: layout.scopeDataPath(scope.key),
+        ...(key ? {
+          encryptionKey: key.value()
+        } : {})
+      });
+    } catch (error) {
+      (0, _budgets.releaseHandleSlot)();
+      throw error;
+    }
+    await (0, _connection.assertReadable)(connection);
+    const schemas = (0, _declare.indexSchemas)(config.collections);
+    // No DDL at all when the declaration is the one already applied (LDB-07).
+    const schema = await (0, _schemaSync.syncSchema)(connection, config);
+    const scopeConnection = connection;
+    const schemaVersion = await (0, _executor.runMigrations)({
+      connection: scopeConnection,
+      config,
+      schemaFor: name => (0, _handle.schemaFor)(schemas, name),
+      now,
+      closeOnFailure: releaseConnection,
+      ledgerReady: schema.unchanged
+    });
+    await schema.record();
+    await (0, _catalog.registerScope)(catalog, {
+      scopeKey: scope.key,
+      createdAt: now(),
+      deletionState: 'active',
+      backupPosture: includeInBackup ? 'included' : 'excluded',
+      encrypted
+    });
+    await catalog.close();
+    (0, _deletion.clearScopeInvalidation)(config.name, scope.key);
+    return (0, _handle.buildHandle)({
+      config,
+      connection: scopeConnection,
+      key,
+      layout,
+      now,
+      schemaVersion,
+      schemas,
+      scope,
+      posture: (0, _backupAndroidVerify.effectivePostureFor)(layout, includeInBackup, _backupIos.iosPosture)
+    });
+  } catch (error) {
+    // No usable handle after a failed open (FR-002). Anything already
+    // acquired is released here rather than left for a caller who is about
+    // to be handed an exception instead of a handle.
+    key?.release();
+    await releaseConnection();
+    await catalog.close();
+    throw error;
+  }
+}
+//# sourceMappingURL=lifecycle.js.map

package/lib/commonjs/adapter/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_errors","require","_keyProvider","_provider","_errors2","_faults","_executor","_backupAndroidVerify","_backupIos","_location","_declare","_validateConfig","_validate","_catalog","_connection","_native","_budgets","_deletion","_handle","_schemaSync","resolveEncryption","config","encryption","enabled","isEncryptionAvailable","raise","DiagnosticCodes","ENCRYPTION_UNAVAILABLE","message","isCipherAvailable","assertPostureMatches","catalog","scope","encrypted","entry","readEntry","key","deletionState","SCOPE_DELETED","detail","scopeKey","ENCRYPTION_MISMATCH","openSqliteDatabase","options","now","Date","validateConfig","throwIfFaulted","resolveScope","includeInBackup","backup","includeInPlatformBackup","layout","layoutFor","name","ensureManagedRoot","openConnection","path","catalogPath","connection","released","releaseConnection","close","releaseHandleSlot","ensureCatalog","acquireKey","acquireHandleSlot","scopeDataPath","encryptionKey","value","error","assertReadable","schemas","indexSchemas","collections","schema","syncSchema","scopeConnection","schemaVersion","runMigrations","schemaFor","closeOnFailure","ledgerReady","unchanged","record","registerScope","createdAt","backupPosture","clearScopeInvalidation","buildHandle","posture","effectivePostureFor","iosPosture","release"],"sourceRoot":"../../../src","sources":["adapter/lifecycle.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/adapter/schema-sync.js

@@ -0,0 +1,124 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.syncSchema = syncSchema;
+var _store = require("../artifacts/store.js");
+var _rowCodec = require("../sqlite/row-codec.js");
+var _values = require("../sqlite/values.js");
+/**
+ * Bringing the physical tables in line with the declared schema, and skipping
+ * that work when nothing changed (LDB-07, LDB-11).
+ *
+ * Until 0.4.0 every open ran the whole set — CREATE TABLE, PRAGMA table_info,
+ * CREATE INDEX per index, for every collection — some sixty native round-trips
+ * for ten collections, on the startup path. The applied schema is now recorded
+ * in `_meta`; an open whose declaration matches it runs no DDL at all.
+ */
+
+/** Bumped whenever the DDL this package generates changes, so it is re-applied once. */
+const DDL_VERSION = 1;
+const FINGERPRINT_KEY = 'schema_fingerprint';
+
+/** What was declared, and by which generation of this package's DDL. */
+function fingerprintOf(config) {
+  return JSON.stringify([DDL_VERSION, config.collections]);
+}
+async function appliedFingerprint(connection) {
+  try {
+    const result = await connection.execute('SELECT value FROM _meta WHERE key = ?', [FINGERPRINT_KEY]);
+    const row = result.rows[0];
+    return row ? (0, _values.text)(row.value) : null;
+  } catch {
+    // A database that has never been opened has no `_meta` yet.
+    return null;
+  }
+}
+
+/** `unique` and the column list of an index, read back from the statement SQLite stored. */
+function definitionOf(sql) {
+  const unique = /^\s*CREATE\s+UNIQUE\s/i.test(sql);
+  const columns = sql.slice(sql.lastIndexOf('(') + 1, sql.lastIndexOf(')')).replace(/["\s]/g, '');
+  return `${unique ? 'unique' : 'plain'}:${columns}`;
+}
+
+/**
+ * Indexes follow their declaration (LDB-11). `CREATE INDEX IF NOT EXISTS` keyed
+ * on the name alone meant that adding `unique: true` to an existing index, or
+ * changing its fields, did nothing, and an index no longer declared stayed
+ * forever. An index whose definition changed is dropped and recreated, and one
+ * of this package's that is no longer declared is dropped. Only indexes carrying
+ * the collection's own prefix are touched.
+ */
+async function syncIndexes(connection, schema) {
+  const table = `c_${schema.name}`;
+  const existing = await connection.execute("SELECT name, sql FROM sqlite_master WHERE type = 'index' AND tbl_name = ? AND sql IS NOT NULL", [table]);
+  const current = new Map(existing.rows.map(row => [(0, _values.text)(row.name), (0, _values.text)(row.sql)]));
+  const wanted = new Map((0, _rowCodec.createIndexSql)(schema).map(statement => {
+    const name = /INDEX IF NOT EXISTS "([^"]+)"/.exec(statement)?.[1] ?? '';
+    return [name, statement];
+  }));
+  for (const index of schema.indexes ?? []) {
+    // Indexes created before 0.2.0 carry the bare declared name; they are
+    // recreated under the collection-scoped one. No row data moves.
+    if (current.has(index.name) && index.name !== (0, _rowCodec.physicalIndexName)(schema, index.name)) {
+      await connection.execute(`DROP INDEX IF EXISTS "${index.name}"`);
+    }
+  }
+  for (const [name, sql] of current) {
+    const statement = wanted.get(name);
+    const ours = name.startsWith(`${table}__`);
+    if (statement === undefined && ours || statement && definitionOf(statement) !== definitionOf(sql)) {
+      await connection.execute(`DROP INDEX IF EXISTS "${name}"`);
+    }
+  }
+  for (const statement of wanted.values()) {
+    await connection.execute(statement);
+  }
+}
+
+/**
+ * Adding a column rather than recreating the table is what makes declaring a
+ * new queryable field non-destructive: the payload already holds the value, so
+ * the new column is backfilled from it and no record is rewritten by hand
+ * (research.md R6).
+ */
+async function ensureCollection(connection, schema) {
+  await connection.execute((0, _rowCodec.createTableSql)(schema));
+  const info = await connection.execute(`PRAGMA table_info("c_${schema.name}")`);
+  const present = new Set(info.rows.map(row => (0, _values.text)(row.name)));
+  for (const field of schema.fields ?? []) {
+    const column = `f_${field.name}`;
+    if (present.has(column)) {
+      continue;
+    }
+    await connection.execute((0, _rowCodec.addColumnSql)(schema, field));
+    // The same projection a write applies (`projectValue`): an object or an
+    // array projects to NULL. A bare json_extract backfilled those as JSON
+    // text, so a filter matched old records and new ones differently (LDB-11).
+    const path = `'$."${field.name}"'`;
+    await connection.execute(`UPDATE "c_${schema.name}" SET "${column}" = CASE WHEN json_type(payload, ${path}) IN ('object', 'array') THEN NULL ELSE json_extract(payload, ${path}) END`);
+  }
+  await syncIndexes(connection, schema);
+}
+async function syncSchema(connection, config) {
+  const fingerprint = fingerprintOf(config);
+  if ((await appliedFingerprint(connection)) === fingerprint) {
+    return {
+      unchanged: true,
+      record: async () => undefined
+    };
+  }
+  for (const schema of config.collections) {
+    await ensureCollection(connection, schema);
+  }
+  await (0, _store.ensureAttachmentTable)(connection);
+  return {
+    unchanged: false,
+    async record() {
+      await connection.execute('INSERT INTO _meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value', [FINGERPRINT_KEY, fingerprint]);
+    }
+  };
+}
+//# sourceMappingURL=schema-sync.js.map

package/lib/commonjs/adapter/schema-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_store","require","_rowCodec","_values","DDL_VERSION","FINGERPRINT_KEY","fingerprintOf","config","JSON","stringify","collections","appliedFingerprint","connection","result","execute","row","rows","text","value","definitionOf","sql","unique","test","columns","slice","lastIndexOf","replace","syncIndexes","schema","table","name","existing","current","Map","map","wanted","createIndexSql","statement","exec","index","indexes","has","physicalIndexName","get","ours","startsWith","undefined","values","ensureCollection","createTableSql","info","present","Set","field","fields","column","addColumnSql","path","syncSchema","fingerprint","unchanged","record","ensureAttachmentTable"],"sourceRoot":"../../../src","sources":["adapter/schema-sync.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/adapter/transaction.js

@@ -0,0 +1,58 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createTransaction = createTransaction;
+var _errors = require("../contract/errors.js");
+var _errors2 = require("../diagnostics/errors.js");
+/**
+ * The `Transaction` a consumer actually holds.
+ *
+ * Two rules live here rather than in either adapter, so both are held to the
+ * same standard:
+ *
+ * **Read-your-own-writes** (FR-043). Every collection reached through `tx`
+ * runs against the transaction's executor, so a read inside sees the writes
+ * made inside. A collection reached through the handle during a transaction
+ * would not, and handing one out would be a quiet correctness trap.
+ *
+ * **Terminal state is terminal** (FR-044). After a commit or an abort, using
+ * the transaction raises rather than silently writing outside it — the
+ * failure mode where a caller's cleanup code lands in the database after the
+ * rollback it was supposed to be part of.
+ */
+
+function createTransaction(host) {
+  let settled = false;
+  const assertLive = () => {
+    if (settled) {
+      (0, _errors2.raise)(_errors.DiagnosticCodes.TRANSACTION_STATE, {
+        message: 'transaction already settled'
+      });
+    }
+  };
+  const transaction = {
+    collection(name) {
+      assertLive();
+      return host.collection(name);
+    },
+    attachments() {
+      assertLive();
+      return host.attachments();
+    },
+    async abort() {
+      assertLive();
+      settled = true;
+      await host.rollback();
+    }
+  };
+  return {
+    transaction,
+    isSettled: () => settled,
+    settle: () => {
+      settled = true;
+    }
+  };
+}
+//# sourceMappingURL=transaction.js.map

package/lib/commonjs/adapter/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_errors","require","_errors2","createTransaction","host","settled","assertLive","raise","DiagnosticCodes","TRANSACTION_STATE","message","transaction","collection","name","attachments","abort","rollback","isSettled","settle"],"sourceRoot":"../../../src","sources":["adapter/transaction.ts"],"mappings":";;;;;;AAiBA,IAAAA,OAAA,GAAAC,OAAA;AAIA,IAAAC,QAAA,GAAAD,OAAA;AArBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAqBO,SAASE,iBAAiBA,CAACC,IAAqB,EAAsB;EAC5E,IAAIC,OAAO,GAAG,KAAK;EAEnB,MAAMC,UAAU,GAAGA,CAAA,KAAY;IAC9B,IAAID,OAAO,EAAE;MACZ,IAAAE,cAAK,EAACC,uBAAe,CAACC,iBAAiB,EAAE;QACxCC,OAAO,EAAE;MACV,CAAC,CAAC;IACH;EACD,CAAC;EAED,MAAMC,WAAwB,GAAG;IAChCC,UAAUA,CAA+BC,IAAY,EAAoB;MACxEP,UAAU,CAAC,CAAC;MACZ,OAAOF,IAAI,CAACQ,UAAU,CAAIC,IAAI,CAAC;IAChC,CAAC;IACDC,WAAWA,CAAA,EAAgB;MAC1BR,UAAU,CAAC,CAAC;MACZ,OAAOF,IAAI,CAACU,WAAW,CAAC,CAAC;IAC1B,CAAC;IACD,MAAMC,KAAKA,CAAA,EAAkB;MAC5BT,UAAU,CAAC,CAAC;MACZD,OAAO,GAAG,IAAI;MACd,MAAMD,IAAI,CAACY,QAAQ,CAAC,CAAC;IACtB;EACD,CAAC;EAED,OAAO;IACNL,WAAW;IACXM,SAAS,EAAEA,CAAA,KAAMZ,OAAO;IACxBa,MAAM,EAAEA,CAAA,KAAM;MACbb,OAAO,GAAG,IAAI;IACf;EACD,CAAC;AACF","ignoreList":[]}

package/lib/commonjs/artifacts/availability.js

@@ -0,0 +1,90 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.artifactAvailability = artifactAvailability;
+var _fs = require("../platform/fs.js");
+var _bytes = require("../platform/bytes.js");
+var _chunkedCipher = require("../crypto/chunked-cipher.js");
+var _paths = require("./paths.js");
+var _store = require("./store.js");
+/**
+ * "Is this artifact still there?", answered without opening it.
+ *
+ * `stat()` and, for an encrypted artifact, the 22-byte header. Never a
+ * content byte and never a decryption (FR-073e, FR-107b). An availability
+ * check that decrypted would make a gallery screen showing fifty thumbnails
+ * decrypt fifty artifacts to answer a question none of them asked, and would
+ * put key material in play for an operation that does not need it.
+ *
+ * The four states are deliberately four rather than two. `missing` is data
+ * that is gone; `undecryptable` is data that exists under a key that does not
+ * open it, which is often recoverable and always a different conversation to
+ * have with the user (FR-107c).
+ */
+
+async function artifactAvailability(context, executor, id) {
+  const reference = await (0, _store.readReference)(executor, id);
+  if (!reference) {
+    // No reference is "missing" rather than an error: the caller asked
+    // about an artifact this scope does not claim to have.
+    return {
+      id,
+      state: 'missing'
+    };
+  }
+  const path = (0, _paths.artifactPath)(context.layout, context.scopeKey, id);
+  let size;
+  try {
+    const stat = await (0, _fs.fileSystem)().stat(path);
+    if (!stat.isFile()) {
+      return {
+        id,
+        state: 'inaccessible'
+      };
+    }
+    size = stat.size;
+  } catch {
+    return {
+      id,
+      state: 'missing'
+    };
+  }
+  if (context.artifactKey(id) === null) {
+    return {
+      id,
+      state: 'available',
+      size: reference.size
+    };
+  }
+  if (size < _chunkedCipher.HEADER_BYTES) {
+    return {
+      id,
+      state: 'undecryptable',
+      size: reference.size
+    };
+  }
+  try {
+    const header = (0, _bytes.base64ToBytes)(await (0, _fs.fileSystem)().read(path, _chunkedCipher.HEADER_BYTES, 0, 'base64'));
+    if ((0, _bytes.asciiAt)(header, 0, 4) !== _chunkedCipher.MAGIC) {
+      return {
+        id,
+        state: 'undecryptable',
+        size: reference.size
+      };
+    }
+  } catch {
+    return {
+      id,
+      state: 'inaccessible',
+      size: reference.size
+    };
+  }
+  return {
+    id,
+    state: 'available',
+    size: reference.size
+  };
+}
+//# sourceMappingURL=availability.js.map

package/lib/commonjs/artifacts/availability.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_fs","require","_bytes","_chunkedCipher","_paths","_store","artifactAvailability","context","executor","id","reference","readReference","state","path","artifactPath","layout","scopeKey","size","stat","fileSystem","isFile","artifactKey","HEADER_BYTES","header","base64ToBytes","read","asciiAt","MAGIC"],"sourceRoot":"../../../src","sources":["artifacts/availability.ts"],"mappings":";;;;;;AAgBA,IAAAA,GAAA,GAAAC,OAAA;AACA,IAAAC,MAAA,GAAAD,OAAA;AACA,IAAAE,cAAA,GAAAF,OAAA;AAEA,IAAAG,MAAA,GAAAH,OAAA;AACA,IAAAI,MAAA,GAAAJ,OAAA;AArBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUO,eAAeK,oBAAoBA,CACzCC,OAAwB,EACxBC,QAAkB,EAClBC,EAAU,EACwB;EAClC,MAAMC,SAAS,GAAG,MAAM,IAAAC,oBAAa,EAACH,QAAQ,EAAEC,EAAE,CAAC;EACnD,IAAI,CAACC,SAAS,EAAE;IACf;IACA;IACA,OAAO;MAAED,EAAE;MAAEG,KAAK,EAAE;IAAU,CAAC;EAChC;EAEA,MAAMC,IAAI,GAAG,IAAAC,mBAAY,EAACP,OAAO,CAACQ,MAAM,EAAER,OAAO,CAACS,QAAQ,EAAEP,EAAE,CAAC;EAE/D,IAAIQ,IAAY;EAChB,IAAI;IACH,MAAMC,IAAI,GAAG,MAAM,IAAAC,cAAU,EAAC,CAAC,CAACD,IAAI,CAACL,IAAI,CAAC;IAC1C,IAAI,CAACK,IAAI,CAACE,MAAM,CAAC,CAAC,EAAE;MACnB,OAAO;QAAEX,EAAE;QAAEG,KAAK,EAAE;MAAe,CAAC;IACrC;IACAK,IAAI,GAAGC,IAAI,CAACD,IAAI;EACjB,CAAC,CAAC,MAAM;IACP,OAAO;MAAER,EAAE;MAAEG,KAAK,EAAE;IAAU,CAAC;EAChC;EAEA,IAAIL,OAAO,CAACc,WAAW,CAACZ,EAAE,CAAC,KAAK,IAAI,EAAE;IACrC,OAAO;MAAEA,EAAE;MAAEG,KAAK,EAAE,WAAW;MAAEK,IAAI,EAAEP,SAAS,CAACO;IAAK,CAAC;EACxD;EAEA,IAAIA,IAAI,GAAGK,2BAAY,EAAE;IACxB,OAAO;MAAEb,EAAE;MAAEG,KAAK,EAAE,eAAe;MAAEK,IAAI,EAAEP,SAAS,CAACO;IAAK,CAAC;EAC5D;EAEA,IAAI;IACH,MAAMM,MAAM,GAAG,IAAAC,oBAAa,EAAC,MAAM,IAAAL,cAAU,EAAC,CAAC,CAACM,IAAI,CAACZ,IAAI,EAAES,2BAAY,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IACtF,IAAI,IAAAI,cAAO,EAACH,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,KAAKI,oBAAK,EAAE;MACpC,OAAO;QAAElB,EAAE;QAAEG,KAAK,EAAE,eAAe;QAAEK,IAAI,EAAEP,SAAS,CAACO;MAAK,CAAC;IAC5D;EACD,CAAC,CAAC,MAAM;IACP,OAAO;MAAER,EAAE;MAAEG,KAAK,EAAE,cAAc;MAAEK,IAAI,EAAEP,SAAS,CAACO;IAAK,CAAC;EAC3D;EAEA,OAAO;IAAER,EAAE;IAAEG,KAAK,EAAE,WAAW;IAAEK,IAAI,EAAEP,SAAS,CAACO;EAAK,CAAC;AACxD","ignoreList":[]}

package/lib/commonjs/artifacts/cascade.js

@@ -0,0 +1,80 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.cascadeForOwner = cascadeForOwner;
+exports.unlinkArtifact = unlinkArtifact;
+var _fs = require("../platform/fs.js");
+var _paths = require("./paths.js");
+var _store = require("./store.js");
+/**
+ * Cascading artifact removal.
+ *
+ * The package deletes the files, because the Q2 clarification made it the
+ * owner of them (FR-073c). That is the single riskiest thing this package
+ * does — POL-011(b)'s media-and-files row exists for it — so two rules hold
+ * without exception: every path goes through the boundary guard in
+ * `paths.ts`, and the outcome reports what was removed **and what could not
+ * be**, never a bare success (FR-071).
+ *
+ * A failed removal is reported rather than retried or swallowed. A file the
+ * package could not delete is still on disk holding the user's data, and an
+ * app that told them "deleted" would have said something untrue.
+ */
+
+/** Unlinks one artifact file. True when the file is gone afterwards, whoever removed it. */
+async function unlinkArtifact(path) {
+  if (await (0, _fs.removeIfPresent)(path)) {
+    return true;
+  }
+  // `removeIfPresent` cannot tell "already gone" from "could not remove". A
+  // file that was already gone counts as removed: the end state the caller
+  // asked for is the end state they got.
+  try {
+    return !(await (0, _fs.fileSystem)().exists(path));
+  } catch {
+    return false;
+  }
+}
+async function removeAll(context, executor, ids, deferred) {
+  const removedArtifacts = [];
+  const failedRemovals = [];
+  for (const id of ids) {
+    // The reference first. A reference left pointing at a deleted file is
+    // the unrecoverable state; a file left without its reference is an
+    // orphan reconciliation finds.
+    if (!(await (0, _store.deleteReference)(executor, id))) {
+      failedRemovals.push(id);
+      continue;
+    }
+    const path = (0, _paths.artifactPath)(context.layout, context.scopeKey, id);
+    if (deferred) {
+      deferred.add(path);
+      removedArtifacts.push(id);
+      continue;
+    }
+    if (await unlinkArtifact(path)) {
+      removedArtifacts.push(id);
+    } else {
+      // Still on disk holding the user's data: reported, never claimed removed.
+      failedRemovals.push(id);
+    }
+  }
+  return {
+    removedRecords: 0,
+    removedArtifacts,
+    orphanedReferences: [],
+    failedRemovals
+  };
+}
+
+/**
+ * Everything belonging to one record, for the FR-070 cascade. Inside a
+ * transaction pass `deferred`: the files are removed only once it commits.
+ */
+async function cascadeForOwner(context, executor, owner, deferred) {
+  const references = await (0, _store.listReferencesFor)(executor, owner);
+  return removeAll(context, executor, references.map(reference => reference.id), deferred);
+}
+//# sourceMappingURL=cascade.js.map

package/lib/commonjs/artifacts/cascade.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_fs","require","_paths","_store","unlinkArtifact","path","removeIfPresent","fileSystem","exists","removeAll","context","executor","ids","deferred","removedArtifacts","failedRemovals","id","deleteReference","push","artifactPath","layout","scopeKey","add","removedRecords","orphanedReferences","cascadeForOwner","owner","references","listReferencesFor","map","reference"],"sourceRoot":"../../../src","sources":["artifacts/cascade.ts"],"mappings":";;;;;;;AAgBA,IAAAA,GAAA,GAAAC,OAAA;AAEA,IAAAC,MAAA,GAAAD,OAAA;AACA,IAAAE,MAAA,GAAAF,OAAA;AAnBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAeA;AACO,eAAeG,cAAcA,CAACC,IAAY,EAAoB;EACpE,IAAI,MAAM,IAAAC,mBAAe,EAACD,IAAI,CAAC,EAAE;IAChC,OAAO,IAAI;EACZ;EACA;EACA;EACA;EACA,IAAI;IACH,OAAO,EAAE,MAAM,IAAAE,cAAU,EAAC,CAAC,CAACC,MAAM,CAACH,IAAI,CAAC,CAAC;EAC1C,CAAC,CAAC,MAAM;IACP,OAAO,KAAK;EACb;AACD;AAEA,eAAeI,SAASA,CACvBC,OAAwB,EACxBC,QAAkB,EAClBC,GAAa,EACbC,QAA0B,EACC;EAC3B,MAAMC,gBAA0B,GAAG,EAAE;EACrC,MAAMC,cAAwB,GAAG,EAAE;EAEnC,KAAK,MAAMC,EAAE,IAAIJ,GAAG,EAAE;IACrB;IACA;IACA;IACA,IAAI,EAAE,MAAM,IAAAK,sBAAe,EAACN,QAAQ,EAAEK,EAAE,CAAC,CAAC,EAAE;MAC3CD,cAAc,CAACG,IAAI,CAACF,EAAE,CAAC;MACvB;IACD;IACA,MAAMX,IAAI,GAAG,IAAAc,mBAAY,EAACT,OAAO,CAACU,MAAM,EAAEV,OAAO,CAACW,QAAQ,EAAEL,EAAE,CAAC;IAC/D,IAAIH,QAAQ,EAAE;MACbA,QAAQ,CAACS,GAAG,CAACjB,IAAI,CAAC;MAClBS,gBAAgB,CAACI,IAAI,CAACF,EAAE,CAAC;MACzB;IACD;IACA,IAAI,MAAMZ,cAAc,CAACC,IAAI,CAAC,EAAE;MAC/BS,gBAAgB,CAACI,IAAI,CAACF,EAAE,CAAC;IAC1B,CAAC,MAAM;MACN;MACAD,cAAc,CAACG,IAAI,CAACF,EAAE,CAAC;IACxB;EACD;EAEA,OAAO;IACNO,cAAc,EAAE,CAAC;IACjBT,gBAAgB;IAChBU,kBAAkB,EAAE,EAAE;IACtBT;EACD,CAAC;AACF;;AAEA;AACA;AACA;AACA;AACO,eAAeU,eAAeA,CACpCf,OAAwB,EACxBC,QAAkB,EAClBe,KAAsB,EACtBb,QAA0B,EACC;EAC3B,MAAMc,UAAU,GAAG,MAAM,IAAAC,wBAAiB,EAACjB,QAAQ,EAAEe,KAAK,CAAC;EAC3D,OAAOjB,SAAS,CACfC,OAAO,EACPC,QAAQ,EACRgB,UAAU,CAACE,GAAG,CAACC,SAAS,IAAIA,SAAS,CAACd,EAAE,CAAC,EACzCH,QACD,CAAC;AACF","ignoreList":[]}

package/lib/commonjs/artifacts/paths.js

@@ -0,0 +1,31 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.artifactPath = artifactPath;
+exports.artifactsDirectory = artifactsDirectory;
+var _location = require("../platform/location.js");
+/**
+ * Every artifact path, resolved through one guard.
+ *
+ * POL-011(b) flags media-and-files as a risk precisely because this package
+ * deletes files from disk on cascade. The mitigation is structural rather
+ * than procedural: no code in `artifacts/` builds a path by string
+ * concatenation, and the one function that turns an attachment id into a path
+ * refuses anything escaping the managed root (FR-073, FR-073f).
+ *
+ * That is what makes SC-013a's filesystem tracing pass reliably rather than
+ * usually — there is no second path to audit.
+ */
+
+function artifactsDirectory(layout, scopeKey) {
+  return (0, _location.assertWithinManagedArea)(layout, layout.scopeArtifactsPath(scopeKey));
+}
+function artifactPath(layout, scopeKey, attachmentId) {
+  // `layout.artifactPath` already rejects an id that is not a safe single
+  // path segment; the guard then re-checks the assembled result, so a change
+  // to either one alone cannot open a hole.
+  return (0, _location.assertWithinManagedArea)(layout, layout.artifactPath(scopeKey, attachmentId));
+}
+//# sourceMappingURL=paths.js.map

package/lib/commonjs/artifacts/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_location","require","artifactsDirectory","layout","scopeKey","assertWithinManagedArea","scopeArtifactsPath","artifactPath","attachmentId"],"sourceRoot":"../../../src","sources":["artifacts/paths.ts"],"mappings":";;;;;;;AAaA,IAAAA,SAAA,GAAAC,OAAA;AAbA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIO,SAASC,kBAAkBA,CAACC,MAAqB,EAAEC,QAAgB,EAAU;EACnF,OAAO,IAAAC,iCAAuB,EAACF,MAAM,EAAEA,MAAM,CAACG,kBAAkB,CAACF,QAAQ,CAAC,CAAC;AAC5E;AAEO,SAASG,YAAYA,CAC3BJ,MAAqB,EACrBC,QAAgB,EAChBI,YAAoB,EACX;EACT;EACA;EACA;EACA,OAAO,IAAAH,iCAAuB,EAACF,MAAM,EAAEA,MAAM,CAACI,YAAY,CAACH,QAAQ,EAAEI,YAAY,CAAC,CAAC;AACpF","ignoreList":[]}

package/lib/commonjs/artifacts/reconcile.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.reconcileArtifacts = reconcileArtifacts;
+var _fs = require("../platform/fs.js");
+var _compare = require("../query/compare.js");
+var _paths = require("./paths.js");
+var _store = require("./store.js");
+/**
+ * Reconciliation: the two ways the database and the disk can disagree.
+ *
+ * An **orphaned artifact** is a file with no reference — left by a rolled-back
+ * transaction, or by a crash between the write and the insert. A **dangling
+ * reference** is the reverse: a row pointing at a file the operating system
+ * reclaimed, or the user deleted through a file manager.
+ *
+ * App-triggered only (FR-073d). A background sweep would run during a user's
+ * session without their knowledge, delete files it believes are orphans, and
+ * have no way to distinguish "orphan" from "written by a transaction that has
+ * not committed yet". Handing the trigger to the app makes that an explicit
+ * decision at a moment the app knows is quiet.
+ */
+
+async function filesOnDisk(context) {
+  try {
+    return await (0, _fs.fileSystem)().readdir((0, _paths.artifactsDirectory)(context.layout, context.scopeKey));
+  } catch {
+    // No directory means no artifacts, which is a valid answer rather than
+    // a failure — a scope that never wrote one never created it.
+    return [];
+  }
+}
+async function reconcileArtifacts(context, executor, options = {}) {
+  const references = await (0, _store.listReferences)(executor);
+  const referenced = new Set(references.map(reference => reference.id));
+  const present = new Set(await filesOnDisk(context));
+  const orphanedArtifacts = [...present].filter(id => !referenced.has(id)).sort(_compare.byteOrder);
+  const danglingReferences = references.filter(reference => !present.has(reference.id)).map(reference => reference.id).sort(_compare.byteOrder);
+  const removedArtifacts = [];
+  if (options.removeOrphans) {
+    for (const id of orphanedArtifacts) {
+      if (await (0, _fs.removeIfPresent)((0, _paths.artifactPath)(context.layout, context.scopeKey, id))) {
+        removedArtifacts.push(id);
+      }
+    }
+  }
+  return {
+    orphanedArtifacts,
+    danglingReferences,
+    removedArtifacts
+  };
+}
+//# sourceMappingURL=reconcile.js.map