@twzrd1111/clawrouter-mpp 0.2.0 → 0.3.0

package/README.md

@@ -3,6 +3,17 @@
 MPP (Machine Payments Protocol) payment rails for [ClawRouter](https://github.com/BlockRunAI/ClawRouter):
 pay an MPP seller over **Tempo** or **Solana** instead of x402, under ClawRouter's own spend limits.
 
+## Upgrading from 0.2.0
+
+- Fulfillment rows now use `twzrd.mpp.fulfillment.v2`. Readers must accept the new schema to retain
+  `response_bytes` and `body_sha256`; these fields are null when the recorder does not read a complete
+  body within its 1 MiB cap.
+- Credit rows carry an optional `reference` matching the error and spend record. It is a local
+  signed-payload hash, not a settlement signature.
+- `payFetch.flush({ timeoutMs })` bounds waiting for both records and ledger persistence. A timeout
+  leaves the paid response and background writes intact; an omitted timeout keeps the previous
+  unbounded wait. Values above 2,147,483,647 ms are rejected.
+
 ```ts
 import { startProxy, SpendControl, FileSpendControlStorage } from "@twzrd1111/clawrouter";
 import { createMppFetch, createSolanaMppFetch } from "@twzrd1111/clawrouter-mpp";
@@ -36,7 +47,13 @@ run asynchronously so they do not hold the response stream. `payFetch.flush?.()`
 records and fsyncs the local ledger during orderly shutdown. `startProxy` calls the rail's flush hook
 after closing its listener, and direct rail users must call `payFetch.flush()` themselves. It waits for
 active SSE responses too, so drain or cancel them before flushing; an open stream can keep the flush
-pending. Network contribution remains off unless separately enabled. It blocks unscored
+pending. `payFetch.flush({ timeoutMs })` bounds the entire wait for records and ledger persistence
+(0 through 2,147,483,647 ms). At the deadline it still attempts the ledger flush in the background,
+then rejects with an `AggregateError` holding an `MppFlushTimeoutError`. Its `pending` field counts
+unfinished records; `ledgerPending` indicates whether ledger flushing is still in progress.
+A late ledger failure is reported once: by a flush still waiting on that ledger, otherwise by the next explicit flush. (Ownership is tracked per ledger promise; an integration that returns a fresh wrapper promise for the same failure to each caller can still see it twice.) A timeout does not confirm durability.
+It never cancels or reads a response body, so a late reader still gets the whole paid response,
+and its record lands when that body is drained. Network contribution remains off unless separately enabled. It blocks unscored
 networks by default, including Tempo mainnet and Moderato, until TWZRD has a reputation corpus for
 them. The default provider also fails closed on outages; the ledger sink itself makes no network
 call. An explicit `allowUnscoredNetwork: true` requires `policy.maxAmountUsd` and returns
@@ -45,7 +62,7 @@ fulfillment row omits prompts, responses, credentials, and raw receipt headers;
 field is explicitly a seller claim. Network contribution remains a separate opt-in.
 
 This integration requires `twzrd-x402-gate@0.17.0`, which is not published yet. npm's current
-`0.16.1` does not include Tempo charge evaluation or this shared-ledger adapter.
+`0.16.2` does not include Tempo charge evaluation or the shared-ledger adapter.
 
 Receipt-safe payment metadata is available through `readPaidCallEvidence(response)` for a paid
 response from this rail. The
@@ -57,6 +74,12 @@ intent match the challenge; it is not an on-chain verification. `seller_reported
 compares labels only and does not verify model identity. A failed local write does not change an
 already-paid response; `payFetch.flush()` surfaces persistence failures to the shutdown caller.
 
+Rows use schema `twzrd.mpp.fulfillment.v2`. `response_bytes` and `body_sha256` (lowercase hex
+SHA-256) describe the complete response body as the recorder read it: a JSON body read through its
+clone, or an SSE body tapped to its end. Both are `null` when the recorder did not read the body,
+it exceeded 1 MiB, or the stream was cancelled or errored before its end; a partial body is never
+hashed. The digest is of bytes the seller sent and is not a seller attestation.
+
 This candidate requires `@twzrd1111/clawrouter >=0.12.309`, including deferred streaming headers.
 The fork is the release target. Upstream PRs #545 and #546 are independent of this release.
 
@@ -121,6 +144,13 @@ synchronous claim gives concurrent duplicates one winner. The claim remains spen
 model fails. This helper does not verify a payment itself,
 and installing a buyer rail cannot add replay protection to a remote seller.
 
+`SpentProofLedger` keeps claims in memory, so a restart or a second process forgets spent
+proofs, and a proof can be redeemed again while its challenge is still valid. A seller with
+more than one process, or one that restarts, needs a durable, atomic uniqueness check shared by
+every worker (for example a unique key on network plus transaction signature, as an
+authoritative settlement table provides). Rejecting expired challenges narrows the window but
+does not close it on its own.
+
 ## Credits for signed calls with no completion
 
 ```ts
@@ -155,6 +185,9 @@ and request deadlines cancel the upstream reader and clean up coalesced callers.
 `CreditLedger` and `creditPaidNoCompletion(ledger, error, fields)` are also public for callers
 with their own ledger; `readCredits(ledger)` reads that ledger. Retrying the credit operation
 returns the same immutable row and invokes no signer. It does not retry a model request.
+Each row carries the payment `reference` from the error (or from `fields.reference`) when one
+is known, so a credit can be joined to the error and the spend record. The reference is a hash
+of the signed payload, not a chain signature; an unknown reference is left off the row.
 
 Both ledgers are in memory, scoped to one process, and reset on restart. Credits record
 signed attempts, not confirmed settlement or redeemable balances. There is no refund, chain

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { Account } from 'viem';
-import { SpendControl, PayFetch, SpendRecord } from '@twzrd1111/clawrouter';
+import { PayFetch, SpendControl, SpendRecord } from '@twzrd1111/clawrouter';
 export { PayFetch } from '@twzrd1111/clawrouter';
 import { KeyPairSigner } from '@solana/kit';
 
-declare const MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v1";
+declare const MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v2";
 declare const MPP_FULFILLMENT_MAX_BODY_BYTES: number;
 type MppPaymentFacts = {
     challengeId: string;
@@ -38,6 +38,18 @@ type MppFulfillmentRecord = {
     /** Equality of seller-reported and requested labels only; this does not verify the served model. */
     seller_reported_model_matches_request: boolean | null;
     gate: MppGateDecision | null;
+    /**
+     * Byte length of the complete response body as received. null when the recorder did not read
+     * the body, it exceeded MPP_FULFILLMENT_MAX_BODY_BYTES, or it was cancelled or errored first.
+     */
+    response_bytes: number | null;
+    /** Lowercase hex SHA-256 of the same complete body; null under the same conditions. */
+    body_sha256: string | null;
+};
+/** Size and digest of a complete response body, or null fields when it was not fully read. */
+type MppBodyDigest = {
+    response_bytes: number | null;
+    body_sha256: string | null;
 };
 type MppFulfillmentSink = (record: MppFulfillmentRecord) => void | Promise<void>;
 
@@ -75,6 +87,27 @@ declare class MppGateError extends Error {
     constructor(code: MppGateError["code"], challengeId: string, message: string, decision?: MppGateDecision);
 }
 
+type MppFlushOptions = {
+    /**
+     * Bound the entire wait for fulfillment records and ledger persistence. At the deadline,
+     * ledger flushing is still attempted in the background; neither writes nor response bodies
+     * are cancelled. Late ledger failures are retained for the next flush(). Omit to wait forever.
+     * Valid range: 0 through 2_147_483_647 milliseconds (Node's maximum timer delay).
+     */
+    timeoutMs?: number;
+};
+/** A rail fetch whose flush() accepts an optional deadline. Assignable to PayFetch. */
+type MppPayFetch = PayFetch & {
+    flush: (options?: MppFlushOptions) => Promise<void>;
+};
+/** The deadline elapsed; persistence may still be running and response bodies remain caller-owned. */
+declare class MppFlushTimeoutError extends Error {
+    readonly pending: number;
+    readonly timeoutMs: number;
+    readonly ledgerPending: boolean;
+    constructor(pending: number, timeoutMs: number, ledgerPending?: boolean);
+}
+
 /**
  * Tempo TIP-20 USD stablecoins priced here, lower-case, all 6 decimals (the challenge carries no
  * `decimals`). Any other asset cannot be priced, so it is refused while amount limits are set.
@@ -108,7 +141,7 @@ declare function quoteFromChallenge(challenge: ChallengeLike, usdAssets?: Readon
     amount: string | undefined;
     priceable: boolean;
 };
-declare function createMppFetch(account: Account, base: typeof fetch | undefined, opts: MppFetchOptions): PayFetch;
+declare function createMppFetch(account: Account, base: typeof fetch | undefined, opts: MppFetchOptions): MppPayFetch;
 
 declare const DEFAULT_SOLANA_USD_MINTS: ReadonlySet<string>;
 type SolanaNetwork = "mainnet" | "devnet" | "localnet";
@@ -123,7 +156,7 @@ type SolanaMppFetchOptions = {
     /** Injectable transport; defaults to fetch. The SDK's RPC transport is separate. */
     fetch?: typeof fetch;
 };
-declare function createSolanaMppFetch(opts: SolanaMppFetchOptions): Promise<PayFetch>;
+declare function createSolanaMppFetch(opts: SolanaMppFetchOptions): Promise<MppPayFetch>;
 
 /** In-memory credit row. No chain write and no signer. */
 type CreditEntry = Readonly<{
@@ -131,6 +164,11 @@ type CreditEntry = Readonly<{
     amount: string;
     challengeId: string;
     reason: string;
+    /**
+     * Payment reference from MppPaidNoCompletionError, when one is known: `mpp-` plus a short hash of
+     * the signed payload. Joins the row to the error and the spend record. Not a chain tx signature.
+     */
+    reference?: string;
 }>;
 declare class CreditLedger {
     private readonly rows;
@@ -149,6 +187,7 @@ declare class MppPaidNoCompletionError extends Error {
 /**
  * Record one credit for a paid call that returned no completion.
  * A retry of the same payer and challenge returns the first row.
+ * The row carries `fields.reference`, else the error's reference when one is known.
  * `sign`, when passed, is never called.
  */
 declare function creditPaidNoCompletion(ledger: CreditLedger, err: MppPaidNoCompletionError, fields: CreditEntry, hooks?: {
@@ -206,5 +245,5 @@ declare function fulfillPaidProof<T>(opts: {
     upstream: () => Promise<T>;
 }): Promise<T>;
 
-export { CreditLedger, DEFAULT_SOLANA_USD_MINTS, DEFAULT_TEMPO_USD_ASSETS, MPP_FULFILLMENT_MAX_BODY_BYTES, MPP_FULFILLMENT_RECORD_SCHEMA, MppGateError, MppPaidNoCompletionError, ReplayRejectedError, SpentProofLedger, createMppFetch, createSolanaMppFetch, creditPaidNoCompletion, fulfillPaidProof, quoteFromChallenge, readCredits, readPaidCallEvidence };
-export type { CreditEntry, MppFetchOptions, MppFulfillmentRecord, MppFulfillmentSink, MppGateChallenge, MppGateDecision, MppGateEvaluator, MppIntegration, MppPaymentFacts, SolanaMppFetchOptions };
+export { CreditLedger, DEFAULT_SOLANA_USD_MINTS, DEFAULT_TEMPO_USD_ASSETS, MPP_FULFILLMENT_MAX_BODY_BYTES, MPP_FULFILLMENT_RECORD_SCHEMA, MppFlushTimeoutError, MppGateError, MppPaidNoCompletionError, ReplayRejectedError, SpentProofLedger, createMppFetch, createSolanaMppFetch, creditPaidNoCompletion, fulfillPaidProof, quoteFromChallenge, readCredits, readPaidCallEvidence };
+export type { CreditEntry, MppBodyDigest, MppFetchOptions, MppFlushOptions, MppFulfillmentRecord, MppFulfillmentSink, MppGateChallenge, MppGateDecision, MppGateEvaluator, MppIntegration, MppPayFetch, MppPaymentFacts, SolanaMppFetchOptions };

package/dist/index.js

@@ -41,12 +41,18 @@ var MppPaidNoCompletionError = class extends Error {
     this.status = status;
   }
 };
+var UNKNOWN_REFERENCE = "mpp-unknown";
 function creditPaidNoCompletion(ledger, err, fields, hooks) {
   if (!(err instanceof MppPaidNoCompletionError)) {
     throw new TypeError("credit requires MppPaidNoCompletionError");
   }
   void hooks;
-  return ledger.recordOnce(fields);
+  const reference = [fields.reference, err.reference].find(
+    (value) => typeof value === "string" && value !== "" && value !== UNKNOWN_REFERENCE
+  );
+  const { reference: _dropped, ...rest } = fields;
+  void _dropped;
+  return ledger.recordOnce(reference ? { ...rest, reference } : rest);
 }
 var credits = new CreditLedger();
 function creditFromChallenge(challenge, payer) {
@@ -160,7 +166,7 @@ async function boundedSnippet(response, timeoutMs = SNIPPET_TIMEOUT_MS) {
   }
 }
 function fail(spend, call, status, detail, cause) {
-  const reference = call.reference ?? "mpp-unknown";
+  const reference = call.reference ?? UNKNOWN_REFERENCE;
   const why = status !== void 0 ? `HTTP ${status}` : "request failed";
   if (spend && call.record) {
     spend.annotateRecord(call.record, `signed, no completion (${why}) ref ${reference}`);
@@ -273,8 +279,10 @@ async function evaluateMppGate(evaluator, challenge) {
 }
 
 // src/mpp-fulfillment-record.ts
-var MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v1";
+import { createHash as createHash2 } from "crypto";
+var MPP_FULFILLMENT_RECORD_SCHEMA = "twzrd.mpp.fulfillment.v2";
 var MPP_FULFILLMENT_MAX_BODY_BYTES = 1024 * 1024;
+var NO_BODY_DIGEST = { response_bytes: null, body_sha256: null };
 function asRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -324,6 +332,7 @@ function createSseReceiptParser(challengeId, expectedIntent, expectedMethod) {
   let unavailable = false;
   let receipt;
   let sellerReportedModel = null;
+  const hash = createHash2("sha256");
   const finishEvent = () => {
     if (data.length && eventName === "payment-receipt" && !receipt) {
       try {
@@ -359,6 +368,7 @@ function createSseReceiptParser(challengeId, expectedIntent, expectedMethod) {
   return {
     push(chunk) {
       totalBytes += chunk.byteLength;
+      if (totalBytes <= MPP_FULFILLMENT_MAX_BODY_BYTES) hash.update(chunk);
       if (totalBytes > MPP_FULFILLMENT_MAX_BODY_BYTES) {
         unavailable = true;
         buffer = "";
@@ -378,6 +388,10 @@ function createSseReceiptParser(challengeId, expectedIntent, expectedMethod) {
         buffer = "";
       }
     },
+    /** Digest of every pushed byte; call only after the source stream reported done. */
+    digest() {
+      return totalBytes > MPP_FULFILLMENT_MAX_BODY_BYTES ? NO_BODY_DIGEST : { response_bytes: totalBytes, body_sha256: hash.digest("hex") };
+    },
     finish() {
       if (!unavailable && !receipt) {
         buffer += decoder.decode();
@@ -391,8 +405,8 @@ function createSseReceiptParser(challengeId, expectedIntent, expectedMethod) {
     }
   };
 }
-async function readJsonCapped(body) {
-  if (!body) return void 0;
+async function readBodyCapped(body) {
+  if (!body) return null;
   const reader = body.getReader();
   const chunks = [];
   let size = 0;
@@ -403,15 +417,32 @@ async function readJsonCapped(body) {
       size += value.byteLength;
       if (size > MPP_FULFILLMENT_MAX_BODY_BYTES) {
         await reader.cancel().catch(() => void 0);
-        return void 0;
+        return null;
       }
       chunks.push(value);
     }
-    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    return Buffer.concat(chunks);
+  } catch {
+    return null;
+  }
+}
+function parseJson(bytes) {
+  if (!bytes) return void 0;
+  try {
+    return JSON.parse(bytes.toString("utf8"));
   } catch {
     return void 0;
   }
 }
+function digestOf(bytes) {
+  return bytes ? {
+    response_bytes: bytes.byteLength,
+    body_sha256: createHash2("sha256").update(bytes).digest("hex")
+  } : NO_BODY_DIGEST;
+}
+async function readJsonCapped(body) {
+  return parseJson(await readBodyCapped(body));
+}
 function bodyIsJson(headers) {
   return (headers.get("content-type") ?? "").toLowerCase().includes("json");
 }
@@ -449,7 +480,7 @@ function wrappedResponse(response, body) {
   });
   return wrapped;
 }
-async function emitRecord(input, receipt, requestValue, responseValue, sink, sellerModelOverride) {
+async function emitRecord(input, receipt, requestValue, responseValue, sink, digest, sellerModelOverride) {
   const req = asRecord(requestValue);
   const res = asRecord(responseValue);
   const requestedModel = string(req?.model);
@@ -474,7 +505,9 @@ async function emitRecord(input, receipt, requestValue, responseValue, sink, sel
     requested_model: requestedModel,
     seller_reported_model: sellerReportedModel,
     seller_reported_model_matches_request: requestedModel && sellerReportedModel ? requestedModel.toLowerCase() === sellerReportedModel.toLowerCase() : null,
-    gate: input.gate ?? null
+    gate: input.gate ?? null,
+    response_bytes: digest.response_bytes,
+    body_sha256: digest.body_sha256
   };
   await sink(row);
 }
@@ -507,11 +540,11 @@ function recordMppFulfillment(input, sink, onPending) {
     });
     track(recording2);
     let recordingStarted = false;
-    const finishRecord = (receipt2, sellerReportedModel) => {
+    const finishRecord = (receipt2, sellerReportedModel, digest) => {
       if (recordingStarted) return;
       recordingStarted = true;
       const write = requestBody.then(
-        (request) => emitRecord(input, receipt2, request, void 0, sink, sellerReportedModel)
+        (request) => emitRecord(input, receipt2, request, void 0, sink, digest, sellerReportedModel)
       );
       void write.then(resolveRecording, rejectRecording);
       void write.catch(() => {
@@ -526,7 +559,7 @@ function recordMppFulfillment(input, sink, onPending) {
           const { done, value } = await reader.read();
           if (done) {
             const parsed = parser.finish();
-            finishRecord(parsed.receipt, parsed.sellerReportedModel);
+            finishRecord(parsed.receipt, parsed.sellerReportedModel, parser.digest());
             controller.close();
             reader.releaseLock();
             return;
@@ -534,7 +567,7 @@ function recordMppFulfillment(input, sink, onPending) {
           parser.push(value);
           controller.enqueue(value);
         } catch (error) {
-          finishRecord({ state: "unavailable", value: null }, null);
+          finishRecord({ state: "unavailable", value: null }, null, NO_BODY_DIGEST);
           controller.error(error);
         }
       },
@@ -542,14 +575,14 @@ function recordMppFulfillment(input, sink, onPending) {
         await reader.cancel(reason).catch(() => void 0);
         const parsed = parser.finish();
         const receipt2 = parsed.receipt.state === "missing" ? { state: "unavailable", value: null } : parsed.receipt;
-        finishRecord(receipt2, parsed.sellerReportedModel);
+        finishRecord(receipt2, parsed.sellerReportedModel, NO_BODY_DIGEST);
       }
     });
     return wrappedResponse(input.response, tapped);
   }
-  const responseBody = bodyIsJson(input.response.headers) ? readJsonCapped(input.response.clone().body) : Promise.resolve(void 0);
+  const responseBody = bodyIsJson(input.response.headers) ? readBodyCapped(input.response.clone().body) : Promise.resolve(null);
   const recording = Promise.all([requestBody, responseBody]).then(
-    ([request, response]) => emitRecord(input, receipt, request, response, sink)
+    ([request, bytes]) => emitRecord(input, receipt, request, parseJson(bytes), sink, digestOf(bytes))
   );
   track(recording);
   void recording.catch(() => {
@@ -583,6 +616,102 @@ function runWithMppPaymentBudget(context, run) {
   return contextStorage.run(context, run);
 }
 
+// src/mpp-flush.ts
+var MppFlushTimeoutError = class extends Error {
+  pending;
+  timeoutMs;
+  ledgerPending;
+  constructor(pending, timeoutMs, ledgerPending = false) {
+    super(
+      `MPP flush deadline reached after ${timeoutMs} ms: ${pending} fulfillment record(s) pending; ledger flush ${ledgerPending ? "still pending" : "finished"}`
+    );
+    this.name = "MppFlushTimeoutError";
+    this.pending = pending;
+    this.timeoutMs = timeoutMs;
+    this.ledgerPending = ledgerPending;
+  }
+};
+var MAX_TIMER_MS = 2147483647;
+function deadlineOf(options) {
+  const value = options?.timeoutMs;
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > MAX_TIMER_MS) {
+    throw new TypeError(`flush timeoutMs must be a number from 0 to ${MAX_TIMER_MS}`);
+  }
+  return value;
+}
+var ownership = /* @__PURE__ */ new WeakMap();
+function ownershipFor(failures) {
+  let entry = ownership.get(failures);
+  if (!entry) {
+    entry = { waiters: /* @__PURE__ */ new Map(), claimed: /* @__PURE__ */ new WeakSet() };
+    ownership.set(failures, entry);
+  }
+  return entry;
+}
+var isObject = (value) => typeof value === "object" && value !== null || typeof value === "function";
+async function flushFulfillments(pending, failures, integrationFlush, options) {
+  const timeoutMs = deadlineOf(options);
+  let timer;
+  let expired = false;
+  const deadline = timeoutMs === void 0 ? void 0 : new Promise((resolve) => {
+    timer = setTimeout(() => {
+      expired = true;
+      resolve();
+    }, timeoutMs);
+  });
+  const wait = (task) => deadline ? Promise.race([task, deadline]) : task;
+  try {
+    await wait(Promise.all([...pending]).then(() => void 0));
+    const owners = ownershipFor(failures);
+    const ownErrors = [];
+    let ledgerPending = true;
+    let waiting = true;
+    let source;
+    try {
+      source = Promise.resolve(integrationFlush());
+    } catch (error) {
+      ownErrors.push(error);
+      ledgerPending = false;
+    }
+    const release = () => {
+      if (!waiting) return;
+      waiting = false;
+      if (!source) return;
+      const left = (owners.waiters.get(source) ?? 1) - 1;
+      if (left > 0) owners.waiters.set(source, left);
+      else owners.waiters.delete(source);
+    };
+    let ledger = Promise.resolve();
+    if (source) {
+      const observed = source;
+      owners.waiters.set(observed, (owners.waiters.get(observed) ?? 0) + 1);
+      ledger = observed.catch((error) => {
+        if (waiting) {
+          ownErrors.push(error);
+          if (isObject(error)) owners.claimed.add(error);
+          const queued = failures.indexOf(error);
+          if (queued >= 0) failures.splice(queued, 1);
+        } else if (!owners.waiters.get(observed) && !(isObject(error) && owners.claimed.has(error)) && !failures.includes(error)) {
+          failures.push(error);
+        }
+      }).finally(() => {
+        ledgerPending = false;
+      });
+    }
+    try {
+      await wait(ledger);
+    } finally {
+      release();
+    }
+    const errors = [.../* @__PURE__ */ new Set([...failures.splice(0), ...ownErrors])];
+    if (expired) errors.push(new MppFlushTimeoutError(pending.size, timeoutMs, ledgerPending));
+    if (errors.length) throw new AggregateError(errors, "MPP fulfillment records did not flush");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 // src/mpp-fetch.ts
 var mppxClientDeps = {
   load: () => loadOptional("mppx", MPPX_RANGE, () => import("mppx/client"))
@@ -747,16 +876,7 @@ function createMppFetch(account, base = fetch, opts) {
   payFetch.supportsNativeStreaming = true;
   payFetch.onNoCompletion = rejectPaidNoCompletion;
   payFetch.isPaidResponse = isPaidResponse;
-  payFetch.flush = async () => {
-    await Promise.all([...pendingFulfillments]);
-    const errors = fulfillmentFailures.splice(0);
-    try {
-      await integration.flush();
-    } catch (error) {
-      errors.push(error);
-    }
-    if (errors.length) throw new AggregateError(errors, "MPP fulfillment records did not flush");
-  };
+  payFetch.flush = (options) => flushFulfillments(pendingFulfillments, fulfillmentFailures, () => integration.flush(), options);
   return payFetch;
 }
 
@@ -968,16 +1088,7 @@ async function createSolanaMppFetch(opts) {
   payFetch.supportsNativeStreaming = true;
   payFetch.onNoCompletion = rejectPaidNoCompletion;
   payFetch.isPaidResponse = isPaidResponse;
-  payFetch.flush = async () => {
-    await Promise.all([...pendingFulfillments]);
-    const errors = fulfillmentFailures.splice(0);
-    try {
-      await integration.flush();
-    } catch (error) {
-      errors.push(error);
-    }
-    if (errors.length) throw new AggregateError(errors, "MPP fulfillment records did not flush");
-  };
+  payFetch.flush = (options) => flushFulfillments(pendingFulfillments, fulfillmentFailures, () => integration.flush(), options);
   return payFetch;
 }
 function solanaNetworkId(value) {
@@ -1041,6 +1152,7 @@ export {
   DEFAULT_TEMPO_USD_ASSETS,
   MPP_FULFILLMENT_MAX_BODY_BYTES,
   MPP_FULFILLMENT_RECORD_SCHEMA,
+  MppFlushTimeoutError,
   MppGateError,
   MppPaidNoCompletionError,
   ReplayRejectedError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twzrd1111/clawrouter-mpp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MPP (Machine Payments Protocol) payment rails for ClawRouter: Tempo and Solana charge, with spend limits and paid-failure handling",
   "type": "module",
   "main": "dist/index.js",