@forgezero/runtime 0.1.4 → 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

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) {

package/dist/finance/ledger.d.ts

@@ -33,8 +33,8 @@ import { type Money } from './money';
  * must balance, so a split that loses a unit cannot be committed at all.
  */
 export declare class LedgerError extends Error {
-    readonly code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE';
-    constructor(code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE', message: string);
+    readonly code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'TOO_MANY_ENTRIES' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE';
+    constructor(code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'TOO_MANY_ENTRIES' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE', message: string);
 }
 /**
  * The sub-accounts every owner has.
@@ -96,6 +96,12 @@ export interface Transaction {
     atMs: number;
     memo?: string;
 }
+/**
+ * A ledger transaction is one atomic business movement, not a batch transport.
+ * Keeping the posting set small bounds both the durable document and the
+ * multikey `accountIds[*]` index entry fan-out derived from it by the API.
+ */
+export declare const MAX_LEDGER_ENTRIES = 64;
 /**
  * Every transaction sums to zero, per asset.
  *

package/dist/finance/ledger.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) {
@@ -302,6 +306,7 @@ export {
   assertAvailable,
   accountId,
   VERSION2 as VERSION,
+  MAX_LEDGER_ENTRIES,
   LedgerError,
   BUCKETS,
   ACCOUNT_KINDS

package/dist/jobs.d.ts

@@ -86,6 +86,8 @@ export interface JobContext {
     log(message: string, detail?: Record<string, unknown>): void;
 }
 export interface JobResult {
+    /** A resolved run may still report an operational failure without throwing. */
+    ok?: boolean;
     /** Anything worth showing on a status screen. Kept in the report verbatim. */
     [key: string]: unknown;
 }

package/dist/jobs.js

@@ -477,8 +477,15 @@ function createScheduler(options) {
         log: (message, detail) => options.onLog?.(job.key, message, detail)
       });
       report.lastResult = result ?? undefined;
-      report.lastError = undefined;
-      report.consecutiveFailures = 0;
+      if (result?.ok === false) {
+        const error = new Error("job returned ok=false");
+        report.lastError = error.message;
+        report.consecutiveFailures += 1;
+        options.onError?.(job.key, error);
+      } else {
+        report.lastError = undefined;
+        report.consecutiveFailures = 0;
+      }
     } catch (error) {
       report.lastError = error instanceof Error ? error.message : String(error);
       report.consecutiveFailures += 1;

package/dist/query.d.ts

@@ -0,0 +1,47 @@
+/** Provider-neutral, function-based typed query contracts. */
+export type QueryIssue = Readonly<{
+    path: string;
+    message: string;
+}>;
+export type QueryDecode<T> = Readonly<{
+    ok: true;
+    value: T;
+}> | Readonly<{
+    ok: false;
+    issues: readonly QueryIssue[];
+}>;
+/** Inputs may coerce wire values; outputs must validate strictly. */
+export interface QueryCodec<T> {
+    readonly schema?: unknown;
+    decode(value: unknown): QueryDecode<T>;
+    encode(value: unknown): QueryDecode<T>;
+}
+export interface QueryContract<Name extends string, Input, Output> {
+    readonly name: Name;
+    readonly input: QueryCodec<Input>;
+    readonly output: QueryCodec<Output>;
+}
+export declare class QueryContractError extends Error {
+    readonly query: string;
+    readonly phase: 'input' | 'output' | 'aborted';
+    readonly issues: readonly QueryIssue[];
+    constructor(query: string, phase: 'input' | 'output' | 'aborted', issues?: readonly QueryIssue[]);
+}
+export declare function defineQuery<const Name extends string, Input, Output>(definition: {
+    name: Name;
+    input: QueryCodec<Input>;
+    output: QueryCodec<Output>;
+}): QueryContract<Name, Input, Output>;
+export interface QueryExecution {
+    readonly signal: AbortSignal;
+}
+export interface QueryImplementation<Context, Output> {
+    execute(context: Context, input: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<Output>;
+}
+export declare function implementQuery<Context, Name extends string, Input, Output>(contract: QueryContract<Name, Input, Output>, handler: (context: Context, input: Input, execution: QueryExecution) => Output | Promise<Output>): QueryImplementation<Context, Output> & {
+    readonly contract: typeof contract;
+};
+export type QueryInput<Q> = Q extends QueryContract<string, infer Input, unknown> ? Input : never;
+export type QueryOutput<Q> = Q extends QueryContract<string, unknown, infer Output> ? Output : never;

package/dist/query.js

@@ -0,0 +1,51 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/query.ts
+class QueryContractError extends Error {
+  query;
+  phase;
+  issues;
+  constructor(query, phase, issues = []) {
+    super(`Query ${query} failed ${phase} validation`);
+    this.query = query;
+    this.phase = phase;
+    this.issues = issues;
+    this.name = "QueryContractError";
+  }
+}
+function defineQuery(definition) {
+  if (!definition.name.trim())
+    throw new Error("A query contract requires a stable name");
+  return Object.freeze({ ...definition });
+}
+function implementQuery(contract, handler) {
+  return {
+    contract,
+    async execute(context, rawInput, options = {}) {
+      const signal = options.signal ?? new AbortController().signal;
+      if (signal.aborted)
+        throw new QueryContractError(contract.name, "aborted");
+      const decoded = contract.input.decode(rawInput);
+      if (!decoded.ok)
+        throw new QueryContractError(contract.name, "input", decoded.issues);
+      const rawOutput = await handler(context, decoded.value, { signal });
+      if (signal.aborted)
+        throw new QueryContractError(contract.name, "aborted");
+      const encoded = contract.output.encode(rawOutput);
+      if (!encoded.ok)
+        throw new QueryContractError(contract.name, "output", encoded.issues);
+      return encoded.value;
+    }
+  };
+}
+export {
+  implementQuery,
+  defineQuery,
+  QueryContractError
+};

package/dist/schema-typebox.d.ts

@@ -1,4 +1,5 @@
 import type { TSchema, Static } from '@sinclair/typebox';
+import type { QueryCodec } from './query';
 import { type SchemaValidator } from './schema';
 /**
  * TypeBox implementation of `SchemaValidator`.
@@ -20,5 +21,7 @@ export declare const typebox: SchemaValidator<TSchema>;
  * refusing to start.
  */
 export declare function parse<T extends TSchema>(schema: T, value: unknown): Static<T>;
+/** TypeBox codec for `@forgezero/runtime/query`. */
+export declare function typeboxQueryCodec<T extends TSchema>(schema: T): QueryCodec<Static<T>>;
 export { Type as T } from '@sinclair/typebox';
 export type { TSchema, Static } from '@sinclair/typebox';

package/dist/schema-typebox.js

@@ -21,6 +21,7 @@ var DEFAULT_RESTRICTIONS = {
   maxDepth: 4,
   maxFields: 100,
   maxBytes: 64 * 1024,
+  maxArrayItems: 1000,
   forbidden: ["$ref", "$id", "$dynamicRef", "$dynamicAnchor", "$schema", "definitions", "$defs"]
 };
 function restrictJsonSchema(schema, limits = DEFAULT_RESTRICTIONS) {
@@ -59,8 +60,20 @@ function restrictJsonSchema(schema, limits = DEFAULT_RESTRICTIONS) {
         walk(properties[name], depth + 1, path ? `${path}.${name}` : name);
       }
     }
-    if (record.type === "array" && record.items) {
-      walk(record.items, depth + 1, `${path}[]`);
+    if (record.type === "array") {
+      const maximum = record.maxItems;
+      if (!Number.isInteger(maximum) || maximum < 0) {
+        throw new SchemaError("SCHEMA_ARRAY_UNBOUNDED", "Arrays must declare a finite non-negative integer maxItems.", path || "(root)");
+      }
+      if (maximum > limits.maxArrayItems) {
+        throw new SchemaError("SCHEMA_ARRAY_TOO_LARGE", `Array maxItems ${maximum} exceeds the platform limit of ${limits.maxArrayItems}.`, path || "(root)");
+      }
+      const minimum = record.minItems;
+      if (minimum !== undefined && (!Number.isInteger(minimum) || minimum < 0 || minimum > maximum)) {
+        throw new SchemaError("SCHEMA_ARRAY_BOUNDS_INVALID", "minItems must be a non-negative integer no larger than maxItems.", path || "(root)");
+      }
+      if (record.items)
+        walk(record.items, depth + 1, `${path}[]`);
     }
   };
   walk(schema, 1, "");
@@ -194,7 +207,24 @@ function parse(schema, value) {
   const first = result.errors[0];
   throw new SchemaError("SCHEMA_INVALID", first?.message ?? "Value does not match schema", first?.path);
 }
+function typeboxQueryCodec(schema) {
+  const issues = (value) => [...Value.Errors(schema, value)].map((error) => ({
+    path: error.path || "(root)",
+    message: error.message
+  }));
+  return {
+    schema,
+    decode(value) {
+      const converted = Value.Convert(schema, value);
+      return Value.Check(schema, converted) ? { ok: true, value: Value.Clean(schema, converted) } : { ok: false, issues: issues(converted) };
+    },
+    encode(value) {
+      return Value.Check(schema, value) ? { ok: true, value: Value.Clean(schema, value) } : { ok: false, issues: issues(value) };
+    }
+  };
+}
 export {
+  typeboxQueryCodec,
   typebox,
   parse,
   Type as T

package/dist/schema.d.ts

@@ -38,6 +38,8 @@ export interface Restrictions {
     maxDepth: number;
     maxFields: number;
     maxBytes: number;
+    /** Largest caller-authored array a persisted value may contain. */
+    maxArrayItems: number;
     /** Keywords refused outright, wherever they appear. */
     forbidden: readonly string[];
 }

package/dist/schema.js

@@ -21,6 +21,7 @@ var DEFAULT_RESTRICTIONS = {
   maxDepth: 4,
   maxFields: 100,
   maxBytes: 64 * 1024,
+  maxArrayItems: 1000,
   forbidden: ["$ref", "$id", "$dynamicRef", "$dynamicAnchor", "$schema", "definitions", "$defs"]
 };
 function restrictJsonSchema(schema, limits = DEFAULT_RESTRICTIONS) {
@@ -59,8 +60,20 @@ function restrictJsonSchema(schema, limits = DEFAULT_RESTRICTIONS) {
         walk(properties[name], depth + 1, path ? `${path}.${name}` : name);
       }
     }
-    if (record.type === "array" && record.items) {
-      walk(record.items, depth + 1, `${path}[]`);
+    if (record.type === "array") {
+      const maximum = record.maxItems;
+      if (!Number.isInteger(maximum) || maximum < 0) {
+        throw new SchemaError("SCHEMA_ARRAY_UNBOUNDED", "Arrays must declare a finite non-negative integer maxItems.", path || "(root)");
+      }
+      if (maximum > limits.maxArrayItems) {
+        throw new SchemaError("SCHEMA_ARRAY_TOO_LARGE", `Array maxItems ${maximum} exceeds the platform limit of ${limits.maxArrayItems}.`, path || "(root)");
+      }
+      const minimum = record.minItems;
+      if (minimum !== undefined && (!Number.isInteger(minimum) || minimum < 0 || minimum > maximum)) {
+        throw new SchemaError("SCHEMA_ARRAY_BOUNDS_INVALID", "minItems must be a non-negative integer no larger than maxItems.", path || "(root)");
+      }
+      if (record.items)
+        walk(record.items, depth + 1, `${path}[]`);
     }
   };
   walk(schema, 1, "");

package/package.json

@@ -1,10 +1,10 @@
 {
-	"//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
 	"name": "@forgezero/runtime",
-	"version": "0.1.4",
+	"version": "0.1.5",
 	"type": "module",
-	"publishConfig": {
-		"access": "public"
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
 	},
 	"exports": {
 		"./jobs": {
@@ -43,6 +43,10 @@
 			"types": "./dist/schema-typebox.d.ts",
 			"default": "./dist/schema-typebox.js"
 		},
+		"./query": {
+			"types": "./dist/query.d.ts",
+			"default": "./dist/query.js"
+		},
 		"./calendar": {
 			"types": "./dist/calendar.d.ts",
 			"default": "./dist/calendar.js"
@@ -179,7 +183,7 @@
 	"scripts": {
 		"check": "tsc --noEmit",
 		"prebuild": "rm -rf dist",
-		"build": "bun build src/jobs.ts src/queue.ts src/outbox.ts src/audit.ts src/backup.ts src/notify.ts src/notify-templates.ts src/calendar.ts src/compliance.ts src/pipeline.ts src/totp.ts src/otpauth.ts src/identity.ts src/slip10.ts src/openssh.ts src/ssh-cert.ts src/importers.ts src/snp.ts src/passkey.ts src/custody-crypto.ts src/custody-share.ts src/phrase.ts src/ssh-agent.ts src/schema.ts src/schema-typebox.ts src/finance/discounts.ts src/finance/money.ts src/finance/storage.ts src/finance/custody.ts src/finance/tax.ts src/finance/derive.ts src/finance/venues.ts src/finance/ledger.ts src/finance/rates.ts src/finance/transfers.ts src/finance/chain.ts src/finance/chain-addresses.ts src/finance/chain-deposits.ts src/finance/chain-withdrawals.ts src/finance/chain-reconcile.ts src/finance/market.ts src/finance/commission.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+		"build": "bun build src/query.ts src/jobs.ts src/queue.ts src/outbox.ts src/audit.ts src/backup.ts src/notify.ts src/notify-templates.ts src/calendar.ts src/compliance.ts src/pipeline.ts src/totp.ts src/otpauth.ts src/identity.ts src/slip10.ts src/openssh.ts src/ssh-cert.ts src/importers.ts src/snp.ts src/passkey.ts src/custody-crypto.ts src/custody-share.ts src/phrase.ts src/ssh-agent.ts src/schema.ts src/schema-typebox.ts src/finance/discounts.ts src/finance/money.ts src/finance/storage.ts src/finance/custody.ts src/finance/tax.ts src/finance/derive.ts src/finance/venues.ts src/finance/ledger.ts src/finance/rates.ts src/finance/transfers.ts src/finance/chain.ts src/finance/chain-addresses.ts src/finance/chain-deposits.ts src/finance/chain-withdrawals.ts src/finance/chain-reconcile.ts src/finance/market.ts src/finance/commission.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"dependencies": {
@@ -242,7 +246,7 @@
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/forgezero-net/packages.git",
-		"directory": "packages/runtime"
+		"directory": "runtime"
 	},
 	"bugs": "https://github.com/forgezero-net/packages/issues",
 	"sideEffects": false,