@chipmobilesdk/rn-local-db 0.4.0 → 0.5.0

package/lib/module/adapter/lifecycle.js

@@ -0,0 +1,172 @@
+"use strict";
+
+/**
+ * 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`.
+ */
+
+import { DiagnosticCodes } from "../contract/errors.js";
+import { acquireKey } from "../crypto/key-provider.js";
+import { isCipherAvailable } from "../crypto/provider.js";
+import { raise } from "../diagnostics/errors.js";
+import { throwIfFaulted } from "../diagnostics/faults.js";
+import { runMigrations } from "../migration/executor.js";
+import { effectivePostureFor } from "../platform/backup-android-verify.js";
+import { ensureManagedRoot, iosPosture } from "../platform/backup-ios.js";
+import { layoutFor } from "../platform/location.js";
+import { indexSchemas } from "../schema/declare.js";
+import { validateConfig } from "../schema/validate-config.js";
+import { resolveScope } from "../scope/validate.js";
+import { ensureCatalog, readEntry, registerScope } from "../sqlite/catalog.js";
+import { assertReadable, openConnection } from "../sqlite/connection.js";
+import { isEncryptionAvailable } from "../sqlite/native.js";
+import { acquireHandleSlot, releaseHandleSlot } from "./budgets.js";
+import { clearScopeInvalidation } from "./deletion.js";
+import { buildHandle, schemaFor } from "./handle.js";
+import { syncSchema } from "./schema-sync.js";
+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 (!isEncryptionAvailable()) {
+    raise(DiagnosticCodes.ENCRYPTION_UNAVAILABLE, {
+      message: 'encryption was requested but SQLCipher is not compiled into this build'
+    });
+  }
+  if (!isCipherAvailable()) {
+    raise(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 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.
+    raise(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.
+    raise(DiagnosticCodes.ENCRYPTION_MISMATCH, {
+      message: 'encryption posture does not match the stored database',
+      detail: {
+        scopeKey: scope.key
+      }
+    });
+  }
+}
+export async function openSqliteDatabase(config, options = {}) {
+  const now = options.now ?? (() => Date.now());
+  validateConfig(config);
+  throwIfFaulted('open');
+  const scope = resolveScope(config.scope);
+  const encrypted = resolveEncryption(config);
+  const includeInBackup = config.backup?.includeInPlatformBackup === true;
+  const layout = layoutFor(config.name);
+  await ensureManagedRoot(layout, includeInBackup);
+  const catalog = await 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();
+    releaseHandleSlot();
+  };
+  try {
+    await ensureCatalog(catalog);
+    await assertPostureMatches(catalog, scope, encrypted);
+    if (encrypted) {
+      key = await acquireKey(config.encryption, scope);
+    }
+    acquireHandleSlot();
+    try {
+      connection = await openConnection({
+        path: layout.scopeDataPath(scope.key),
+        ...(key ? {
+          encryptionKey: key.value()
+        } : {})
+      });
+    } catch (error) {
+      releaseHandleSlot();
+      throw error;
+    }
+    await assertReadable(connection);
+    const schemas = indexSchemas(config.collections);
+    // No DDL at all when the declaration is the one already applied (LDB-07).
+    const schema = await syncSchema(connection, config);
+    const scopeConnection = connection;
+    const schemaVersion = await runMigrations({
+      connection: scopeConnection,
+      config,
+      schemaFor: name => schemaFor(schemas, name),
+      now,
+      closeOnFailure: releaseConnection,
+      ledgerReady: schema.unchanged
+    });
+    await schema.record();
+    await registerScope(catalog, {
+      scopeKey: scope.key,
+      createdAt: now(),
+      deletionState: 'active',
+      backupPosture: includeInBackup ? 'included' : 'excluded',
+      encrypted
+    });
+    await catalog.close();
+    clearScopeInvalidation(config.name, scope.key);
+    return buildHandle({
+      config,
+      connection: scopeConnection,
+      key,
+      layout,
+      now,
+      schemaVersion,
+      schemas,
+      scope,
+      posture: effectivePostureFor(layout, includeInBackup, 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/module/adapter/lifecycle.js.map

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

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

@@ -0,0 +1,121 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { ensureAttachmentTable } from "../artifacts/store.js";
+import { addColumnSql, createIndexSql, createTableSql, physicalIndexName } from "../sqlite/row-codec.js";
+import { text } from "../sqlite/values.js";
+
+/** 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 ? 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 => [text(row.name), text(row.sql)]));
+  const wanted = new Map(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 !== 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(createTableSql(schema));
+  const info = await connection.execute(`PRAGMA table_info("c_${schema.name}")`);
+  const present = new Set(info.rows.map(row => text(row.name)));
+  for (const field of schema.fields ?? []) {
+    const column = `f_${field.name}`;
+    if (present.has(column)) {
+      continue;
+    }
+    await connection.execute(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);
+}
+export 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 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/module/adapter/schema-sync.js.map

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

package/lib/module/adapter/transaction.js

@@ -0,0 +1,54 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { DiagnosticCodes } from "../contract/errors.js";
+import { raise } from "../diagnostics/errors.js";
+export function createTransaction(host) {
+  let settled = false;
+  const assertLive = () => {
+    if (settled) {
+      raise(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/module/adapter/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DiagnosticCodes","raise","createTransaction","host","settled","assertLive","TRANSACTION_STATE","message","transaction","collection","name","attachments","abort","rollback","isSettled","settle"],"sourceRoot":"../../../src","sources":["adapter/transaction.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,eAAe,QAAQ,uBAAoB;AAIpD,SAASC,KAAK,QAAQ,0BAAuB;AAe7C,OAAO,SAASC,iBAAiBA,CAACC,IAAqB,EAAsB;EAC5E,IAAIC,OAAO,GAAG,KAAK;EAEnB,MAAMC,UAAU,GAAGA,CAAA,KAAY;IAC9B,IAAID,OAAO,EAAE;MACZH,KAAK,CAACD,eAAe,CAACM,iBAAiB,EAAE;QACxCC,OAAO,EAAE;MACV,CAAC,CAAC;IACH;EACD,CAAC;EAED,MAAMC,WAAwB,GAAG;IAChCC,UAAUA,CAA+BC,IAAY,EAAoB;MACxEL,UAAU,CAAC,CAAC;MACZ,OAAOF,IAAI,CAACM,UAAU,CAAIC,IAAI,CAAC;IAChC,CAAC;IACDC,WAAWA,CAAA,EAAgB;MAC1BN,UAAU,CAAC,CAAC;MACZ,OAAOF,IAAI,CAACQ,WAAW,CAAC,CAAC;IAC1B,CAAC;IACD,MAAMC,KAAKA,CAAA,EAAkB;MAC5BP,UAAU,CAAC,CAAC;MACZD,OAAO,GAAG,IAAI;MACd,MAAMD,IAAI,CAACU,QAAQ,CAAC,CAAC;IACtB;EACD,CAAC;EAED,OAAO;IACNL,WAAW;IACXM,SAAS,EAAEA,CAAA,KAAMV,OAAO;IACxBW,MAAM,EAAEA,CAAA,KAAM;MACbX,OAAO,GAAG,IAAI;IACf;EACD,CAAC;AACF","ignoreList":[]}

package/lib/module/artifacts/availability.js

@@ -0,0 +1,86 @@
+"use strict";
+
+/**
+ * "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).
+ */
+
+import { fileSystem } from "../platform/fs.js";
+import { asciiAt, base64ToBytes } from "../platform/bytes.js";
+import { HEADER_BYTES, MAGIC } from "../crypto/chunked-cipher.js";
+import { artifactPath } from "./paths.js";
+import { readReference } from "./store.js";
+export async function artifactAvailability(context, executor, id) {
+  const reference = await 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 = artifactPath(context.layout, context.scopeKey, id);
+  let size;
+  try {
+    const stat = await 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 < HEADER_BYTES) {
+    return {
+      id,
+      state: 'undecryptable',
+      size: reference.size
+    };
+  }
+  try {
+    const header = base64ToBytes(await fileSystem().read(path, HEADER_BYTES, 0, 'base64'));
+    if (asciiAt(header, 0, 4) !== 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/module/artifacts/availability.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["fileSystem","asciiAt","base64ToBytes","HEADER_BYTES","MAGIC","artifactPath","readReference","artifactAvailability","context","executor","id","reference","state","path","layout","scopeKey","size","stat","isFile","artifactKey","header","read"],"sourceRoot":"../../../src","sources":["artifacts/availability.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,UAAU,QAAQ,mBAAgB;AAC3C,SAASC,OAAO,EAAEC,aAAa,QAAQ,sBAAmB;AAC1D,SAASC,YAAY,EAAEC,KAAK,QAAQ,6BAA0B;AAE9D,SAASC,YAAY,QAAQ,YAAS;AACtC,SAASC,aAAa,QAA8B,YAAS;AAE7D,OAAO,eAAeC,oBAAoBA,CACzCC,OAAwB,EACxBC,QAAkB,EAClBC,EAAU,EACwB;EAClC,MAAMC,SAAS,GAAG,MAAML,aAAa,CAACG,QAAQ,EAAEC,EAAE,CAAC;EACnD,IAAI,CAACC,SAAS,EAAE;IACf;IACA;IACA,OAAO;MAAED,EAAE;MAAEE,KAAK,EAAE;IAAU,CAAC;EAChC;EAEA,MAAMC,IAAI,GAAGR,YAAY,CAACG,OAAO,CAACM,MAAM,EAAEN,OAAO,CAACO,QAAQ,EAAEL,EAAE,CAAC;EAE/D,IAAIM,IAAY;EAChB,IAAI;IACH,MAAMC,IAAI,GAAG,MAAMjB,UAAU,CAAC,CAAC,CAACiB,IAAI,CAACJ,IAAI,CAAC;IAC1C,IAAI,CAACI,IAAI,CAACC,MAAM,CAAC,CAAC,EAAE;MACnB,OAAO;QAAER,EAAE;QAAEE,KAAK,EAAE;MAAe,CAAC;IACrC;IACAI,IAAI,GAAGC,IAAI,CAACD,IAAI;EACjB,CAAC,CAAC,MAAM;IACP,OAAO;MAAEN,EAAE;MAAEE,KAAK,EAAE;IAAU,CAAC;EAChC;EAEA,IAAIJ,OAAO,CAACW,WAAW,CAACT,EAAE,CAAC,KAAK,IAAI,EAAE;IACrC,OAAO;MAAEA,EAAE;MAAEE,KAAK,EAAE,WAAW;MAAEI,IAAI,EAAEL,SAAS,CAACK;IAAK,CAAC;EACxD;EAEA,IAAIA,IAAI,GAAGb,YAAY,EAAE;IACxB,OAAO;MAAEO,EAAE;MAAEE,KAAK,EAAE,eAAe;MAAEI,IAAI,EAAEL,SAAS,CAACK;IAAK,CAAC;EAC5D;EAEA,IAAI;IACH,MAAMI,MAAM,GAAGlB,aAAa,CAAC,MAAMF,UAAU,CAAC,CAAC,CAACqB,IAAI,CAACR,IAAI,EAAEV,YAAY,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;IACtF,IAAIF,OAAO,CAACmB,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,KAAKhB,KAAK,EAAE;MACpC,OAAO;QAAEM,EAAE;QAAEE,KAAK,EAAE,eAAe;QAAEI,IAAI,EAAEL,SAAS,CAACK;MAAK,CAAC;IAC5D;EACD,CAAC,CAAC,MAAM;IACP,OAAO;MAAEN,EAAE;MAAEE,KAAK,EAAE,cAAc;MAAEI,IAAI,EAAEL,SAAS,CAACK;IAAK,CAAC;EAC3D;EAEA,OAAO;IAAEN,EAAE;IAAEE,KAAK,EAAE,WAAW;IAAEI,IAAI,EAAEL,SAAS,CAACK;EAAK,CAAC;AACxD","ignoreList":[]}

package/lib/module/artifacts/cascade.js

@@ -0,0 +1,75 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { fileSystem, removeIfPresent } from "../platform/fs.js";
+import { artifactPath } from "./paths.js";
+import { deleteReference, listReferencesFor } from "./store.js";
+/** Unlinks one artifact file. True when the file is gone afterwards, whoever removed it. */
+export async function unlinkArtifact(path) {
+  if (await 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 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 deleteReference(executor, id))) {
+      failedRemovals.push(id);
+      continue;
+    }
+    const path = 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.
+ */
+export async function cascadeForOwner(context, executor, owner, deferred) {
+  const references = await listReferencesFor(executor, owner);
+  return removeAll(context, executor, references.map(reference => reference.id), deferred);
+}
+//# sourceMappingURL=cascade.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["fileSystem","removeIfPresent","artifactPath","deleteReference","listReferencesFor","unlinkArtifact","path","exists","removeAll","context","executor","ids","deferred","removedArtifacts","failedRemovals","id","push","layout","scopeKey","add","removedRecords","orphanedReferences","cascadeForOwner","owner","references","map","reference"],"sourceRoot":"../../../src","sources":["artifacts/cascade.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,UAAU,EAAEC,eAAe,QAAQ,mBAAgB;AAE5D,SAASC,YAAY,QAAQ,YAAS;AACtC,SACCC,eAAe,EACfC,iBAAiB,QAGX,YAAS;AAIhB;AACA,OAAO,eAAeC,cAAcA,CAACC,IAAY,EAAoB;EACpE,IAAI,MAAML,eAAe,CAACK,IAAI,CAAC,EAAE;IAChC,OAAO,IAAI;EACZ;EACA;EACA;EACA;EACA,IAAI;IACH,OAAO,EAAE,MAAMN,UAAU,CAAC,CAAC,CAACO,MAAM,CAACD,IAAI,CAAC,CAAC;EAC1C,CAAC,CAAC,MAAM;IACP,OAAO,KAAK;EACb;AACD;AAEA,eAAeE,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,MAAMR,eAAe,CAACO,QAAQ,EAAEK,EAAE,CAAC,CAAC,EAAE;MAC3CD,cAAc,CAACE,IAAI,CAACD,EAAE,CAAC;MACvB;IACD;IACA,MAAMT,IAAI,GAAGJ,YAAY,CAACO,OAAO,CAACQ,MAAM,EAAER,OAAO,CAACS,QAAQ,EAAEH,EAAE,CAAC;IAC/D,IAAIH,QAAQ,EAAE;MACbA,QAAQ,CAACO,GAAG,CAACb,IAAI,CAAC;MAClBO,gBAAgB,CAACG,IAAI,CAACD,EAAE,CAAC;MACzB;IACD;IACA,IAAI,MAAMV,cAAc,CAACC,IAAI,CAAC,EAAE;MAC/BO,gBAAgB,CAACG,IAAI,CAACD,EAAE,CAAC;IAC1B,CAAC,MAAM;MACN;MACAD,cAAc,CAACE,IAAI,CAACD,EAAE,CAAC;IACxB;EACD;EAEA,OAAO;IACNK,cAAc,EAAE,CAAC;IACjBP,gBAAgB;IAChBQ,kBAAkB,EAAE,EAAE;IACtBP;EACD,CAAC;AACF;;AAEA;AACA;AACA;AACA;AACA,OAAO,eAAeQ,eAAeA,CACpCb,OAAwB,EACxBC,QAAkB,EAClBa,KAAsB,EACtBX,QAA0B,EACC;EAC3B,MAAMY,UAAU,GAAG,MAAMpB,iBAAiB,CAACM,QAAQ,EAAEa,KAAK,CAAC;EAC3D,OAAOf,SAAS,CACfC,OAAO,EACPC,QAAQ,EACRc,UAAU,CAACC,GAAG,CAACC,SAAS,IAAIA,SAAS,CAACX,EAAE,CAAC,EACzCH,QACD,CAAC;AACF","ignoreList":[]}

package/lib/module/artifacts/paths.js

@@ -0,0 +1,26 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { assertWithinManagedArea } from "../platform/location.js";
+export function artifactsDirectory(layout, scopeKey) {
+  return assertWithinManagedArea(layout, layout.scopeArtifactsPath(scopeKey));
+}
+export 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 assertWithinManagedArea(layout, layout.artifactPath(scopeKey, attachmentId));
+}
+//# sourceMappingURL=paths.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["assertWithinManagedArea","artifactsDirectory","layout","scopeKey","scopeArtifactsPath","artifactPath","attachmentId"],"sourceRoot":"../../../src","sources":["artifacts/paths.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,uBAAuB,QAA4B,yBAAsB;AAElF,OAAO,SAASC,kBAAkBA,CAACC,MAAqB,EAAEC,QAAgB,EAAU;EACnF,OAAOH,uBAAuB,CAACE,MAAM,EAAEA,MAAM,CAACE,kBAAkB,CAACD,QAAQ,CAAC,CAAC;AAC5E;AAEA,OAAO,SAASE,YAAYA,CAC3BH,MAAqB,EACrBC,QAAgB,EAChBG,YAAoB,EACX;EACT;EACA;EACA;EACA,OAAON,uBAAuB,CAACE,MAAM,EAAEA,MAAM,CAACG,YAAY,CAACF,QAAQ,EAAEG,YAAY,CAAC,CAAC;AACpF","ignoreList":[]}

package/lib/module/artifacts/reconcile.js

@@ -0,0 +1,51 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { fileSystem, removeIfPresent } from "../platform/fs.js";
+import { byteOrder } from "../query/compare.js";
+import { artifactPath, artifactsDirectory } from "./paths.js";
+import { listReferences } from "./store.js";
+async function filesOnDisk(context) {
+  try {
+    return await fileSystem().readdir(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 [];
+  }
+}
+export async function reconcileArtifacts(context, executor, options = {}) {
+  const references = await 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(byteOrder);
+  const danglingReferences = references.filter(reference => !present.has(reference.id)).map(reference => reference.id).sort(byteOrder);
+  const removedArtifacts = [];
+  if (options.removeOrphans) {
+    for (const id of orphanedArtifacts) {
+      if (await removeIfPresent(artifactPath(context.layout, context.scopeKey, id))) {
+        removedArtifacts.push(id);
+      }
+    }
+  }
+  return {
+    orphanedArtifacts,
+    danglingReferences,
+    removedArtifacts
+  };
+}
+//# sourceMappingURL=reconcile.js.map

package/lib/module/artifacts/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["fileSystem","removeIfPresent","byteOrder","artifactPath","artifactsDirectory","listReferences","filesOnDisk","context","readdir","layout","scopeKey","reconcileArtifacts","executor","options","references","referenced","Set","map","reference","id","present","orphanedArtifacts","filter","has","sort","danglingReferences","removedArtifacts","removeOrphans","push"],"sourceRoot":"../../../src","sources":["artifacts/reconcile.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,UAAU,EAAEC,eAAe,QAAQ,mBAAgB;AAC5D,SAASC,SAAS,QAAQ,qBAAkB;AAE5C,SAASC,YAAY,EAAEC,kBAAkB,QAAQ,YAAS;AAC1D,SAASC,cAAc,QAA8B,YAAS;AAO9D,eAAeC,WAAWA,CAACC,OAAwB,EAAqB;EACvE,IAAI;IACH,OAAO,MAAMP,UAAU,CAAC,CAAC,CAACQ,OAAO,CAACJ,kBAAkB,CAACG,OAAO,CAACE,MAAM,EAAEF,OAAO,CAACG,QAAQ,CAAC,CAAC;EACxF,CAAC,CAAC,MAAM;IACP;IACA;IACA,OAAO,EAAE;EACV;AACD;AAEA,OAAO,eAAeC,kBAAkBA,CACvCJ,OAAwB,EACxBK,QAAkB,EAClBC,OAAyB,GAAG,CAAC,CAAC,EACE;EAChC,MAAMC,UAAU,GAAG,MAAMT,cAAc,CAACO,QAAQ,CAAC;EACjD,MAAMG,UAAU,GAAG,IAAIC,GAAG,CAACF,UAAU,CAACG,GAAG,CAACC,SAAS,IAAIA,SAAS,CAACC,EAAE,CAAC,CAAC;EACrE,MAAMC,OAAO,GAAG,IAAIJ,GAAG,CAAC,MAAMV,WAAW,CAACC,OAAO,CAAC,CAAC;EAEnD,MAAMc,iBAAiB,GAAG,CAAC,GAAGD,OAAO,CAAC,CAACE,MAAM,CAACH,EAAE,IAAI,CAACJ,UAAU,CAACQ,GAAG,CAACJ,EAAE,CAAC,CAAC,CAACK,IAAI,CAACtB,SAAS,CAAC;EACxF,MAAMuB,kBAAkB,GAAGX,UAAU,CACnCQ,MAAM,CAACJ,SAAS,IAAI,CAACE,OAAO,CAACG,GAAG,CAACL,SAAS,CAACC,EAAE,CAAC,CAAC,CAC/CF,GAAG,CAACC,SAAS,IAAIA,SAAS,CAACC,EAAE,CAAC,CAC9BK,IAAI,CAACtB,SAAS,CAAC;EAEjB,MAAMwB,gBAA0B,GAAG,EAAE;EACrC,IAAIb,OAAO,CAACc,aAAa,EAAE;IAC1B,KAAK,MAAMR,EAAE,IAAIE,iBAAiB,EAAE;MACnC,IAAI,MAAMpB,eAAe,CAACE,YAAY,CAACI,OAAO,CAACE,MAAM,EAAEF,OAAO,CAACG,QAAQ,EAAES,EAAE,CAAC,CAAC,EAAE;QAC9EO,gBAAgB,CAACE,IAAI,CAACT,EAAE,CAAC;MAC1B;IACD;EACD;EAEA,OAAO;IAAEE,iBAAiB;IAAEI,kBAAkB;IAAEC;EAAiB,CAAC;AACnE","ignoreList":[]}