@chipmobilesdk/rn-local-db 0.4.0 → 0.5.0

package/lib/module/artifacts/store.js

@@ -0,0 +1,289 @@
+"use strict";
+
+/**
+ * Artifacts: the file on disk and the reference to it.
+ *
+ * The reference lives in the scope's own database, so a reference created
+ * inside a transaction rolls back with it (FR-072) — no bookkeeping required,
+ * because the connection routes through the transaction in flight.
+ *
+ * The file does not roll back. A filesystem write is not part of a SQL
+ * transaction and cannot be made part of one, so a rolled-back transaction
+ * leaves an artifact on disk with nothing pointing at it. That is not a bug
+ * to be engineered away; it is why reconciliation exists (FR-073d), and why
+ * the write order is deliberate: **the file completes first, then the
+ * reference**. The reverse order would produce a reference to a file that
+ * does not exist, which is the failure a consumer cannot recover from — it
+ * looks like data the app has and does not.
+ */
+
+import { Budgets } from "../contract/config.js";
+import { DiagnosticCodes } from "../contract/errors.js";
+import { isStorageError, raise } from "../diagnostics/errors.js";
+import { throwIfFaulted } from "../diagnostics/faults.js";
+import { raiseNative } from "../diagnostics/map-native.js";
+import { fileSystem, removeIfPresent } from "../platform/fs.js";
+import { base64ToBytes, bytesToBase64, concatBytes } from "../platform/bytes.js";
+import { assertArtifactWithinBudget } from "../query/budgets.js";
+import { HEADER_BYTES, TAG_BYTES, chunkOffset, chunkPlaintextLength, decodeHeader, decryptChunk, encodeHeader, encryptChunk, headerFor } from "../crypto/chunked-cipher.js";
+import { maybeNum, num, text } from "../sqlite/values.js";
+import { artifactPath, artifactsDirectory } from "./paths.js";
+const CREATE_ATTACHMENTS = `CREATE TABLE IF NOT EXISTS _attachments (
+  id               TEXT PRIMARY KEY,
+  owner_collection TEXT,
+  owner_id         TEXT,
+  content_type     TEXT NOT NULL,
+  size             INTEGER NOT NULL,
+  chunk_size       INTEGER,
+  chunk_count      INTEGER,
+  created_at       INTEGER NOT NULL
+)`;
+const CREATE_OWNER_INDEX = 'CREATE INDEX IF NOT EXISTS _attachments_owner ON _attachments (owner_collection, owner_id)';
+export async function ensureAttachmentTable(executor) {
+  await executor.execute(CREATE_ATTACHMENTS);
+  await executor.execute(CREATE_OWNER_INDEX);
+}
+function toReference(row) {
+  const reference = {
+    id: text(row.id),
+    contentType: text(row.content_type),
+    size: num(row.size),
+    createdAt: num(row.created_at)
+  };
+  if (row.owner_collection != null && row.owner_id != null) {
+    reference.owner = {
+      collection: text(row.owner_collection),
+      id: text(row.owner_id)
+    };
+  }
+  const chunkSize = maybeNum(row.chunk_size);
+  if (chunkSize !== null) {
+    reference.chunkSize = chunkSize;
+    reference.chunkCount = num(row.chunk_count);
+  }
+  return reference;
+}
+export async function readReference(executor, id) {
+  const result = await executor.execute('SELECT * FROM _attachments WHERE id = ?', [id]);
+  const row = result.rows[0];
+  return row ? toReference(row) : null;
+}
+export async function listReferences(executor) {
+  const result = await executor.execute('SELECT * FROM _attachments ORDER BY id ASC');
+  return result.rows.map(toReference);
+}
+export async function listReferencesFor(executor, owner) {
+  const result = await executor.execute('SELECT * FROM _attachments WHERE owner_collection = ? AND owner_id = ? ORDER BY id ASC', [owner.collection, owner.id]);
+  return result.rows.map(toReference);
+}
+async function insertReference(executor, reference) {
+  await executor.execute(`INSERT INTO _attachments
+		 (id, owner_collection, owner_id, content_type, size, chunk_size, chunk_count, created_at)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+		 ON CONFLICT(id) DO UPDATE SET
+		   owner_collection = excluded.owner_collection,
+		   owner_id = excluded.owner_id,
+		   content_type = excluded.content_type,
+		   size = excluded.size,
+		   chunk_size = excluded.chunk_size,
+		   chunk_count = excluded.chunk_count,
+		   created_at = excluded.created_at`, [reference.id, reference.owner?.collection ?? null, reference.owner?.id ?? null, reference.contentType, reference.size, reference.chunkSize ?? null, reference.chunkCount ?? null, reference.createdAt]);
+}
+export async function deleteReference(executor, id) {
+  const result = await executor.execute('DELETE FROM _attachments WHERE id = ?', [id]);
+  return result.rowsAffected > 0;
+}
+async function writePlaintext(path, content) {
+  await fileSystem().writeFile(path, content, 'base64');
+}
+
+/** Where an artifact's bytes come from: how many, and any one chunk of them. */
+
+/**
+ * Encrypted write, one chunk in flight.
+ *
+ * The header goes down first because its contents — chunk size, chunk count,
+ * plaintext length — are all known from the input length before any
+ * encryption happens. Only the tags depend on the ciphertext, and they follow
+ * their own chunk, so the whole write is append-only and peak memory is one
+ * chunk regardless of artifact size when the source is a file (FR-107a).
+ */
+async function writeEncrypted(path, key, source) {
+  const header = headerFor(source.size, Budgets.ARTIFACT_CHUNK_BYTES);
+  await fileSystem().writeFile(path, bytesToBase64(encodeHeader(header)), 'base64');
+  for (let index = 0; index < header.chunkCount; index += 1) {
+    const chunk = await source.chunk(index * header.chunkSize, chunkPlaintextLength(header, index));
+    await fileSystem().appendFile(path, bytesToBase64(encryptChunk(key, index, chunk)), 'base64');
+  }
+  return {
+    chunkSize: header.chunkSize,
+    chunkCount: header.chunkCount
+  };
+}
+function sourceFileOf(input) {
+  if (typeof input.sourcePath !== 'string') {
+    return null;
+  }
+  return input.sourcePath.startsWith('file://') ? input.sourcePath.slice('file://'.length) : input.sourcePath;
+}
+
+/**
+ * The input as something to read from. A base64 `content` is decoded whole,
+ * which is the cost of that form; a `sourcePath` is only measured here and
+ * read a chunk at a time, or not read by JS at all (LDB-09).
+ */
+async function byteSourceFor(input) {
+  const file = sourceFileOf(input);
+  if (file === null) {
+    if (typeof input.content !== 'string') {
+      raise(DiagnosticCodes.CONFIG_INVALID, {
+        message: 'an attachment needs content or sourcePath',
+        detail: {
+          attachmentId: input.id
+        }
+      });
+    }
+    const plaintext = base64ToBytes(input.content);
+    return {
+      size: plaintext.length,
+      chunk: async (offset, length) => plaintext.subarray(offset, offset + length)
+    };
+  }
+  let size;
+  try {
+    size = (await fileSystem().stat(file)).size;
+  } catch (error) {
+    raiseNative(error, {
+      operation: 'attachment'
+    });
+  }
+  return {
+    size,
+    chunk: async (offset, length) => base64ToBytes(await fileSystem().read(file, length, offset, 'base64'))
+  };
+}
+export async function writeArtifact(context, input) {
+  throwIfFaulted('attachmentWrite');
+  const source = await byteSourceFor(input);
+  assertArtifactWithinBudget(input.id, source.size);
+  const path = artifactPath(context.layout, context.scopeKey, input.id);
+  const key = context.artifactKey(input.id);
+  const file = sourceFileOf(input);
+  let chunking;
+  try {
+    await fileSystem().mkdir(artifactsDirectory(context.layout, context.scopeKey));
+    if (key) {
+      chunking = await writeEncrypted(path, key, source);
+    } else if (file !== null) {
+      await fileSystem().copyFile(file, path);
+    } else {
+      await writePlaintext(path, input.content);
+    }
+  } catch (error) {
+    // A partial file with no reference is an orphan reconciliation can
+    // find; a reference to a partial file is data the app believes it has.
+    await removeIfPresent(path);
+    raiseNative(error, {
+      operation: 'attachment'
+    });
+  }
+  const reference = {
+    id: input.id,
+    contentType: input.contentType,
+    size: source.size,
+    createdAt: context.now()
+  };
+  if (input.owner) {
+    reference.owner = input.owner;
+  }
+  if (chunking) {
+    reference.chunkSize = chunking.chunkSize;
+    reference.chunkCount = chunking.chunkCount;
+  }
+
+  // Only now. See the note at the top of this file.
+  await insertReference(context.executor(), reference);
+  return reference;
+}
+async function readPlaintext(path, range) {
+  if (!range) {
+    return fileSystem().readFile(path, 'base64');
+  }
+  return fileSystem().read(path, range.length, range.offset, 'base64');
+}
+async function readEncrypted(path, key, range) {
+  const headerBytes = base64ToBytes(await fileSystem().read(path, HEADER_BYTES, 0, 'base64'));
+  const header = decodeHeader(headerBytes);
+  const from = range?.offset ?? 0;
+  const to = range ? Math.min(header.plaintextSize, from + range.length) : header.plaintextSize;
+  if (to <= from) {
+    return '';
+  }
+  const first = Math.floor(from / header.chunkSize);
+  const last = Math.floor((to - 1) / header.chunkSize);
+  const pieces = [];
+  for (let index = first; index <= last; index += 1) {
+    const stored = base64ToBytes(await fileSystem().read(path, chunkPlaintextLength(header, index) + TAG_BYTES, chunkOffset(header, index), 'base64'));
+    const decrypted = decryptChunk(key, index, stored);
+    const chunkStart = index * header.chunkSize;
+    pieces.push(decrypted.subarray(Math.max(0, from - chunkStart), Math.min(decrypted.length, to - chunkStart)));
+  }
+  return bytesToBase64(concatBytes(pieces));
+}
+export async function readArtifact(context, id, range) {
+  const path = artifactPath(context.layout, context.scopeKey, id);
+  const key = context.artifactKey(id);
+  try {
+    return key ? await readEncrypted(path, key, range) : await readPlaintext(path, range);
+  } catch (error) {
+    // A typed error the package already classified — an unreadable header,
+    // a failing tag — says something more specific than "missing" and must
+    // survive. Anything else reaching here is the file not being there.
+    if (isStorageError(error)) {
+      throw error;
+    }
+    raise(DiagnosticCodes.ATTACHMENT_MISSING, {
+      message: 'artifact is missing',
+      detail: {
+        attachmentId: id
+      },
+      cause: error
+    });
+  }
+}
+
+/**
+ * Collects file removals until the transaction that deleted their references
+ * commits. A file unlinked inside the transaction is gone even if the
+ * transaction then rolls back and the reference returns — a dangling
+ * reference to data nobody can recover.
+ */
+
+export async function removeArtifact(context, id, deferred) {
+  const path = artifactPath(context.layout, context.scopeKey, id);
+  if (deferred) {
+    // Inside a transaction: the reference goes now and rolls back with it;
+    // the file goes once the transaction commits.
+    const hadReference = await deleteReference(context.executor(), id);
+    if (hadReference) {
+      deferred.add(path);
+    }
+    return {
+      removedRecords: 0,
+      removedArtifacts: hadReference ? [id] : [],
+      orphanedReferences: [],
+      failedRemovals: []
+    };
+  }
+  const removed = await removeIfPresent(path);
+  const hadReference = await deleteReference(context.executor(), id);
+  return {
+    removedRecords: 0,
+    removedArtifacts: removed ? [id] : [],
+    // A reference with no file left behind is worth reporting rather than
+    // rounding up to success (FR-071).
+    orphanedReferences: !removed && hadReference ? [id] : [],
+    failedRemovals: []
+  };
+}
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["Budgets","DiagnosticCodes","isStorageError","raise","throwIfFaulted","raiseNative","fileSystem","removeIfPresent","base64ToBytes","bytesToBase64","concatBytes","assertArtifactWithinBudget","HEADER_BYTES","TAG_BYTES","chunkOffset","chunkPlaintextLength","decodeHeader","decryptChunk","encodeHeader","encryptChunk","headerFor","maybeNum","num","text","artifactPath","artifactsDirectory","CREATE_ATTACHMENTS","CREATE_OWNER_INDEX","ensureAttachmentTable","executor","execute","toReference","row","reference","id","contentType","content_type","size","createdAt","created_at","owner_collection","owner_id","owner","collection","chunkSize","chunk_size","chunkCount","chunk_count","readReference","result","rows","listReferences","map","listReferencesFor","insertReference","deleteReference","rowsAffected","writePlaintext","path","content","writeFile","writeEncrypted","key","source","header","ARTIFACT_CHUNK_BYTES","index","chunk","appendFile","sourceFileOf","input","sourcePath","startsWith","slice","length","byteSourceFor","file","CONFIG_INVALID","message","detail","attachmentId","plaintext","offset","subarray","stat","error","operation","read","writeArtifact","context","layout","scopeKey","artifactKey","chunking","mkdir","copyFile","now","readPlaintext","range","readFile","readEncrypted","headerBytes","from","to","Math","min","plaintextSize","first","floor","last","pieces","stored","decrypted","chunkStart","push","max","readArtifact","ATTACHMENT_MISSING","cause","removeArtifact","deferred","hadReference","add","removedRecords","removedArtifacts","orphanedReferences","failedRemovals","removed"],"sourceRoot":"../../../src","sources":["artifacts/store.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AASA,SAASA,OAAO,QAAQ,uBAAoB;AAC5C,SAASC,eAAe,QAAQ,uBAAoB;AACpD,SAASC,cAAc,EAAEC,KAAK,QAAQ,0BAAuB;AAC7D,SAASC,cAAc,QAAQ,0BAAuB;AACtD,SAASC,WAAW,QAAQ,8BAA2B;AACvD,SAASC,UAAU,EAAEC,eAAe,QAAQ,mBAAgB;AAC5D,SAASC,aAAa,EAAEC,aAAa,EAAEC,WAAW,QAAQ,sBAAmB;AAE7E,SAASC,0BAA0B,QAAQ,qBAAkB;AAC7D,SACCC,YAAY,EACZC,SAAS,EACTC,WAAW,EACXC,oBAAoB,EACpBC,YAAY,EACZC,YAAY,EACZC,YAAY,EACZC,YAAY,EACZC,SAAS,QACH,6BAA0B;AAEjC,SAASC,QAAQ,EAAEC,GAAG,EAAEC,IAAI,QAAQ,qBAAkB;AACtD,SAASC,YAAY,EAAEC,kBAAkB,QAAQ,YAAS;AAE1D,MAAMC,kBAAkB,GAAG;AAC3B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAE;AAEF,MAAMC,kBAAkB,GACvB,4FAA4F;AAW7F,OAAO,eAAeC,qBAAqBA,CAACC,QAAkB,EAAiB;EAC9E,MAAMA,QAAQ,CAACC,OAAO,CAACJ,kBAAkB,CAAC;EAC1C,MAAMG,QAAQ,CAACC,OAAO,CAACH,kBAAkB,CAAC;AAC3C;AAEA,SAASI,WAAWA,CAACC,GAA4B,EAAuB;EACvE,MAAMC,SAA8B,GAAG;IACtCC,EAAE,EAAEX,IAAI,CAACS,GAAG,CAACE,EAAE,CAAC;IAChBC,WAAW,EAAEZ,IAAI,CAACS,GAAG,CAACI,YAAY,CAAC;IACnCC,IAAI,EAAEf,GAAG,CAACU,GAAG,CAACK,IAAI,CAAC;IACnBC,SAAS,EAAEhB,GAAG,CAACU,GAAG,CAACO,UAAU;EAC9B,CAAC;EACD,IAAIP,GAAG,CAACQ,gBAAgB,IAAI,IAAI,IAAIR,GAAG,CAACS,QAAQ,IAAI,IAAI,EAAE;IACzDR,SAAS,CAACS,KAAK,GAAG;MAAEC,UAAU,EAAEpB,IAAI,CAACS,GAAG,CAACQ,gBAAgB,CAAC;MAAEN,EAAE,EAAEX,IAAI,CAACS,GAAG,CAACS,QAAQ;IAAE,CAAC;EACrF;EACA,MAAMG,SAAS,GAAGvB,QAAQ,CAACW,GAAG,CAACa,UAAU,CAAC;EAC1C,IAAID,SAAS,KAAK,IAAI,EAAE;IACvBX,SAAS,CAACW,SAAS,GAAGA,SAAS;IAC/BX,SAAS,CAACa,UAAU,GAAGxB,GAAG,CAACU,GAAG,CAACe,WAAW,CAAC;EAC5C;EACA,OAAOd,SAAS;AACjB;AAEA,OAAO,eAAee,aAAaA,CAClCnB,QAAkB,EAClBK,EAAU,EAC4B;EACtC,MAAMe,MAAM,GAAG,MAAMpB,QAAQ,CAACC,OAAO,CAAC,yCAAyC,EAAE,CAACI,EAAE,CAAC,CAAC;EACtF,MAAMF,GAAG,GAAGiB,MAAM,CAACC,IAAI,CAAC,CAAC,CAAC;EAC1B,OAAOlB,GAAG,GAAGD,WAAW,CAACC,GAAG,CAAC,GAAG,IAAI;AACrC;AAEA,OAAO,eAAemB,cAAcA,CAACtB,QAAkB,EAAkC;EACxF,MAAMoB,MAAM,GAAG,MAAMpB,QAAQ,CAACC,OAAO,CAAC,4CAA4C,CAAC;EACnF,OAAOmB,MAAM,CAACC,IAAI,CAACE,GAAG,CAACrB,WAAW,CAAC;AACpC;AAEA,OAAO,eAAesB,iBAAiBA,CACtCxB,QAAkB,EAClBa,KAAsB,EACW;EACjC,MAAMO,MAAM,GAAG,MAAMpB,QAAQ,CAACC,OAAO,CACpC,wFAAwF,EACxF,CAACY,KAAK,CAACC,UAAU,EAAED,KAAK,CAACR,EAAE,CAC5B,CAAC;EACD,OAAOe,MAAM,CAACC,IAAI,CAACE,GAAG,CAACrB,WAAW,CAAC;AACpC;AAEA,eAAeuB,eAAeA,CAACzB,QAAkB,EAAEI,SAA8B,EAAiB;EACjG,MAAMJ,QAAQ,CAACC,OAAO,CACrB;AACF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,sCAAsC,EACpC,CACCG,SAAS,CAACC,EAAE,EACZD,SAAS,CAACS,KAAK,EAAEC,UAAU,IAAI,IAAI,EACnCV,SAAS,CAACS,KAAK,EAAER,EAAE,IAAI,IAAI,EAC3BD,SAAS,CAACE,WAAW,EACrBF,SAAS,CAACI,IAAI,EACdJ,SAAS,CAACW,SAAS,IAAI,IAAI,EAC3BX,SAAS,CAACa,UAAU,IAAI,IAAI,EAC5Bb,SAAS,CAACK,SAAS,CAErB,CAAC;AACF;AAEA,OAAO,eAAeiB,eAAeA,CAAC1B,QAAkB,EAAEK,EAAU,EAAoB;EACvF,MAAMe,MAAM,GAAG,MAAMpB,QAAQ,CAACC,OAAO,CAAC,uCAAuC,EAAE,CAACI,EAAE,CAAC,CAAC;EACpF,OAAOe,MAAM,CAACO,YAAY,GAAG,CAAC;AAC/B;AAEA,eAAeC,cAAcA,CAACC,IAAY,EAAEC,OAAe,EAAiB;EAC3E,MAAMrD,UAAU,CAAC,CAAC,CAACsD,SAAS,CAACF,IAAI,EAAEC,OAAO,EAAE,QAAQ,CAAC;AACtD;;AAEA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,eAAeE,cAAcA,CAC5BH,IAAY,EACZI,GAAe,EACfC,MAAkB,EACmC;EACrD,MAAMC,MAAM,GAAG5C,SAAS,CAAC2C,MAAM,CAAC1B,IAAI,EAAErC,OAAO,CAACiE,oBAAoB,CAAC;EACnE,MAAM3D,UAAU,CAAC,CAAC,CAACsD,SAAS,CAACF,IAAI,EAAEjD,aAAa,CAACS,YAAY,CAAC8C,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC;EAEjF,KAAK,IAAIE,KAAK,GAAG,CAAC,EAAEA,KAAK,GAAGF,MAAM,CAAClB,UAAU,EAAEoB,KAAK,IAAI,CAAC,EAAE;IAC1D,MAAMC,KAAK,GAAG,MAAMJ,MAAM,CAACI,KAAK,CAACD,KAAK,GAAGF,MAAM,CAACpB,SAAS,EAAE7B,oBAAoB,CAACiD,MAAM,EAAEE,KAAK,CAAC,CAAC;IAC/F,MAAM5D,UAAU,CAAC,CAAC,CAAC8D,UAAU,CAACV,IAAI,EAAEjD,aAAa,CAACU,YAAY,CAAC2C,GAAG,EAAEI,KAAK,EAAEC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;EAC9F;EAEA,OAAO;IAAEvB,SAAS,EAAEoB,MAAM,CAACpB,SAAS;IAAEE,UAAU,EAAEkB,MAAM,CAAClB;EAAW,CAAC;AACtE;AAEA,SAASuB,YAAYA,CAACC,KAAsB,EAAiB;EAC5D,IAAI,OAAOA,KAAK,CAACC,UAAU,KAAK,QAAQ,EAAE;IACzC,OAAO,IAAI;EACZ;EACA,OAAOD,KAAK,CAACC,UAAU,CAACC,UAAU,CAAC,SAAS,CAAC,GAC1CF,KAAK,CAACC,UAAU,CAACE,KAAK,CAAC,SAAS,CAACC,MAAM,CAAC,GACxCJ,KAAK,CAACC,UAAU;AACpB;;AAEA;AACA;AACA;AACA;AACA;AACA,eAAeI,aAAaA,CAACL,KAAsB,EAAuB;EACzE,MAAMM,IAAI,GAAGP,YAAY,CAACC,KAAK,CAAC;EAChC,IAAIM,IAAI,KAAK,IAAI,EAAE;IAClB,IAAI,OAAON,KAAK,CAACX,OAAO,KAAK,QAAQ,EAAE;MACtCxD,KAAK,CAACF,eAAe,CAAC4E,cAAc,EAAE;QACrCC,OAAO,EAAE,2CAA2C;QACpDC,MAAM,EAAE;UAAEC,YAAY,EAAEV,KAAK,CAACpC;QAAG;MAClC,CAAC,CAAC;IACH;IACA,MAAM+C,SAAS,GAAGzE,aAAa,CAAC8D,KAAK,CAACX,OAAO,CAAC;IAC9C,OAAO;MACNtB,IAAI,EAAE4C,SAAS,CAACP,MAAM;MACtBP,KAAK,EAAE,MAAAA,CAAOe,MAAM,EAAER,MAAM,KAAKO,SAAS,CAACE,QAAQ,CAACD,MAAM,EAAEA,MAAM,GAAGR,MAAM;IAC5E,CAAC;EACF;EACA,IAAIrC,IAAY;EAChB,IAAI;IACHA,IAAI,GAAG,CAAC,MAAM/B,UAAU,CAAC,CAAC,CAAC8E,IAAI,CAACR,IAAI,CAAC,EAAEvC,IAAI;EAC5C,CAAC,CAAC,OAAOgD,KAAK,EAAE;IACfhF,WAAW,CAACgF,KAAK,EAAE;MAAEC,SAAS,EAAE;IAAa,CAAC,CAAC;EAChD;EACA,OAAO;IACNjD,IAAI;IACJ8B,KAAK,EAAE,MAAAA,CAAOe,MAAM,EAAER,MAAM,KAC3BlE,aAAa,CAAC,MAAMF,UAAU,CAAC,CAAC,CAACiF,IAAI,CAACX,IAAI,EAAEF,MAAM,EAAEQ,MAAM,EAAE,QAAQ,CAAC;EACvE,CAAC;AACF;AAEA,OAAO,eAAeM,aAAaA,CAClCC,OAAwB,EACxBnB,KAAsB,EACS;EAC/BlE,cAAc,CAAC,iBAAiB,CAAC;EACjC,MAAM2D,MAAM,GAAG,MAAMY,aAAa,CAACL,KAAK,CAAC;EACzC3D,0BAA0B,CAAC2D,KAAK,CAACpC,EAAE,EAAE6B,MAAM,CAAC1B,IAAI,CAAC;EAEjD,MAAMqB,IAAI,GAAGlC,YAAY,CAACiE,OAAO,CAACC,MAAM,EAAED,OAAO,CAACE,QAAQ,EAAErB,KAAK,CAACpC,EAAE,CAAC;EACrE,MAAM4B,GAAG,GAAG2B,OAAO,CAACG,WAAW,CAACtB,KAAK,CAACpC,EAAE,CAAC;EACzC,MAAM0C,IAAI,GAAGP,YAAY,CAACC,KAAK,CAAC;EAEhC,IAAIuB,QAA+D;EACnE,IAAI;IACH,MAAMvF,UAAU,CAAC,CAAC,CAACwF,KAAK,CAACrE,kBAAkB,CAACgE,OAAO,CAACC,MAAM,EAAED,OAAO,CAACE,QAAQ,CAAC,CAAC;IAC9E,IAAI7B,GAAG,EAAE;MACR+B,QAAQ,GAAG,MAAMhC,cAAc,CAACH,IAAI,EAAEI,GAAG,EAAEC,MAAM,CAAC;IACnD,CAAC,MAAM,IAAIa,IAAI,KAAK,IAAI,EAAE;MACzB,MAAMtE,UAAU,CAAC,CAAC,CAACyF,QAAQ,CAACnB,IAAI,EAAElB,IAAI,CAAC;IACxC,CAAC,MAAM;MACN,MAAMD,cAAc,CAACC,IAAI,EAAEY,KAAK,CAACX,OAAiB,CAAC;IACpD;EACD,CAAC,CAAC,OAAO0B,KAAK,EAAE;IACf;IACA;IACA,MAAM9E,eAAe,CAACmD,IAAI,CAAC;IAC3BrD,WAAW,CAACgF,KAAK,EAAE;MAAEC,SAAS,EAAE;IAAa,CAAC,CAAC;EAChD;EAEA,MAAMrD,SAA8B,GAAG;IACtCC,EAAE,EAAEoC,KAAK,CAACpC,EAAE;IACZC,WAAW,EAAEmC,KAAK,CAACnC,WAAW;IAC9BE,IAAI,EAAE0B,MAAM,CAAC1B,IAAI;IACjBC,SAAS,EAAEmD,OAAO,CAACO,GAAG,CAAC;EACxB,CAAC;EACD,IAAI1B,KAAK,CAAC5B,KAAK,EAAE;IAChBT,SAAS,CAACS,KAAK,GAAG4B,KAAK,CAAC5B,KAAK;EAC9B;EACA,IAAImD,QAAQ,EAAE;IACb5D,SAAS,CAACW,SAAS,GAAGiD,QAAQ,CAACjD,SAAS;IACxCX,SAAS,CAACa,UAAU,GAAG+C,QAAQ,CAAC/C,UAAU;EAC3C;;EAEA;EACA,MAAMQ,eAAe,CAACmC,OAAO,CAAC5D,QAAQ,CAAC,CAAC,EAAEI,SAAS,CAAC;EACpD,OAAOA,SAAS;AACjB;AAEA,eAAegE,aAAaA,CAACvC,IAAY,EAAEwC,KAAiB,EAAmB;EAC9E,IAAI,CAACA,KAAK,EAAE;IACX,OAAO5F,UAAU,CAAC,CAAC,CAAC6F,QAAQ,CAACzC,IAAI,EAAE,QAAQ,CAAC;EAC7C;EACA,OAAOpD,UAAU,CAAC,CAAC,CAACiF,IAAI,CAAC7B,IAAI,EAAEwC,KAAK,CAACxB,MAAM,EAAEwB,KAAK,CAAChB,MAAM,EAAE,QAAQ,CAAC;AACrE;AAEA,eAAekB,aAAaA,CAAC1C,IAAY,EAAEI,GAAe,EAAEoC,KAAiB,EAAmB;EAC/F,MAAMG,WAAW,GAAG7F,aAAa,CAAC,MAAMF,UAAU,CAAC,CAAC,CAACiF,IAAI,CAAC7B,IAAI,EAAE9C,YAAY,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;EAC3F,MAAMoD,MAAM,GAAGhD,YAAY,CAACqF,WAAW,CAAC;EAExC,MAAMC,IAAI,GAAGJ,KAAK,EAAEhB,MAAM,IAAI,CAAC;EAC/B,MAAMqB,EAAE,GAAGL,KAAK,GAAGM,IAAI,CAACC,GAAG,CAACzC,MAAM,CAAC0C,aAAa,EAAEJ,IAAI,GAAGJ,KAAK,CAACxB,MAAM,CAAC,GAAGV,MAAM,CAAC0C,aAAa;EAC7F,IAAIH,EAAE,IAAID,IAAI,EAAE;IACf,OAAO,EAAE;EACV;EAEA,MAAMK,KAAK,GAAGH,IAAI,CAACI,KAAK,CAACN,IAAI,GAAGtC,MAAM,CAACpB,SAAS,CAAC;EACjD,MAAMiE,IAAI,GAAGL,IAAI,CAACI,KAAK,CAAC,CAACL,EAAE,GAAG,CAAC,IAAIvC,MAAM,CAACpB,SAAS,CAAC;EACpD,MAAMkE,MAAoB,GAAG,EAAE;EAE/B,KAAK,IAAI5C,KAAK,GAAGyC,KAAK,EAAEzC,KAAK,IAAI2C,IAAI,EAAE3C,KAAK,IAAI,CAAC,EAAE;IAClD,MAAM6C,MAAM,GAAGvG,aAAa,CAC3B,MAAMF,UAAU,CAAC,CAAC,CAACiF,IAAI,CACtB7B,IAAI,EACJ3C,oBAAoB,CAACiD,MAAM,EAAEE,KAAK,CAAC,GAAGrD,SAAS,EAC/CC,WAAW,CAACkD,MAAM,EAAEE,KAAK,CAAC,EAC1B,QACD,CACD,CAAC;IACD,MAAM8C,SAAS,GAAG/F,YAAY,CAAC6C,GAAG,EAAEI,KAAK,EAAE6C,MAAM,CAAC;IAClD,MAAME,UAAU,GAAG/C,KAAK,GAAGF,MAAM,CAACpB,SAAS;IAC3CkE,MAAM,CAACI,IAAI,CACVF,SAAS,CAAC7B,QAAQ,CACjBqB,IAAI,CAACW,GAAG,CAAC,CAAC,EAAEb,IAAI,GAAGW,UAAU,CAAC,EAC9BT,IAAI,CAACC,GAAG,CAACO,SAAS,CAACtC,MAAM,EAAE6B,EAAE,GAAGU,UAAU,CAC3C,CACD,CAAC;EACF;EAEA,OAAOxG,aAAa,CAACC,WAAW,CAACoG,MAAM,CAAC,CAAC;AAC1C;AAEA,OAAO,eAAeM,YAAYA,CACjC3B,OAAwB,EACxBvD,EAAU,EACVgE,KAAiB,EACC;EAClB,MAAMxC,IAAI,GAAGlC,YAAY,CAACiE,OAAO,CAACC,MAAM,EAAED,OAAO,CAACE,QAAQ,EAAEzD,EAAE,CAAC;EAC/D,MAAM4B,GAAG,GAAG2B,OAAO,CAACG,WAAW,CAAC1D,EAAE,CAAC;EACnC,IAAI;IACH,OAAO4B,GAAG,GAAG,MAAMsC,aAAa,CAAC1C,IAAI,EAAEI,GAAG,EAAEoC,KAAK,CAAC,GAAG,MAAMD,aAAa,CAACvC,IAAI,EAAEwC,KAAK,CAAC;EACtF,CAAC,CAAC,OAAOb,KAAK,EAAE;IACf;IACA;IACA;IACA,IAAInF,cAAc,CAACmF,KAAK,CAAC,EAAE;MAC1B,MAAMA,KAAK;IACZ;IACAlF,KAAK,CAACF,eAAe,CAACoH,kBAAkB,EAAE;MACzCvC,OAAO,EAAE,qBAAqB;MAC9BC,MAAM,EAAE;QAAEC,YAAY,EAAE9C;MAAG,CAAC;MAC5BoF,KAAK,EAAEjC;IACR,CAAC,CAAC;EACH;AACD;;AAEA;AACA;AACA;AACA;AACA;AACA;;AAKA,OAAO,eAAekC,cAAcA,CACnC9B,OAAwB,EACxBvD,EAAU,EACVsF,QAA0B,EACC;EAC3B,MAAM9D,IAAI,GAAGlC,YAAY,CAACiE,OAAO,CAACC,MAAM,EAAED,OAAO,CAACE,QAAQ,EAAEzD,EAAE,CAAC;EAC/D,IAAIsF,QAAQ,EAAE;IACb;IACA;IACA,MAAMC,YAAY,GAAG,MAAMlE,eAAe,CAACkC,OAAO,CAAC5D,QAAQ,CAAC,CAAC,EAAEK,EAAE,CAAC;IAClE,IAAIuF,YAAY,EAAE;MACjBD,QAAQ,CAACE,GAAG,CAAChE,IAAI,CAAC;IACnB;IACA,OAAO;MACNiE,cAAc,EAAE,CAAC;MACjBC,gBAAgB,EAAEH,YAAY,GAAG,CAACvF,EAAE,CAAC,GAAG,EAAE;MAC1C2F,kBAAkB,EAAE,EAAE;MACtBC,cAAc,EAAE;IACjB,CAAC;EACF;EACA,MAAMC,OAAO,GAAG,MAAMxH,eAAe,CAACmD,IAAI,CAAC;EAC3C,MAAM+D,YAAY,GAAG,MAAMlE,eAAe,CAACkC,OAAO,CAAC5D,QAAQ,CAAC,CAAC,EAAEK,EAAE,CAAC;EAElE,OAAO;IACNyF,cAAc,EAAE,CAAC;IACjBC,gBAAgB,EAAEG,OAAO,GAAG,CAAC7F,EAAE,CAAC,GAAG,EAAE;IACrC;IACA;IACA2F,kBAAkB,EAAE,CAACE,OAAO,IAAIN,YAAY,GAAG,CAACvF,EAAE,CAAC,GAAG,EAAE;IACxD4F,cAAc,EAAE;EACjB,CAAC;AACF","ignoreList":[]}

package/lib/module/contract/adapter.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=adapter.js.map

package/lib/module/contract/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/adapter.ts"],"mappings":"","ignoreList":[]}

package/lib/module/contract/attachment.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=attachment.js.map

package/lib/module/contract/attachment.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/attachment.ts"],"mappings":"","ignoreList":[]}

package/lib/module/contract/backup.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=backup.js.map

package/lib/module/contract/backup.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/backup.ts"],"mappings":"","ignoreList":[]}

package/lib/module/contract/config.js

@@ -0,0 +1,27 @@
+"use strict";
+
+/**
+ * Database configuration: everything an app supplies at open time.
+ *
+ * Immutable for the handle's lifetime. Scope in particular is bound here and
+ * never changes (FR-008a) — there is no switchScope, and no operation takes a
+ * scope argument, which is what makes cross-scope leakage inexpressible
+ * rather than merely prevented.
+ */
+
+/** Phase-one budgets (FR-088). Confirmed against the harness during validation. */
+export const Budgets = {
+  MAX_RECORDS_PER_COLLECTION: 100_000,
+  MAX_RECORD_BYTES: 256 * 1024,
+  MAX_BATCH_OPERATIONS: 1_000,
+  MAX_PAGE_SIZE: 500,
+  MAX_COLLECTIONS_PER_DATABASE: 50,
+  MAX_ATTACHMENT_REFERENCES_PER_SCOPE: 50_000,
+  MAX_ARTIFACT_BYTES: 100 * 1024 * 1024,
+  MAX_OPEN_HANDLES: 8,
+  /** Plaintext chunk size for encrypted artifacts (research.md R4). */
+  ARTIFACT_CHUNK_BYTES: 256 * 1024
+};
+
+/** Names a scope for the operations that legitimately need to (FR-059). */
+//# sourceMappingURL=config.js.map

package/lib/module/contract/config.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Budgets","MAX_RECORDS_PER_COLLECTION","MAX_RECORD_BYTES","MAX_BATCH_OPERATIONS","MAX_PAGE_SIZE","MAX_COLLECTIONS_PER_DATABASE","MAX_ATTACHMENT_REFERENCES_PER_SCOPE","MAX_ARTIFACT_BYTES","MAX_OPEN_HANDLES","ARTIFACT_CHUNK_BYTES"],"sourceRoot":"../../../src","sources":["contract/config.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA,OAAO,MAAMA,OAAO,GAAG;EACtBC,0BAA0B,EAAE,OAAO;EACnCC,gBAAgB,EAAE,GAAG,GAAG,IAAI;EAC5BC,oBAAoB,EAAE,KAAK;EAC3BC,aAAa,EAAE,GAAG;EAClBC,4BAA4B,EAAE,EAAE;EAChCC,mCAAmC,EAAE,MAAM;EAC3CC,kBAAkB,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;EACrCC,gBAAgB,EAAE,CAAC;EACnB;EACAC,oBAAoB,EAAE,GAAG,GAAG;AAC7B,CAAU;;AAiBV","ignoreList":[]}

package/lib/module/contract/encryption.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=encryption.js.map

package/lib/module/contract/encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/encryption.ts"],"mappings":"","ignoreList":[]}

package/lib/module/contract/errors.js

@@ -0,0 +1,60 @@
+"use strict";
+
+/**
+ * Diagnostic codes.
+ *
+ * Stable identifiers so an app can choose a response without parsing a
+ * message (FR-074, FR-082). Disk-full, filesystem-access, and corruption stay
+ * distinct rather than collapsing into a generic write failure (FR-076) —
+ * an app frees space for one, retries after unlock for another, and offers a
+ * reset for the third.
+ *
+ * Full table with recommended recovery per code:
+ * specs/008-rn-local-db-package/contracts/errors.md
+ */
+
+export const DiagnosticCodes = {
+  // Configuration and scope
+  CONFIG_INVALID: 'CONFIG_INVALID',
+  INVALID_SCOPE: 'INVALID_SCOPE',
+  MIGRATION_CONFIG_INVALID: 'MIGRATION_CONFIG_INVALID',
+  // Open and lifecycle
+  OPEN_FAILED: 'OPEN_FAILED',
+  CLOSED_HANDLE: 'CLOSED_HANDLE',
+  SCOPE_DELETED: 'SCOPE_DELETED',
+  CORRUPTION: 'CORRUPTION',
+  STORAGE_ACCESS: 'STORAGE_ACCESS',
+  // Migration
+  MIGRATION_FAILED: 'MIGRATION_FAILED',
+  SCHEMA_DOWNGRADE: 'SCHEMA_DOWNGRADE',
+  // Records and writes
+  RECORD_NOT_FOUND: 'RECORD_NOT_FOUND',
+  RECORD_CONFLICT: 'RECORD_CONFLICT',
+  RECORD_TOO_LARGE: 'RECORD_TOO_LARGE',
+  BATCH_TOO_LARGE: 'BATCH_TOO_LARGE',
+  DISK_FULL: 'DISK_FULL',
+  WRITE_FAILED: 'WRITE_FAILED',
+  // Query
+  QUERY_INVALID: 'QUERY_INVALID',
+  PAGE_SIZE_INVALID: 'PAGE_SIZE_INVALID',
+  CURSOR_INVALID: 'CURSOR_INVALID',
+  // Transaction
+  TRANSACTION_FAILED: 'TRANSACTION_FAILED',
+  TRANSACTION_STATE: 'TRANSACTION_STATE',
+  // Attachments
+  ATTACHMENT_MISSING: 'ATTACHMENT_MISSING',
+  ATTACHMENT_OUT_OF_BOUNDS: 'ATTACHMENT_OUT_OF_BOUNDS',
+  ATTACHMENT_WRITE_FAILED: 'ATTACHMENT_WRITE_FAILED',
+  ATTACHMENT_UNDECRYPTABLE: 'ATTACHMENT_UNDECRYPTABLE',
+  // Encryption
+  KEY_INVALID: 'KEY_INVALID',
+  KEY_PROVIDER_FAILED: 'KEY_PROVIDER_FAILED',
+  ENCRYPTION_MISMATCH: 'ENCRYPTION_MISMATCH',
+  ENCRYPTION_UNAVAILABLE: 'ENCRYPTION_UNAVAILABLE'
+};
+/**
+ * Codes worth retrying. `KEY_PROVIDER_FAILED` is here because a locked device
+ * is an expected condition, not a bug (FR-102).
+ */
+export const RETRYABLE_CODES = new Set([DiagnosticCodes.OPEN_FAILED, DiagnosticCodes.DISK_FULL, DiagnosticCodes.WRITE_FAILED, DiagnosticCodes.STORAGE_ACCESS, DiagnosticCodes.TRANSACTION_FAILED, DiagnosticCodes.MIGRATION_FAILED, DiagnosticCodes.ATTACHMENT_WRITE_FAILED, DiagnosticCodes.KEY_PROVIDER_FAILED]);
+//# sourceMappingURL=errors.js.map

package/lib/module/contract/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["DiagnosticCodes","CONFIG_INVALID","INVALID_SCOPE","MIGRATION_CONFIG_INVALID","OPEN_FAILED","CLOSED_HANDLE","SCOPE_DELETED","CORRUPTION","STORAGE_ACCESS","MIGRATION_FAILED","SCHEMA_DOWNGRADE","RECORD_NOT_FOUND","RECORD_CONFLICT","RECORD_TOO_LARGE","BATCH_TOO_LARGE","DISK_FULL","WRITE_FAILED","QUERY_INVALID","PAGE_SIZE_INVALID","CURSOR_INVALID","TRANSACTION_FAILED","TRANSACTION_STATE","ATTACHMENT_MISSING","ATTACHMENT_OUT_OF_BOUNDS","ATTACHMENT_WRITE_FAILED","ATTACHMENT_UNDECRYPTABLE","KEY_INVALID","KEY_PROVIDER_FAILED","ENCRYPTION_MISMATCH","ENCRYPTION_UNAVAILABLE","RETRYABLE_CODES","Set"],"sourceRoot":"../../../src","sources":["contract/errors.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,OAAO,MAAMA,eAAe,GAAG;EAC9B;EACAC,cAAc,EAAE,gBAAgB;EAChCC,aAAa,EAAE,eAAe;EAC9BC,wBAAwB,EAAE,0BAA0B;EAEpD;EACAC,WAAW,EAAE,aAAa;EAC1BC,aAAa,EAAE,eAAe;EAC9BC,aAAa,EAAE,eAAe;EAC9BC,UAAU,EAAE,YAAY;EACxBC,cAAc,EAAE,gBAAgB;EAEhC;EACAC,gBAAgB,EAAE,kBAAkB;EACpCC,gBAAgB,EAAE,kBAAkB;EAEpC;EACAC,gBAAgB,EAAE,kBAAkB;EACpCC,eAAe,EAAE,iBAAiB;EAClCC,gBAAgB,EAAE,kBAAkB;EACpCC,eAAe,EAAE,iBAAiB;EAClCC,SAAS,EAAE,WAAW;EACtBC,YAAY,EAAE,cAAc;EAE5B;EACAC,aAAa,EAAE,eAAe;EAC9BC,iBAAiB,EAAE,mBAAmB;EACtCC,cAAc,EAAE,gBAAgB;EAEhC;EACAC,kBAAkB,EAAE,oBAAoB;EACxCC,iBAAiB,EAAE,mBAAmB;EAEtC;EACAC,kBAAkB,EAAE,oBAAoB;EACxCC,wBAAwB,EAAE,0BAA0B;EACpDC,uBAAuB,EAAE,yBAAyB;EAClDC,wBAAwB,EAAE,0BAA0B;EAEpD;EACAC,WAAW,EAAE,aAAa;EAC1BC,mBAAmB,EAAE,qBAAqB;EAC1CC,mBAAmB,EAAE,qBAAqB;EAC1CC,sBAAsB,EAAE;AACzB,CAAU;AAIV;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAA4C,GAAG,IAAIC,GAAG,CAAiB,CACnF/B,eAAe,CAACI,WAAW,EAC3BJ,eAAe,CAACe,SAAS,EACzBf,eAAe,CAACgB,YAAY,EAC5BhB,eAAe,CAACQ,cAAc,EAC9BR,eAAe,CAACoB,kBAAkB,EAClCpB,eAAe,CAACS,gBAAgB,EAChCT,eAAe,CAACwB,uBAAuB,EACvCxB,eAAe,CAAC2B,mBAAmB,CACnC,CAAC","ignoreList":[]}

package/lib/module/contract/migration.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=migration.js.map

package/lib/module/contract/migration.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/migration.ts"],"mappings":"","ignoreList":[]}

package/lib/module/contract/query.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=query.js.map

package/lib/module/contract/query.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/query.ts"],"mappings":"","ignoreList":[]}

package/lib/module/contract/record.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=record.js.map

package/lib/module/contract/record.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/record.ts"],"mappings":"","ignoreList":[]}

package/lib/module/contract/schema.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=schema.js.map

package/lib/module/contract/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/schema.ts"],"mappings":"","ignoreList":[]}

package/lib/module/contract/scope.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=scope.js.map

package/lib/module/contract/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/scope.ts"],"mappings":"","ignoreList":[]}

package/lib/module/contract/transaction.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=transaction.js.map

package/lib/module/contract/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["contract/transaction.ts"],"mappings":"","ignoreList":[]}

package/lib/module/crypto/chunked-cipher.js

@@ -0,0 +1,134 @@
+"use strict";
+
+/**
+ * The chunked AES-256-GCM artifact format.
+ *
+ * Whole-file encryption was rejected because a 100 MB artifact would have to
+ * be held in memory twice — plaintext and ciphertext — which breaks FR-107a's
+ * flat memory bound and every PERF-001 budget along with it (research.md R4).
+ * Chunking keeps exactly one 256 KB chunk in flight regardless of artifact
+ * size.
+ *
+ * ```text
+ * [ header 22 bytes ] magic | format version | chunk size | chunk count | plaintext size
+ * [ chunk 0 ] ciphertext(≤ chunkSize) | auth tag (16)
+ * [ chunk 1 ] …
+ * ```
+ *
+ * The auth tag follows each chunk rather than sitting in the header, which is
+ * a deliberate departure from the sketch in storage-layout.md. A tag is only
+ * known after its chunk has been encrypted, and the filesystem peer appends —
+ * it cannot seek back to patch a header. Collecting every tag before writing
+ * anything would mean buffering the whole ciphertext, which is the thing this
+ * format exists to avoid. Inline tags keep the write append-only and leave
+ * every chunk at a computable offset.
+ *
+ * A failing tag on read is `ATTACHMENT_UNDECRYPTABLE`, deliberately distinct
+ * from `ATTACHMENT_MISSING` (FR-107c): one is a wrong key or a tampered file
+ * and may be recoverable, the other is data that is simply gone.
+ */
+
+import { Budgets } from "../contract/config.js";
+import { DiagnosticCodes } from "../contract/errors.js";
+import { raise } from "../diagnostics/errors.js";
+import { nonceForChunk } from "./derive.js";
+import { cipherModule } from "./provider.js";
+import { asciiAt, concatBytes } from "../platform/bytes.js";
+export const MAGIC = 'LDB1';
+export const FORMAT_VERSION = 1;
+export const HEADER_BYTES = 22;
+export const TAG_BYTES = 16;
+export const ALGORITHM = 'aes-256-gcm';
+export function chunkCountFor(plaintextSize, chunkSize) {
+  return plaintextSize === 0 ? 0 : Math.ceil(plaintextSize / chunkSize);
+}
+export function encodeHeader(header) {
+  const bytes = new Uint8Array(HEADER_BYTES);
+  for (let index = 0; index < 4; index += 1) {
+    bytes[index] = MAGIC.charCodeAt(index);
+  }
+  // Big-endian, as DataView writes by default; the on-disk format is unchanged.
+  const view = new DataView(bytes.buffer);
+  view.setUint16(4, header.formatVersion);
+  view.setUint32(6, header.chunkSize);
+  view.setUint32(10, header.chunkCount);
+  // Split across two 32-bit writes: artifact sizes stay well inside the safe
+  // integer range, and this avoids depending on BigInt in Hermes.
+  view.setUint32(14, Math.floor(header.plaintextSize / 0x100000000));
+  view.setUint32(18, header.plaintextSize % 0x100000000);
+  return bytes;
+}
+export function decodeHeader(bytes) {
+  if (bytes.length < HEADER_BYTES || asciiAt(bytes, 0, 4) !== MAGIC) {
+    raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
+      message: 'artifact header is not a recognised encrypted artifact'
+    });
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, HEADER_BYTES);
+  return {
+    formatVersion: view.getUint16(4),
+    chunkSize: view.getUint32(6),
+    chunkCount: view.getUint32(10),
+    plaintextSize: view.getUint32(14) * 0x100000000 + view.getUint32(18)
+  };
+}
+
+/** Plaintext length of chunk `index`; the last one is usually short. */
+export function chunkPlaintextLength(header, index) {
+  const start = index * header.chunkSize;
+  return Math.max(0, Math.min(header.chunkSize, header.plaintextSize - start));
+}
+
+/**
+ * Byte offset of chunk `index` in the file.
+ *
+ * Every chunk but the last is full, so the offset is arithmetic rather than a
+ * table lookup — which is what lets a range read seek straight to the chunk
+ * it needs instead of walking the file.
+ */
+export function chunkOffset(header, index) {
+  return HEADER_BYTES + index * (header.chunkSize + TAG_BYTES);
+}
+export function encryptedLength(header) {
+  if (header.chunkCount === 0) {
+    return HEADER_BYTES;
+  }
+  const lastIndex = header.chunkCount - 1;
+  return chunkOffset(header, lastIndex) + chunkPlaintextLength(header, lastIndex) + TAG_BYTES;
+}
+
+/** One chunk in, ciphertext with its tag appended out. */
+export function encryptChunk(key, index, plaintext) {
+  const cipher = cipherModule().createCipheriv(ALGORITHM, key, nonceForChunk(index));
+  return concatBytes([new Uint8Array(cipher.update(plaintext)), new Uint8Array(cipher.final()), new Uint8Array(cipher.getAuthTag())]);
+}
+export function decryptChunk(key, index, stored) {
+  if (stored.length < TAG_BYTES) {
+    raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
+      message: 'artifact chunk is truncated'
+    });
+  }
+  const body = stored.subarray(0, stored.length - TAG_BYTES);
+  const tag = stored.subarray(stored.length - TAG_BYTES);
+  const decipher = cipherModule().createDecipheriv(ALGORITHM, key, nonceForChunk(index));
+  decipher.setAuthTag(tag);
+  try {
+    return concatBytes([new Uint8Array(decipher.update(body)), new Uint8Array(decipher.final())]);
+  } catch (error) {
+    // A failing tag is the only signal that separates "exists but will not
+    // decrypt" from "missing", and an app responds to them differently.
+    raise(DiagnosticCodes.ATTACHMENT_UNDECRYPTABLE, {
+      message: 'artifact chunk failed authentication',
+      cause: error
+    });
+  }
+}
+export function headerFor(plaintextSize, chunkSize = Budgets.ARTIFACT_CHUNK_BYTES) {
+  return {
+    formatVersion: FORMAT_VERSION,
+    chunkSize,
+    chunkCount: chunkCountFor(plaintextSize, chunkSize),
+    plaintextSize
+  };
+}
+//# sourceMappingURL=chunked-cipher.js.map

package/lib/module/crypto/chunked-cipher.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Budgets","DiagnosticCodes","raise","nonceForChunk","cipherModule","asciiAt","concatBytes","MAGIC","FORMAT_VERSION","HEADER_BYTES","TAG_BYTES","ALGORITHM","chunkCountFor","plaintextSize","chunkSize","Math","ceil","encodeHeader","header","bytes","Uint8Array","index","charCodeAt","view","DataView","buffer","setUint16","formatVersion","setUint32","chunkCount","floor","decodeHeader","length","ATTACHMENT_UNDECRYPTABLE","message","byteOffset","getUint16","getUint32","chunkPlaintextLength","start","max","min","chunkOffset","encryptedLength","lastIndex","encryptChunk","key","plaintext","cipher","createCipheriv","update","final","getAuthTag","decryptChunk","stored","body","subarray","tag","decipher","createDecipheriv","setAuthTag","error","cause","headerFor","ARTIFACT_CHUNK_BYTES"],"sourceRoot":"../../../src","sources":["crypto/chunked-cipher.ts"],"mappings":"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","ignoreList":[]}