@forgezero/runtime 0.1.3 → 0.1.5

package/README.md

@@ -5,7 +5,7 @@ themselves, keyed queues, a transactional outbox, a hash-chained audit trail,
 templated mail, encrypted backups, schema validation, and money that is never a
 floating-point number.
 
-Thirty-three public modules. Each is its own entry point, so you install one package and
+Thirty-four public modules. Each is its own entry point, so you install one package and
 your bundler includes only what you imported.
 
 ```bash
@@ -24,7 +24,7 @@ import { createScheduler } from '@forgezero/runtime/jobs';
 
 | | |
 |---|---|
-| **Spine** | `jobs` `queue` `outbox` |
+| **Spine** | `query` `jobs` `queue` `outbox` |
 | **Record** | `audit` `backup` `compliance` `calendar` |
 | **Identity** | `identity` `totp` `notify` `notify/templates` `schema` `schema/typebox` |
 | **Finance** | `finance/money` `finance/storage` `finance/ledger` `finance/commission` `finance/rates` `finance/transfers` `finance/tax` `finance/chain` `finance/custody` `finance/derive` `finance/venues` `finance/binance` |
@@ -32,6 +32,28 @@ import { createScheduler } from '@forgezero/runtime/jobs';
 None of it knows what your product does. You bind your own rules to these; you
 do not fork them.
 
+## Typed function queries
+
+`query` binds typed input/output codecs to an ordinary function and any context
+you choose. It has no database or ForgeZero realm dependency. Inputs may decode
+wire values; outputs are checked strictly so a wrong handler result cannot be
+coerced into looking correct.
+
+```ts
+import { defineQuery, implementQuery } from '@forgezero/runtime/query';
+import { typeboxQueryCodec, T } from '@forgezero/runtime/schema/typebox';
+
+const contract = defineQuery({
+  name: 'invoice.by-reference',
+  input: typeboxQueryCodec(T.Object({ reference: T.String() })),
+  output: typeboxQueryCodec(T.Object({ total: T.String() }))
+});
+
+const findInvoice = implementQuery(contract, async (services: MyServices, input, { signal }) =>
+  services.invoices.find(input.reference, { signal })
+);
+```
+
 ## One reusable async queue
 
 `queue` is deliberately memory-only: it accepts a function, returns that
@@ -43,7 +65,9 @@ ArangoDB unique claim, while another caller may use any database or no database.
 ```ts
 import { createQueue } from '@forgezero/runtime/queue';
 
-const queue = createQueue({ width: 8 });
+// Default admission is 60% of reported logical CPUs (with one reserved).
+// Use `width` for an exact ceiling, or an explicit dynamic resource policy:
+const queue = createQueue({ resources: { percent: 60, reserve: 1, max: 32 } });
 const task = queue.run('tenant-a:wallet-7', transfer, amount, destination);
 const receipt = await task.result;
 
@@ -55,6 +79,25 @@ queue.cancel(task.id);               // pending task only
 await queue.stop(30_000);            // close intake and drain all work
 ```
 
+Different async keys overlap immediately. CPU-heavy JavaScript does not become
+multi-core merely by entering a queue: put that handler in Bun/standard Workers
+and await the Worker result from the queue.
+
+Jobs accept intervals down to seconds or a local wall-clock schedule with an
+IANA timezone and weekday filter. `overlap: 'wait'` (the default) schedules the
+next run after completion; `overlap: 'skip'` keeps clock cadence and drops a tick
+when the same key is still busy. Same-key overlap is never allowed.
+
+```ts
+defineJob({
+  key: 'tenant:acme:invoice',
+  label: 'Monthly invoice preparation',
+  schedule: { timezone: 'Asia/Kolkata', time: '00:00:15', weekdays: [1] },
+  overlap: 'skip',
+  run: async ({ signal }) => generateInvoices({ signal })
+});
+```
+
 ## Three things worth knowing before you use it
 
 **Money is never a number.** An amount is minor units as a `bigint` with its

package/dist/audit.js

@@ -33,10 +33,41 @@ var DEFAULT_RETRY = {
   attempts: 1,
   backoffMs: (attempt) => Math.min(30000, 2 ** attempt * 100)
 };
+var reportedParallelism = () => {
+  const reported = globalThis.navigator?.hardwareConcurrency;
+  return Number.isSafeInteger(reported) && reported > 0 ? reported : 1;
+};
+function queueWidthFor(policy = {}) {
+  const percent = policy.percent ?? 60;
+  const reserve = policy.reserve ?? 1;
+  const min = policy.min ?? 1;
+  const max = policy.max ?? Number.MAX_SAFE_INTEGER;
+  const available = (policy.available ?? reportedParallelism)();
+  if (!Number.isFinite(percent) || percent <= 0 || percent > 100) {
+    throw new RangeError("queue: resource percent must be greater than 0 and at most 100");
+  }
+  for (const [name, value] of [["reserve", reserve], ["min", min], ["max", max]]) {
+    if (!Number.isSafeInteger(value) || value < (name === "reserve" ? 0 : 1)) {
+      throw new RangeError(`queue: resource ${name} must be ${name === "reserve" ? "a non-negative" : "a positive"} integer`);
+    }
+  }
+  if (!Number.isSafeInteger(available) || available < 1) {
+    throw new RangeError("queue: available parallelism must be a positive integer");
+  }
+  if (min > max)
+    throw new RangeError("queue: resource min cannot exceed max");
+  const usable = Math.max(1, available - reserve);
+  return Math.min(max, Math.max(min, Math.floor(usable * percent / 100)));
+}
 function createQueue(options = {}) {
-  const width = options.width ?? 8;
+  if (options.width !== undefined && options.resources !== undefined) {
+    throw new Error("queue: choose either width or resources, not both");
+  }
+  const configuredWidth = options.width;
+  const widthNow = () => configuredWidth ?? queueWidthFor(options.resources);
+  const initialWidth = widthNow();
   const retry = { ...DEFAULT_RETRY, ...options.retry };
-  if (!Number.isSafeInteger(width) || width < 1) {
+  if (!Number.isSafeInteger(initialWidth) || initialWidth < 1) {
     throw new RangeError("queue: width must be a positive integer");
   }
   if (!Number.isSafeInteger(retry.attempts) || retry.attempts < 1) {
@@ -68,6 +99,7 @@ function createQueue(options = {}) {
       announceIdle();
       return;
     }
+    const width = widthNow();
     for (const [key, lane] of lanes) {
       if (running.size >= width)
         break;
@@ -215,6 +247,7 @@ function createQueue(options = {}) {
       for (const lane of lanes.values())
         queued += lane.length;
       return {
+        width: widthNow(),
         running: running.size,
         queued,
         keys: lanes.size,

package/dist/backup.d.ts

@@ -32,11 +32,11 @@
  * refuse rather than doing their best.
  */
 export declare class BackupError extends Error {
-    readonly code: 'CHUNK_MISSING' | 'DIGEST_MISMATCH' | 'REALM_MISMATCH' | 'BAD_MANIFEST' | 'UNSUPPORTED_FORMAT' | 'DECRYPT_FAILED' | 'EMPTY_SNAPSHOT' | 'RETENTION_WOULD_EMPTY';
-    constructor(code: 'CHUNK_MISSING' | 'DIGEST_MISMATCH' | 'REALM_MISMATCH' | 'BAD_MANIFEST' | 'UNSUPPORTED_FORMAT' | 'DECRYPT_FAILED' | 'EMPTY_SNAPSHOT' | 'RETENTION_WOULD_EMPTY', message: string);
+    readonly code: 'CHUNK_MISSING' | 'DIGEST_MISMATCH' | 'REALM_MISMATCH' | 'BAD_MANIFEST' | 'UNSUPPORTED_FORMAT' | 'DECRYPT_FAILED' | 'MAINTENANCE_REQUIRED' | 'EMPTY_SNAPSHOT' | 'RETENTION_WOULD_EMPTY';
+    constructor(code: 'CHUNK_MISSING' | 'DIGEST_MISMATCH' | 'REALM_MISMATCH' | 'BAD_MANIFEST' | 'UNSUPPORTED_FORMAT' | 'DECRYPT_FAILED' | 'MAINTENANCE_REQUIRED' | 'EMPTY_SNAPSHOT' | 'RETENTION_WOULD_EMPTY', message: string);
 }
 /** Bumped only for a change that an older reader cannot handle. */
-export declare const SNAPSHOT_FORMAT = 1;
+export declare const SNAPSHOT_FORMAT = 2;
 export interface ChunkRecord {
     index: number;
     /** Object key in the store. */
@@ -55,7 +55,11 @@ export interface SnapshotManifest {
     collections: Record<string, number>;
     chunks: readonly ChunkRecord[];
     totalRows: number;
-    /** Digest over every chunk digest — one value that fixes the whole snapshot. */
+    /**
+     * HMAC-SHA-256 over the canonical manifest body. Despite the legacy field
+     * name this is a keyed authenticator, not a plain digest. Format 1 used an
+     * unkeyed digest and is deliberately not accepted by this reader.
+     */
     sealDigest: string;
     /** Free-form: schema version, application version, who triggered it. */
     labels?: Record<string, string>;
@@ -76,8 +80,14 @@ export interface ObjectStore {
 }
 /** Where the rows come from. Async-iterable so a large collection never lands in memory whole. */
 export interface RowSource {
+    /** Acquire a point-in-time source transaction or equivalent read fence. */
+    begin?(): Promise<void>;
     collections(): Promise<string[]>;
     rows(collection: string): AsyncIterable<Record<string, unknown>>;
+    /** Release the read fence after every row has been captured. */
+    commit?(): Promise<void>;
+    /** Release it after an interrupted or failed capture. */
+    abort?(): Promise<void>;
 }
 /** Where they go on the way back. */
 export interface RowSink {
@@ -90,7 +100,10 @@ export interface RowSink {
     write(collection: string, rows: Record<string, unknown>[]): Promise<void>;
     /** Called before anything is written. The sink's chance to refuse or truncate. */
     begin?(manifest: SnapshotManifest): Promise<void>;
+    /** Commit all staged rows atomically. */
     finish?(manifest: SnapshotManifest): Promise<void>;
+    /** Roll back all staged rows after any write or commit failure. */
+    abort?(manifest: SnapshotManifest): Promise<void>;
 }
 export interface SnapshotOptions {
     store: ObjectStore;
@@ -174,6 +187,7 @@ export declare function restore(options: RestoreOptions): Promise<RestoreReport>
 export declare function listSnapshots(args: {
     store: ObjectStore;
     realm: string;
+    masterSeed: Uint8Array;
     prefix?: string;
 }): Promise<SnapshotManifest[]>;
 export interface RetentionPolicy {
@@ -200,6 +214,7 @@ export declare function selectForDeletion(manifests: readonly SnapshotManifest[]
 export declare function prune(args: {
     store: ObjectStore;
     realm: string;
+    masterSeed: Uint8Array;
     policy?: RetentionPolicy;
     prefix?: string;
     /** Report what would go without removing it. */

package/dist/backup.js

@@ -7,7 +7,14 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 });
 
 // src/backup.ts
-import { hkdf, seal, open, sha256, timingSafeEqual } from "@forgezero/access/security";
+import {
+  hkdf,
+  hmacSha256,
+  seal,
+  open,
+  sha256,
+  timingSafeEqual
+} from "@forgezero/access/security";
 
 class BackupError extends Error {
   code;
@@ -17,15 +24,145 @@ class BackupError extends Error {
     this.name = "BackupError";
   }
 }
-var SNAPSHOT_FORMAT = 1;
+var SNAPSHOT_FORMAT = 2;
 var keyFor = (masterSeed, realm, snapshotId) => hkdf(masterSeed, `forgezero:backup:v1:${realm}:${snapshotId}`, 32);
+var manifestKeyFor = (masterSeed, realm, snapshotId) => hkdf(masterSeed, `forgezero:backup:manifest:v2:${realm}:${snapshotId}`, 32);
 var aadFor = (realm, snapshotId, index) => `backup:${realm}:${snapshotId}:${index}`;
 var objectKey = (prefix, realm, id, part) => `${prefix}${realm}/${id}/${part}`;
+function canonicalManifest(manifest) {
+  return JSON.stringify([
+    manifest.format,
+    manifest.id,
+    manifest.realm,
+    manifest.createdAtMs,
+    Object.entries(manifest.collections).sort(([left], [right]) => left.localeCompare(right)),
+    manifest.chunks.map((chunk) => [
+      chunk.index,
+      chunk.object,
+      chunk.digest,
+      chunk.rows,
+      chunk.bytes
+    ]),
+    manifest.totalRows,
+    manifest.labels ? Object.entries(manifest.labels).sort(([left], [right]) => left.localeCompare(right)) : null
+  ]);
+}
+async function sealManifest(manifest, masterSeed) {
+  const key = await manifestKeyFor(masterSeed, manifest.realm, manifest.id);
+  return hmacSha256(key, canonicalManifest(manifest));
+}
+var MANIFEST_KEYS = new Set([
+  "format",
+  "id",
+  "realm",
+  "createdAtMs",
+  "collections",
+  "chunks",
+  "totalRows",
+  "sealDigest",
+  "labels"
+]);
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function manifestProblem(value) {
+  if (!isRecord(value))
+    return "The manifest is not an object.";
+  if (Object.keys(value).some((key) => !MANIFEST_KEYS.has(key)))
+    return "The manifest has unknown fields.";
+  if (value.format !== SNAPSHOT_FORMAT) {
+    return `Snapshot format ${String(value.format)} is not supported by this reader (${SNAPSHOT_FORMAT}).`;
+  }
+  if (typeof value.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value.id)) {
+    return "The snapshot id is invalid.";
+  }
+  if (typeof value.realm !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value.realm)) {
+    return "The snapshot realm is invalid.";
+  }
+  if (!Number.isSafeInteger(value.createdAtMs) || value.createdAtMs <= 0) {
+    return "The snapshot creation time is invalid.";
+  }
+  if (!isRecord(value.collections) || Object.keys(value.collections).length === 0) {
+    return "The manifest has no collection inventory.";
+  }
+  for (const [collection, count] of Object.entries(value.collections)) {
+    if (!/^[a-z][a-z0-9_]*$/.test(collection) || !Number.isSafeInteger(count) || count < 0) {
+      return `The collection inventory entry "${collection}" is invalid.`;
+    }
+  }
+  if (!Array.isArray(value.chunks) || value.chunks.length === 0)
+    return "The manifest has no chunks.";
+  if (!Number.isSafeInteger(value.totalRows) || value.totalRows <= 0) {
+    return "The manifest row total is invalid.";
+  }
+  if (typeof value.sealDigest !== "string" || !/^[a-f0-9]{64}$/.test(value.sealDigest)) {
+    return "The manifest authenticator is invalid.";
+  }
+  if (value.labels !== undefined) {
+    if (!isRecord(value.labels))
+      return "The manifest labels are invalid.";
+    for (const [label, content] of Object.entries(value.labels)) {
+      if (label.length === 0 || label.length > 128 || typeof content !== "string" || content.length > 1024) {
+        return `The manifest label "${label}" is invalid.`;
+      }
+    }
+  }
+  let chunkRows = 0;
+  let root;
+  for (const [position, candidate] of value.chunks.entries()) {
+    if (!isRecord(candidate))
+      return `Chunk ${position} is not an object.`;
+    const keys = Object.keys(candidate).sort().join(",");
+    if (keys !== "bytes,digest,index,object,rows")
+      return `Chunk ${position} has an invalid shape.`;
+    if (candidate.index !== position)
+      return `Chunk indexes are not contiguous at position ${position}.`;
+    if (typeof candidate.object !== "string" || candidate.object.length > 1024) {
+      return `Chunk ${position} has an invalid object key.`;
+    }
+    const filename = `chunk-${String(position).padStart(5, "0")}.json`;
+    const suffix = `${value.realm}/${value.id}/${filename}`;
+    if (!candidate.object.endsWith(suffix))
+      return `Chunk ${position} is outside the snapshot prefix.`;
+    const candidateRoot = candidate.object.slice(0, -filename.length);
+    root ??= candidateRoot;
+    if (candidateRoot !== root)
+      return `Chunk ${position} does not share the snapshot prefix.`;
+    if (typeof candidate.digest !== "string" || !/^[a-f0-9]{64}$/.test(candidate.digest)) {
+      return `Chunk ${position} has an invalid digest.`;
+    }
+    if (!Number.isSafeInteger(candidate.rows) || candidate.rows <= 0) {
+      return `Chunk ${position} has an invalid row count.`;
+    }
+    if (!Number.isSafeInteger(candidate.bytes) || candidate.bytes <= 0) {
+      return `Chunk ${position} has an invalid byte count.`;
+    }
+    chunkRows += candidate.rows;
+  }
+  if (chunkRows !== value.totalRows)
+    return "Chunk row counts do not equal the manifest total.";
+  const collectionRows = Object.values(value.collections).reduce((sum, count) => sum + count, 0);
+  if (collectionRows !== value.totalRows)
+    return "Collection row counts do not equal the manifest total.";
+  return null;
+}
 async function snapshot(options) {
   const now = options.now ?? Date.now;
   const chunkRows = options.chunkRows ?? 1000;
   const prefix = options.prefix ?? "snapshots/";
-  const id = options.id ?? `snap_${new Date(now()).toISOString().replace(/[-:.]/g, "").slice(0, 15)}`;
+  const nonce = crypto.getRandomValues(new Uint8Array(8));
+  const randomSuffix = Array.from(nonce, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  const id = options.id ?? `snap_${new Date(now()).toISOString().replace(/[-:.TZ]/g, "")}_${randomSuffix}`;
+  if (!Number.isSafeInteger(chunkRows) || chunkRows <= 0) {
+    throw new BackupError("BAD_MANIFEST", "chunkRows must be a positive safe integer.");
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(options.realm)) {
+    throw new BackupError("BAD_MANIFEST", "The snapshot realm is not safe for an object key.");
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(id)) {
+    throw new BackupError("BAD_MANIFEST", "The snapshot id is not safe for an object key.");
+  }
+  if (!prefix || prefix.includes("..") || prefix.startsWith("/") || !prefix.endsWith("/")) {
+    throw new BackupError("BAD_MANIFEST", "The snapshot prefix must be a relative object prefix ending in /.");
+  }
   const key = await keyFor(options.masterSeed, options.realm, id);
   const chunks = [];
   const collections = {};
@@ -47,26 +184,38 @@ async function snapshot(options) {
       bytes: body.length
     });
   };
-  for (const collection of await options.source.collections()) {
-    let batch = [];
-    let count = 0;
-    for await (const row of options.source.rows(collection)) {
-      batch.push(row);
-      count += 1;
-      if (batch.length >= chunkRows) {
-        await flush(collection, batch);
-        batch = [];
+  let sourceFinalized = false;
+  try {
+    await options.source.begin?.();
+    for (const collection of await options.source.collections()) {
+      let batch = [];
+      let count = 0;
+      for await (const row of options.source.rows(collection)) {
+        batch.push(row);
+        count += 1;
+        if (batch.length >= chunkRows) {
+          await flush(collection, batch);
+          batch = [];
+        }
       }
+      await flush(collection, batch);
+      collections[collection] = count;
+      totalRows += count;
+      options.onProgress?.({ collection, rows: count, chunks: chunks.length });
     }
-    await flush(collection, batch);
-    collections[collection] = count;
-    totalRows += count;
-    options.onProgress?.({ collection, rows: count, chunks: chunks.length });
+    await options.source.commit?.();
+    sourceFinalized = true;
+  } catch (cause) {
+    if (!sourceFinalized)
+      await options.source.abort?.().catch(() => {
+        return;
+      });
+    throw cause;
   }
   if (totalRows === 0) {
     throw new BackupError("EMPTY_SNAPSHOT", "The source produced no rows. Refusing to write an empty snapshot.");
   }
-  const manifest = {
+  const unsigned = {
     format: SNAPSHOT_FORMAT,
     id,
     realm: options.realm,
@@ -74,9 +223,12 @@ async function snapshot(options) {
     collections,
     chunks,
     totalRows,
-    sealDigest: await sha256(chunks.map((chunk) => chunk.digest).join("")),
     ...options.labels ? { labels: options.labels } : {}
   };
+  const manifest = {
+    ...unsigned,
+    sealDigest: await sealManifest(unsigned, options.masterSeed)
+  };
   await options.store.putObject({
     key: objectKey(prefix, options.realm, id, "manifest.json"),
     body: JSON.stringify(manifest, null, 2),
@@ -86,9 +238,9 @@ async function snapshot(options) {
 }
 async function verifySnapshot(args) {
   const problems = [];
-  const key = await keyFor(args.masterSeed, args.manifest.realm, args.manifest.id);
   let rowsChecked = 0;
-  if (args.manifest.format > SNAPSHOT_FORMAT) {
+  const invalid = manifestProblem(args.manifest);
+  if (invalid) {
     return {
       ok: false,
       id: args.manifest.id,
@@ -97,12 +249,25 @@ async function verifySnapshot(args) {
       problems: [
         {
           chunk: -1,
-          code: "UNSUPPORTED_FORMAT",
-          message: `Snapshot format ${args.manifest.format} is newer than this reader (${SNAPSHOT_FORMAT}).`
+          code: args.manifest.format !== SNAPSHOT_FORMAT ? "UNSUPPORTED_FORMAT" : "BAD_MANIFEST",
+          message: invalid
         }
       ]
     };
   }
+  const { sealDigest, ...unsigned } = args.manifest;
+  const expectedSeal = await sealManifest(unsigned, args.masterSeed);
+  if (!timingSafeEqual(expectedSeal, sealDigest)) {
+    return {
+      ok: false,
+      id: args.manifest.id,
+      chunksChecked: 0,
+      rowsChecked: 0,
+      problems: [{ chunk: -1, code: "BAD_MANIFEST", message: "The manifest did not authenticate." }]
+    };
+  }
+  const key = await keyFor(args.masterSeed, args.manifest.realm, args.manifest.id);
+  const collectionRows = {};
   for (const chunk of args.manifest.chunks) {
     let raw;
     try {
@@ -135,15 +300,34 @@ async function verifySnapshot(args) {
       });
       continue;
     }
-    rowsChecked += JSON.parse(plaintext).rows.length;
+    let parsed;
+    try {
+      parsed = JSON.parse(plaintext);
+    } catch {
+      problems.push({ chunk: chunk.index, code: "BAD_MANIFEST", message: `${chunk.object} is not JSON.` });
+      continue;
+    }
+    if (!isRecord(parsed) || typeof parsed.collection !== "string" || !Object.hasOwn(args.manifest.collections, parsed.collection) || !Array.isArray(parsed.rows) || parsed.rows.length !== chunk.rows || parsed.rows.some((row) => !isRecord(row))) {
+      problems.push({
+        chunk: chunk.index,
+        code: "BAD_MANIFEST",
+        message: `${chunk.object} does not match its declared collection and row count.`
+      });
+      continue;
+    }
+    collectionRows[parsed.collection] = (collectionRows[parsed.collection] ?? 0) + parsed.rows.length;
+    rowsChecked += parsed.rows.length;
   }
-  const sealDigest = await sha256(args.manifest.chunks.map((chunk) => chunk.digest).join(""));
-  if (!timingSafeEqual(sealDigest, args.manifest.sealDigest)) {
-    problems.push({
-      chunk: -1,
-      code: "BAD_MANIFEST",
-      message: "The manifest does not match its own seal — a chunk was added to or removed from the list."
-    });
+  if (problems.length === 0) {
+    for (const [collection, expectedRows] of Object.entries(args.manifest.collections)) {
+      if ((collectionRows[collection] ?? 0) === expectedRows)
+        continue;
+      problems.push({
+        chunk: -1,
+        code: "BAD_MANIFEST",
+        message: `Collection ${collection} restored ${collectionRows[collection] ?? 0} rows, expected ${expectedRows}.`
+      });
+    }
   }
   return {
     ok: problems.length === 0,
@@ -158,8 +342,8 @@ async function restore(options) {
   if (manifest.realm !== options.realm) {
     throw new BackupError("REALM_MISMATCH", `This snapshot belongs to realm "${manifest.realm}" and cannot be restored into "${options.realm}".`);
   }
-  if (manifest.format > SNAPSHOT_FORMAT) {
-    throw new BackupError("UNSUPPORTED_FORMAT", `Snapshot format ${manifest.format} is newer than this reader (${SNAPSHOT_FORMAT}). Restoring it would silently drop whatever the newer format added.`);
+  if (manifest.format !== SNAPSHOT_FORMAT) {
+    throw new BackupError("UNSUPPORTED_FORMAT", `Snapshot format ${manifest.format} is not supported by this reader (${SNAPSHOT_FORMAT}).`);
   }
   if (!options.skipVerify) {
     const report = await verifySnapshot({
@@ -172,21 +356,31 @@ async function restore(options) {
       throw new BackupError(first.code, `Refusing to restore: ${report.problems.length} problem(s), first at chunk ${first.chunk} — ${first.message}`);
     }
   }
-  await options.sink.begin?.(manifest);
   const key = await keyFor(options.masterSeed, manifest.realm, manifest.id);
   const collections = {};
   let rowsRestored = 0;
-  for (const chunk of manifest.chunks) {
-    const raw = await options.store.getObject(chunk.object);
-    const sealed = JSON.parse(new TextDecoder().decode(raw));
-    const plaintext = await open(key, sealed, aadFor(manifest.realm, manifest.id, chunk.index));
-    const { collection, rows } = JSON.parse(plaintext);
-    await options.sink.write(collection, rows);
-    collections[collection] = (collections[collection] ?? 0) + rows.length;
-    rowsRestored += rows.length;
-    options.onProgress?.({ chunk: chunk.index + 1, of: manifest.chunks.length, rows: rowsRestored });
+  let sinkFinalized = false;
+  try {
+    await options.sink.begin?.(manifest);
+    for (const chunk of manifest.chunks) {
+      const raw = await options.store.getObject(chunk.object);
+      const sealed = JSON.parse(new TextDecoder().decode(raw));
+      const plaintext = await open(key, sealed, aadFor(manifest.realm, manifest.id, chunk.index));
+      const { collection, rows } = JSON.parse(plaintext);
+      await options.sink.write(collection, rows);
+      collections[collection] = (collections[collection] ?? 0) + rows.length;
+      rowsRestored += rows.length;
+      options.onProgress?.({ chunk: chunk.index + 1, of: manifest.chunks.length, rows: rowsRestored });
+    }
+    await options.sink.finish?.(manifest);
+    sinkFinalized = true;
+  } catch (cause) {
+    if (!sinkFinalized)
+      await options.sink.abort?.(manifest).catch(() => {
+        return;
+      });
+    throw cause;
   }
-  await options.sink.finish?.(manifest);
   return { id: manifest.id, rowsRestored, collections };
 }
 async function listSnapshots(args) {
@@ -197,7 +391,14 @@ async function listSnapshots(args) {
     if (!object.key.endsWith("/manifest.json"))
       continue;
     try {
-      manifests.push(JSON.parse(new TextDecoder().decode(await args.store.getObject(object.key))));
+      const manifest = JSON.parse(new TextDecoder().decode(await args.store.getObject(object.key)));
+      const invalid = manifestProblem(manifest);
+      if (invalid || manifest.realm !== args.realm)
+        continue;
+      const { sealDigest, ...unsigned } = manifest;
+      if (!timingSafeEqual(await sealManifest(unsigned, args.masterSeed), sealDigest))
+        continue;
+      manifests.push(manifest);
     } catch {}
   }
   return manifests.sort((a, b) => b.createdAtMs - a.createdAtMs);
@@ -245,7 +446,12 @@ function selectForDeletion(manifests, policy = DEFAULT_RETENTION) {
   return newestFirst.filter((manifest) => !keep.has(manifest.id));
 }
 async function prune(args) {
-  const manifests = await listSnapshots({ store: args.store, realm: args.realm, prefix: args.prefix });
+  const manifests = await listSnapshots({
+    store: args.store,
+    realm: args.realm,
+    masterSeed: args.masterSeed,
+    prefix: args.prefix
+  });
   const doomed = selectForDeletion(manifests, args.policy);
   if (doomed.length >= manifests.length) {
     throw new BackupError("RETENTION_WOULD_EMPTY", "This policy would delete every snapshot. Refusing.");
@@ -276,6 +482,7 @@ function backupJob(options) {
       const pruned = await prune({
         store: options.store,
         realm: options.realm,
+        masterSeed: options.masterSeed,
         policy: options.policy,
         prefix: options.prefix
       });

package/dist/finance/chain-deposits.js

@@ -168,10 +168,14 @@ function parseAccount(id) {
   return { kind, owner, bucket };
 }
 var queueKeyFor = (account) => `${account.kind}:${account.owner}`;
+var MAX_LEDGER_ENTRIES = 64;
 function assertBalanced(transaction) {
-  if (transaction.entries.length === 0) {
+  if (transaction.entries.length < 2) {
     throw new LedgerError("EMPTY_TRANSACTION", "A transaction needs at least two entries.");
   }
+  if (transaction.entries.length > MAX_LEDGER_ENTRIES) {
+    throw new LedgerError("TOO_MANY_ENTRIES", `A transaction may contain at most ${MAX_LEDGER_ENTRIES} entries; split this batch into separate transactions.`);
+  }
   const totals = new Map;
   for (const entry of transaction.entries) {
     if (entry.amount.units === 0n) {

package/dist/finance/chain-withdrawals.js

@@ -168,10 +168,14 @@ function parseAccount(id) {
   return { kind, owner, bucket };
 }
 var queueKeyFor = (account) => `${account.kind}:${account.owner}`;
+var MAX_LEDGER_ENTRIES = 64;
 function assertBalanced(transaction) {
-  if (transaction.entries.length === 0) {
+  if (transaction.entries.length < 2) {
     throw new LedgerError("EMPTY_TRANSACTION", "A transaction needs at least two entries.");
   }
+  if (transaction.entries.length > MAX_LEDGER_ENTRIES) {
+    throw new LedgerError("TOO_MANY_ENTRIES", `A transaction may contain at most ${MAX_LEDGER_ENTRIES} entries; split this batch into separate transactions.`);
+  }
   const totals = new Map;
   for (const entry of transaction.entries) {
     if (entry.amount.units === 0n) {

package/dist/finance/commission.js

@@ -168,10 +168,14 @@ function parseAccount(id) {
   return { kind, owner, bucket };
 }
 var queueKeyFor = (account) => `${account.kind}:${account.owner}`;
+var MAX_LEDGER_ENTRIES = 64;
 function assertBalanced(transaction) {
-  if (transaction.entries.length === 0) {
+  if (transaction.entries.length < 2) {
     throw new LedgerError("EMPTY_TRANSACTION", "A transaction needs at least two entries.");
   }
+  if (transaction.entries.length > MAX_LEDGER_ENTRIES) {
+    throw new LedgerError("TOO_MANY_ENTRIES", `A transaction may contain at most ${MAX_LEDGER_ENTRIES} entries; split this batch into separate transactions.`);
+  }
   const totals = new Map;
   for (const entry of transaction.entries) {
     if (entry.amount.units === 0n) {