@chipmobilesdk/rn-local-db 0.4.0 → 0.5.0

package/lib/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["deleteDatabase","deleteScopeData","openDatabase","resetScope","DiagnosticCodes","StorageError","isCode","isStorageError","setDiagnosticLogger","Budgets"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;AACA,SAASA,cAAc,EAAEC,eAAe,EAAEC,YAAY,EAAEC,UAAU,QAAQ,oBAAW;;AAErF;AACA,SAASC,eAAe,EAAEC,YAAY,EAAEC,MAAM,EAAEC,cAAc,QAAQ,yBAAsB;AAC5F,SAASC,mBAAmB,QAA+B,0BAAuB;;AAElF;AACA,SAASC,OAAO,QAAQ,sBAAmB;;AAE3C","ignoreList":[]}

package/lib/module/migration/executor.js

@@ -0,0 +1,132 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { DiagnosticCodes } from "../contract/errors.js";
+import { raise } from "../diagnostics/errors.js";
+import { throwIfFaulted } from "../diagnostics/faults.js";
+import { createSqlCollection } from "../adapter/collection.js";
+import { ensureLedger, FORMAT_VERSION, readVersions, recordAttempt, writeSchemaVersion } from "./ledger.js";
+import { pendingMigrations, validateMigrationChain } from "./validate-chain.js";
+function migrationContextFor(context, executor) {
+  return {
+    collection(name) {
+      return 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.
+      raise(DiagnosticCodes.TRANSACTION_STATE, {
+        message: 'a migration cannot abort its own transaction'
+      });
+    },
+    async execute(sql, params) {
+      await executor.execute(sql, params);
+    }
+  };
+}
+export async function runMigrations(context) {
+  const {
+    config,
+    connection
+  } = context;
+  validateMigrationChain(config);
+  // Skipped when the open already found its bookkeeping tables in place.
+  if (context.ledgerReady !== true) {
+    await ensureLedger(connection);
+  }
+  const {
+    schema: recorded,
+    format
+  } = await readVersions(connection);
+  if (format > 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();
+    raise(DiagnosticCodes.SCHEMA_DOWNGRADE, {
+      message: 'database was written by a newer version of this package',
+      detail: {
+        recordedVersion: format,
+        version: 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();
+    raise(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 pendingMigrations(config, recorded)) {
+    try {
+      await connection.transaction(async tx => {
+        throwIfFaulted('migration');
+        await migration.migrate(migrationContextFor(context, tx));
+        await writeSchemaVersion(tx, migration.version);
+        await 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 recordAttempt(connection, {
+        version: migration.version,
+        attemptedAt: context.now(),
+        outcome: 'failed',
+        failureCode: error.code ?? DiagnosticCodes.MIGRATION_FAILED
+      });
+      await context.closeOnFailure();
+      raise(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/module/migration/executor.js.map

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

package/lib/module/migration/ledger.js

@@ -0,0 +1,57 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { text } from "../sqlite/values.js";
+
+/** Physical layout version, independent of the app's schema version. */
+export const 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
+)`;
+export 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. */
+export 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 => [text(row.key), Number(text(row.value))]));
+  return {
+    schema: values.get('schema_version') ?? 0,
+    format: values.get('format_version') ?? FORMAT_VERSION
+  };
+}
+export 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)]);
+}
+export 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/module/migration/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["text","FORMAT_VERSION","CREATE_META","CREATE_MIGRATIONS","ensureLedger","executor","execute","String","readVersions","result","values","Map","rows","map","row","key","Number","value","schema","get","format","writeSchemaVersion","version","recordAttempt","entry","attemptedAt","outcome","failureCode"],"sourceRoot":"../../../src","sources":["migration/ledger.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAIA,SAASA,IAAI,QAAQ,qBAAkB;;AAEvC;AACA,OAAO,MAAMC,cAAc,GAAG,CAAC;AAE/B,MAAMC,WAAW,GAAG;AACpB;AACA;AACA,EAAE;AAEF,MAAMC,iBAAiB,GAAG;AAC1B;AACA;AACA;AACA;AACA,EAAE;AAEF,OAAO,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,CAACN,cAAc,CAAC,CAC1C,CAAC;EACD,MAAMI,QAAQ,CAACC,OAAO,CACrB,0EAA0E,EAC1E,CAAC,gBAAgB,EAAE,GAAG,CACvB,CAAC;AACF;AASA;AACA,OAAO,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,CAACd,IAAI,CAACc,GAAG,CAACC,GAAG,CAAC,EAAEC,MAAM,CAAChB,IAAI,CAACc,GAAG,CAACG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;EACxF,OAAO;IACNC,MAAM,EAAER,MAAM,CAACS,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC;IACzCC,MAAM,EAAEV,MAAM,CAACS,GAAG,CAAC,gBAAgB,CAAC,IAAIlB;EACzC,CAAC;AACF;AAEA,OAAO,eAAeoB,kBAAkBA,CAAChB,QAAkB,EAAEiB,OAAe,EAAiB;EAC5F,MAAMjB,QAAQ,CAACC,OAAO,CACrB,oGAAoG,EACpG,CAAC,gBAAgB,EAAEC,MAAM,CAACe,OAAO,CAAC,CACnC,CAAC;AACF;AAEA,OAAO,eAAeC,aAAaA,CAClClB,QAAkB,EAClBmB,KAAgG,EAChF;EAChB,MAAMnB,QAAQ,CAACC,OAAO,CACrB;AACF;AACA;AACA;AACA;AACA,0CAA0C,EACxC,CAACkB,KAAK,CAACF,OAAO,EAAEE,KAAK,CAACC,WAAW,EAAED,KAAK,CAACE,OAAO,EAAEF,KAAK,CAACG,WAAW,IAAI,IAAI,CAC5E,CAAC;AACF","ignoreList":[]}

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

@@ -0,0 +1,70 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+import { DiagnosticCodes } from "../contract/errors.js";
+import { raise } from "../diagnostics/errors.js";
+function invalid(message, detail) {
+  raise(DiagnosticCodes.MIGRATION_CONFIG_INVALID, {
+    message,
+    detail
+  });
+}
+export 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. */
+export function orderedMigrations(config) {
+  return [...(config.migrations ?? [])].sort((a, b) => a.version - b.version);
+}
+export function pendingMigrations(config, recordedVersion) {
+  return orderedMigrations(config).filter(migration => migration.version > recordedVersion);
+}
+//# sourceMappingURL=validate-chain.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["DiagnosticCodes","raise","invalid","message","detail","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":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA,SAASA,eAAe,QAAQ,uBAAoB;AAEpD,SAASC,KAAK,QAAQ,0BAAuB;AAE7C,SAASC,OAAOA,CAACC,OAAe,EAAEC,MAAgC,EAAS;EAC1EH,KAAK,CAACD,eAAe,CAACK,wBAAwB,EAAE;IAAEF,OAAO;IAAEC;EAAO,CAAC,CAAC;AACrE;AAEA,OAAO,SAASE,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;IACxET,OAAO,CAAC,0CAA0C,CAAC;EACpD;EAEA,MAAMU,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;MAClEb,OAAO,CAAC,8CAA8C,CAAC;IACxD;IACA,IAAIU,QAAQ,CAACI,GAAG,CAACF,SAAS,CAACC,OAAO,CAAC,EAAE;MACpCb,OAAO,CAAC,6BAA6B,EAAE;QAAEa,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;MAC5ChB,OAAO,CAAC,mCAAmC,EAAE;QAAEa,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;MAC3Bb,OAAO,CAAC,2BAA2B,EAAE;QAAEa;MAAQ,CAAC,CAAC;IAClD;EACD;EAEA,KAAK,MAAMA,OAAO,IAAIH,QAAQ,EAAE;IAC/B,IAAIG,OAAO,GAAGR,MAAM,CAACI,aAAa,EAAE;MACnCT,OAAO,CAAC,sDAAsD,EAAE;QAAEa;MAAQ,CAAC,CAAC;IAC7E;EACD;AACD;;AAEA;AACA,OAAO,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;AAEA,OAAO,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/module/package.json

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

package/lib/module/platform/backup-android-verify.js

@@ -0,0 +1,69 @@
+"use strict";
+
+/**
+ * Android backup posture: verified and reported, never enforced.
+ *
+ * Android decides backup participation from `android:dataExtractionRules` in
+ * the app's manifest. That is build-time and app-owned, and this package
+ * authors no native code, so it cannot contribute an entry and cannot change
+ * the answer at runtime (research.md R5).
+ *
+ * What it can do is check the one thing that silently breaks the documented
+ * fix: the rule the README tells an app to ship addresses the `file` domain,
+ * which is the app's `files/` directory. If the managed root did not land
+ * under that directory, the app can ship the XML exactly as documented and
+ * still have an unprotected database. That mismatch is detectable here, and
+ * an app learning it from this report is the whole point of FR-111 — the
+ * alternative is learning it from an incident.
+ */
+
+import { Platform } from 'react-native';
+import { MANAGED_ROOT_NAME, normalizePath } from "./location.js";
+export function isAndroid() {
+  return Platform.OS === 'android';
+}
+
+/** The `path` an app's exclusion rule must name for the root it actually got. */
+export function coveragePathFor(layout) {
+  const root = normalizePath(layout.root);
+  const marker = `/files/`;
+  const index = root.indexOf(marker);
+  if (index === -1) {
+    return null;
+  }
+  return root.slice(index + marker.length);
+}
+export function androidPosture(layout, includeInPlatformBackup) {
+  const requested = includeInPlatformBackup ? 'included' : 'excluded';
+  const coverage = coveragePathFor(layout);
+  if (coverage === null) {
+    return {
+      requested,
+      // Not "excluded" and not "included": the package genuinely does not
+      // know, and saying either would be a claim it cannot support.
+      observed: 'unknown',
+      enforcedBy: 'app-manifest',
+      warning: 'The managed storage area is not under the Android file domain, so the ' + 'documented data_extraction_rules.xml entry will not cover it. Backup ' + 'posture cannot be honoured on this platform until the app supplies a ' + 'rule matching the actual storage location.'
+    };
+  }
+  return {
+    requested,
+    observed: 'unknown',
+    enforcedBy: 'app-manifest',
+    warning: `Android backup participation is declared by the app, not this package. ` + `Confirm android/app/src/main/res/xml/data_extraction_rules.xml contains an ` + `entry for domain="file" path="${MANAGED_ROOT_NAME}/" and that ` + `AndroidManifest.xml references it; the observed posture cannot be verified ` + `from JavaScript.`
+  };
+}
+
+/**
+ * The posture the handle reports (FR-111).
+ *
+ * Split by platform rather than smoothed over, because a consumer writing a
+ * privacy disclosure needs to know which of the two answers it is holding.
+ */
+export function effectivePostureFor(layout, includeInPlatformBackup, iosPostureFor) {
+  if (isAndroid()) {
+    return androidPosture(layout, includeInPlatformBackup);
+  }
+  return iosPostureFor(includeInPlatformBackup);
+}
+//# sourceMappingURL=backup-android-verify.js.map

package/lib/module/platform/backup-android-verify.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Platform","MANAGED_ROOT_NAME","normalizePath","isAndroid","OS","coveragePathFor","layout","root","marker","index","indexOf","slice","length","androidPosture","includeInPlatformBackup","requested","coverage","observed","enforcedBy","warning","effectivePostureFor","iosPostureFor"],"sourceRoot":"../../../src","sources":["platform/backup-android-verify.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,QAAQ,QAAQ,cAAc;AAGvC,SAASC,iBAAiB,EAAEC,aAAa,QAA4B,eAAY;AAEjF,OAAO,SAASC,SAASA,CAAA,EAAY;EACpC,OAAOH,QAAQ,CAACI,EAAE,KAAK,SAAS;AACjC;;AAEA;AACA,OAAO,SAASC,eAAeA,CAACC,MAAqB,EAAiB;EACrE,MAAMC,IAAI,GAAGL,aAAa,CAACI,MAAM,CAACC,IAAI,CAAC;EACvC,MAAMC,MAAM,GAAG,SAAS;EACxB,MAAMC,KAAK,GAAGF,IAAI,CAACG,OAAO,CAACF,MAAM,CAAC;EAClC,IAAIC,KAAK,KAAK,CAAC,CAAC,EAAE;IACjB,OAAO,IAAI;EACZ;EACA,OAAOF,IAAI,CAACI,KAAK,CAACF,KAAK,GAAGD,MAAM,CAACI,MAAM,CAAC;AACzC;AAEA,OAAO,SAASC,cAAcA,CAC7BP,MAAqB,EACrBQ,uBAAgC,EACb;EACnB,MAAMC,SAAS,GAAGD,uBAAuB,GAAG,UAAU,GAAG,UAAU;EACnE,MAAME,QAAQ,GAAGX,eAAe,CAACC,MAAM,CAAC;EAExC,IAAIU,QAAQ,KAAK,IAAI,EAAE;IACtB,OAAO;MACND,SAAS;MACT;MACA;MACAE,QAAQ,EAAE,SAAS;MACnBC,UAAU,EAAE,cAAc;MAC1BC,OAAO,EACN,wEAAwE,GACxE,uEAAuE,GACvE,uEAAuE,GACvE;IACF,CAAC;EACF;EAEA,OAAO;IACNJ,SAAS;IACTE,QAAQ,EAAE,SAAS;IACnBC,UAAU,EAAE,cAAc;IAC1BC,OAAO,EACN,yEAAyE,GACzE,6EAA6E,GAC7E,iCAAiClB,iBAAiB,cAAc,GAChE,6EAA6E,GAC7E;EACF,CAAC;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASmB,mBAAmBA,CAClCd,MAAqB,EACrBQ,uBAAgC,EAChCO,aAAqD,EAClC;EACnB,IAAIlB,SAAS,CAAC,CAAC,EAAE;IAChB,OAAOU,cAAc,CAACP,MAAM,EAAEQ,uBAAuB,CAAC;EACvD;EACA,OAAOO,aAAa,CAACP,uBAAuB,CAAC;AAC9C","ignoreList":[]}

package/lib/module/platform/backup-ios.js

@@ -0,0 +1,44 @@
+"use strict";
+
+/**
+ * iOS backup exclusion.
+ *
+ * `NSURLIsExcludedFromBackupKey` is set on the managed root at creation, and
+ * the attribute is inherited by everything beneath it — so one call covers
+ * the catalog, every scope database, and every artifact, including ones
+ * created years later. Setting it per file would leave a window in which a
+ * freshly written artifact is backed up before the attribute lands.
+ *
+ * This is the half of FR-109 the package can actually enforce. Android is
+ * manifest-owned; see backup-android-verify.ts and research.md R5.
+ */
+
+import { Platform } from 'react-native';
+import { fileSystem } from "./fs.js";
+export function isIos() {
+  return Platform.OS === 'ios';
+}
+
+/**
+ * Create the managed root with the exclusion attribute already on it.
+ *
+ * Idempotent: `mkdir` on an existing directory re-applies the attribute,
+ * which matters because an app that flips the posture between launches must
+ * get the new one without a reinstall.
+ */
+export async function ensureManagedRoot(layout, includeInPlatformBackup) {
+  await fileSystem().mkdir(layout.root, isIos() ? {
+    NSURLIsExcludedFromBackupKey: !includeInPlatformBackup
+  } : {});
+}
+
+/** What the package can state about iOS, where it enforces rather than reports. */
+export function iosPosture(includeInPlatformBackup) {
+  const requested = includeInPlatformBackup ? 'included' : 'excluded';
+  return {
+    requested,
+    observed: requested,
+    enforcedBy: 'package'
+  };
+}
+//# sourceMappingURL=backup-ios.js.map

package/lib/module/platform/backup-ios.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Platform","fileSystem","isIos","OS","ensureManagedRoot","layout","includeInPlatformBackup","mkdir","root","NSURLIsExcludedFromBackupKey","iosPosture","requested","observed","enforcedBy"],"sourceRoot":"../../../src","sources":["platform/backup-ios.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,QAAQ,QAAQ,cAAc;AAGvC,SAASC,UAAU,QAAQ,SAAM;AAGjC,OAAO,SAASC,KAAKA,CAAA,EAAY;EAChC,OAAOF,QAAQ,CAACG,EAAE,KAAK,KAAK;AAC7B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,eAAeC,iBAAiBA,CACtCC,MAAqB,EACrBC,uBAAgC,EAChB;EAChB,MAAML,UAAU,CAAC,CAAC,CAACM,KAAK,CACvBF,MAAM,CAACG,IAAI,EACXN,KAAK,CAAC,CAAC,GAAG;IAAEO,4BAA4B,EAAE,CAACH;EAAwB,CAAC,GAAG,CAAC,CACzE,CAAC;AACF;;AAEA;AACA,OAAO,SAASI,UAAUA,CAACJ,uBAAgC,EAAoB;EAC9E,MAAMK,SAAS,GAAGL,uBAAuB,GAAG,UAAU,GAAG,UAAU;EACnE,OAAO;IACNK,SAAS;IACTC,QAAQ,EAAED,SAAS;IACnBE,UAAU,EAAE;EACb,CAAC;AACF","ignoreList":[]}

package/lib/module/platform/bytes.js

@@ -0,0 +1,148 @@
+"use strict";
+
+/**
+ * Byte handling without Node's `Buffer`.
+ *
+ * Hermes has no global `Buffer`, and `react-native-quick-crypto` installs one
+ * only when the app calls its `install()` — which nothing in this package or its
+ * documentation asked for. Until 0.2.0 attachment writes and reads used the
+ * global anyway, so on a device every attachment operation threw. Everything
+ * here is plain `Uint8Array` and a self-contained base64 codec, identical on
+ * Hermes and in Node.
+ */
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const LOOKUP = (() => {
+  const table = new Int16Array(128).fill(-1);
+  for (let index = 0; index < ALPHABET.length; index += 1) {
+    table[ALPHABET.charCodeAt(index)] = index;
+  }
+  // The URL-safe variants decode too, since some file APIs return them.
+  table['-'.charCodeAt(0)] = 62;
+  table['_'.charCodeAt(0)] = 63;
+  return table;
+})();
+
+/**
+ * Codecs Hermes and Node provide but React Native's type declarations omit.
+ * Read through this view so the package type-checks without DOM or Node types.
+ */
+
+export const host = globalThis;
+
+/* eslint-disable no-bitwise -- base64 is bit packing; there is no clearer way to write it. */
+
+/** Characters per `String.fromCharCode` call; large spreads overflow the stack. */
+const CHUNK = 0x8000;
+export function base64ToBytes(base64) {
+  if (host.atob) {
+    let binary;
+    try {
+      binary = host.atob(base64.replace(/-/g, '+').replace(/_/g, '/'));
+    } catch {
+      // atob is strict where Buffer was lenient; fall through to the
+      // tolerant decoder rather than turn stray characters into a crash.
+    }
+    if (binary !== undefined) {
+      const bytes = new Uint8Array(binary.length);
+      for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+      }
+      return bytes;
+    }
+  }
+  // Decode directly, skipping padding and anything outside the alphabet.
+  const bytes = new Uint8Array(Math.ceil(base64.length * 3 / 4));
+  let out = 0;
+  let buffer = 0;
+  let bits = 0;
+  for (let index = 0; index < base64.length; index += 1) {
+    const code = base64.charCodeAt(index);
+    const value = code < 128 ? LOOKUP[code] : -1;
+    if (value < 0) continue;
+    buffer = buffer << 6 | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes[out++] = buffer >> bits & 0xff;
+    }
+  }
+  return bytes.subarray(0, out);
+}
+export function bytesToBase64(bytes) {
+  if (host.btoa) {
+    const parts = [];
+    for (let index = 0; index < bytes.length; index += CHUNK) {
+      parts.push(String.fromCharCode(...bytes.subarray(index, index + CHUNK)));
+    }
+    return host.btoa(parts.join(''));
+  }
+  const parts = [];
+  for (let start = 0; start < bytes.length; start += CHUNK * 3) {
+    let piece = '';
+    const end = Math.min(bytes.length, start + CHUNK * 3);
+    let index = start;
+    for (; index + 2 < end; index += 3) {
+      const triple = bytes[index] << 16 | bytes[index + 1] << 8 | bytes[index + 2];
+      piece += ALPHABET[triple >> 18] + ALPHABET[triple >> 12 & 63] + ALPHABET[triple >> 6 & 63] + ALPHABET[triple & 63];
+    }
+    const remaining = end - index;
+    if (remaining === 1) {
+      const value = bytes[index];
+      piece += `${ALPHABET[value >> 2]}${ALPHABET[(value & 3) << 4]}==`;
+    } else if (remaining === 2) {
+      const value = bytes[index] << 8 | bytes[index + 1];
+      piece += `${ALPHABET[value >> 10]}${ALPHABET[value >> 4 & 63]}${ALPHABET[(value & 15) << 2]}=`;
+    }
+    parts.push(piece);
+  }
+  return parts.join('');
+}
+
+/** UTF-8 encoding. `TextEncoder` is in Hermes and Node; the loop is the fallback. */
+export function utf8Bytes(value) {
+  if (host.TextEncoder) {
+    return new host.TextEncoder().encode(value);
+  }
+  const encoded = unescape(encodeURIComponent(value));
+  const bytes = new Uint8Array(encoded.length);
+  for (let index = 0; index < encoded.length; index += 1) {
+    bytes[index] = encoded.charCodeAt(index);
+  }
+  return bytes;
+}
+
+/** UTF-8 decoding, the inverse of `utf8Bytes`. */
+export function utf8String(bytes) {
+  if (host.TextDecoder) {
+    return new host.TextDecoder().decode(bytes);
+  }
+  let binary = '';
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return decodeURIComponent(escape(binary));
+}
+
+/* eslint-enable no-bitwise */
+
+export function concatBytes(parts) {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const joined = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    joined.set(part, offset);
+    offset += part.length;
+  }
+  return joined;
+}
+
+/** The ASCII text of `length` bytes from `start`, for magic numbers. */
+export function asciiAt(bytes, start, length) {
+  let text = '';
+  for (let index = start; index < start + length && index < bytes.length; index += 1) {
+    text += String.fromCharCode(bytes[index]);
+  }
+  return text;
+}
+//# sourceMappingURL=bytes.js.map

package/lib/module/platform/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ALPHABET","LOOKUP","table","Int16Array","fill","index","length","charCodeAt","host","globalThis","CHUNK","base64ToBytes","base64","atob","binary","replace","undefined","bytes","Uint8Array","Math","ceil","out","buffer","bits","code","value","subarray","bytesToBase64","btoa","parts","push","String","fromCharCode","join","start","piece","end","min","triple","remaining","utf8Bytes","TextEncoder","encode","encoded","unescape","encodeURIComponent","utf8String","TextDecoder","decode","byte","decodeURIComponent","escape","concatBytes","total","reduce","sum","part","joined","offset","set","asciiAt","text"],"sourceRoot":"../../../src","sources":["platform/bytes.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/platform/fs.js

@@ -0,0 +1,54 @@
+"use strict";
+
+/**
+ * The filesystem peer, behind one lazy accessor.
+ *
+ * Required lazily for the same reason the engine is: a consuming app that
+ * only ever runs the in-memory adapter in tests must not have to install a
+ * native module to import this package. Confining the require to `platform/`
+ * also keeps the native surface four directories wide, which is the layering
+ * rule the ESLint config enforces.
+ */
+
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+import { DiagnosticCodes } from "../contract/errors.js";
+import { StorageError } from "../diagnostics/errors.js";
+
+/**
+ * Only what the package actually uses. The peer's upload and download
+ * helpers are deliberately absent from this type: the package must never
+ * make a network request (FR-084, SC-016), and a surface that cannot express
+ * one is a stronger guarantee than a rule that says not to.
+ */
+
+/** Loaded on first use (rn-core's lazy peer); a missing peer is `STORAGE_ACCESS`. */
+const fs = lazyPeer('@dr.pogodin/react-native-fs', () => {
+  // Inside `try`, so Metro bundles an app that leaves this optional peer out.
+  try {
+    return require('@dr.pogodin/react-native-fs');
+  } catch (cause) {
+    throw cause;
+  }
+});
+
+/** Swap the peer. Tests and the demo app's in-memory mode only; `null` restores it. */
+export function setFileSystem(module) {
+  fs.override(module ?? undefined);
+}
+export function fileSystem() {
+  return fs.require((_peer, cause) => new StorageError(DiagnosticCodes.STORAGE_ACCESS, {
+    message: 'filesystem peer is not installed',
+    cause
+  }));
+}
+
+/** Remove a path, treating "already gone" as success (FR-062). */
+export async function removeIfPresent(path) {
+  try {
+    await fileSystem().unlink(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+//# sourceMappingURL=fs.js.map

package/lib/module/platform/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["lazyPeer","DiagnosticCodes","StorageError","fs","require","cause","setFileSystem","module","override","undefined","fileSystem","_peer","STORAGE_ACCESS","message","removeIfPresent","path","unlink"],"sourceRoot":"../../../src","sources":["platform/fs.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,SAASA,QAAQ,QAAQ,wBAAwB;AAEjD,SAASC,eAAe,QAAQ,uBAAoB;AACpD,SAASC,YAAY,QAAQ,0BAAuB;;AAepD;AACA;AACA;AACA;AACA;AACA;;AAiBA;AACA,MAAMC,EAAE,GAAGH,QAAQ,CAAC,6BAA6B,EAAE,MAAM;EACxD;EACA,IAAI;IACH,OAAOI,OAAO,CAAC,6BAA6B,CAAC;EAC9C,CAAC,CAAC,OAAOC,KAAK,EAAE;IACf,MAAMA,KAAK;EACZ;AACD,CAAC,CAAC;;AAEF;AACA,OAAO,SAASC,aAAaA,CAACC,MAAyB,EAAQ;EAC9DJ,EAAE,CAACK,QAAQ,CAACD,MAAM,IAAIE,SAAS,CAAC;AACjC;AAEA,OAAO,SAASC,UAAUA,CAAA,EAAe;EACxC,OAAOP,EAAE,CAACC,OAAO,CAChB,CAACO,KAAK,EAAEN,KAAK,KACZ,IAAIH,YAAY,CAACD,eAAe,CAACW,cAAc,EAAE;IAChDC,OAAO,EAAE,kCAAkC;IAC3CR;EACD,CAAC,CACH,CAAC;AACF;;AAEA;AACA,OAAO,eAAeS,eAAeA,CAACC,IAAY,EAAoB;EACrE,IAAI;IACH,MAAML,UAAU,CAAC,CAAC,CAACM,MAAM,CAACD,IAAI,CAAC;IAC/B,OAAO,IAAI;EACZ,CAAC,CAAC,MAAM;IACP,OAAO,KAAK;EACb;AACD","ignoreList":[]}