@inversealtruism/cairn-sdk 0.4.0 → 0.4.1

package/dist/index.d.ts

@@ -134,7 +134,9 @@ interface OfferFillCheck {
  * Pre-verify an offer on-chain before building a `fillOffer` payment. `light` is a PoW-verifying light client
  * (its `verifyTxInclusion` surfaces the merkle-proven tx + committed appPayloadHash); `client` reads source txs
  * for the prevout-owner author bind. Pass `servedOffer` (the resolver's offer object) to also bind its
- * payto/seller/terms to the proven values. See the module header for the trust posture.
+ * payto/seller/terms to the proven values. The FULL object is required: a served offer missing want.payto
+ * or seller is refused (P75-5). A token-priced offer's served want.ticker/want.amount are bound verbatim to
+ * the record. See the module header for the trust posture.
  */
 declare function preverifyOffer(opts: {
     light: {
@@ -158,7 +160,7 @@ declare function preverifyOffer(opts: {
 
 /** Stable machine-readable error codes (branch on these, not the message text). */
 type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "ACCOUNT_CHANGED" | "FIRST_PARTY_ONLY" | "RATE_LIMITED" | "APPROVAL_CLOSED" | "FORBIDDEN" | "INTERNAL" | "GHOST_INPUTS_SKIPPED" | "VERIFY_UNAVAILABLE" | "VERIFY_TAMPER" | "INSUFFICIENT" | "TOO_MANY_INPUTS" | "FEE_TOO_LOW" | "FEE_CAP" | "BAD_FEE" | "ZERO_ADDR_REFUSED" | "BAD_OUTPUTS" | "NO_OUTPUTS" | "BAD_REQUEST" | "OFFER_UNKNOWN" | "FILL_UNSAFE" | "FILL_WRONG_TARGET" | "SOURCE_DIVERGENCE" | "SUBMIT_REJECTED" | "SUBMIT_MAYBE_INFLIGHT" | "SUBMIT_DUPLICATE" | "NOTHING_TO_CONSOLIDATE" | "UNKNOWN";
-declare const SDK_VERSION = "0.4.0";
+declare const SDK_VERSION = "0.4.1";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
@@ -178,7 +180,7 @@ declare class CairnError extends Error {
     /** Relative docs path (under the SDK docs base), if any. */
     readonly docsPath?: string;
     /** The cairn-sdk version that produced this error. */
-    readonly version = "0.4.0";
+    readonly version = "0.4.1";
     /**
      * Whether a dApp may safely AUTO-retry this failure. `false` for fund-safety refusals and user-intent
      * declines (the default); `true` only for provably transient infra faults where nothing was signed.
@@ -317,7 +319,7 @@ declare class Cairn {
     wallet?: WalletConnection;
     private readonly cairnHttp;
     private _spvLight;
-    private _spvSeeded;
+    private _spvSeedInflight;
     private readonly _spvCp;
     private readonly _cairnBase;
     constructor(config?: CairnConfig);
@@ -328,18 +330,30 @@ declare class Cairn {
      * checkpoint (can't verify backward) or if verification fails — the IndexerClient then degrades
      * to the honest "proof-consistent" instead of over-claiming "verified-inclusion". The verified
      * header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
+     * MF-03: a STRUCTURAL forward-sync break (a reorg orphaned the cached tip) reseeds ONCE via
+     * withSpvReseed. RESIDUAL: a height at or below the cached tip answers from the cached branch with
+     * NO network touch, so a tx in a reorg-orphaned block can still read "verified-inclusion" until a
+     * read PAST the tip trips the reseed; this closes the permanent post-reorg brick, not reorg-blindness.
      */
     private verifiedHeaderMerkleAt;
-    /** The PoW-verifying SPV light client, seeded ONCE from the pinned checkpoint (shared by the M3 header-merkle
-     *  bind and the F13 offer pre-verify). Reused across calls; the first call near tip syncs the post-checkpoint span. */
+    private withSpvReseed;
+    private seedFreshSpvLight;
+    /** The PoW-verifying SPV light client, seeded from the pinned checkpoint and cached across calls
+     *  (shared by the M3 header-merkle bind and the F13 offer pre-verify). The client is committed to
+     *  the field ONLY after a fully successful seed (MF-14): a failed seed leaves NO cached state, so
+     *  the next call retries on a fresh client instead of wedging on "seedTrusted must be called on a
+     *  fresh client". Concurrent first callers share ONE in-flight seed. Re-seeded only when a
+     *  structural (reorg) break is detected, see withSpvReseed. */
     private seededSpvLight;
     /**
      * W12 batch header transport for the checkpoint..tip forward sync, backed by the cairn server's
      * `/api/headers/:from/:count`. Carries ZERO trust: the LightClient re-verifies every header's PoW /
      * prev-link / LWMA, so a forged or stale row fails closed and retrying transport proves nothing new.
      * Retry budget: a 429 (per-IP header budget) or 502/503 (a height past the lagging indexer, or the
-     * server's 10s deadline) is a transient data-availability hiccup; back off (honouring Retry-After) a
-     * bounded number of times, then THROW so `sync()` fails closed. A non-dense range is rejected.
+     * server's 10s deadline), a transport/timeout error, or a body-read fault (an oversize stream past the
+     * SPV_MAX_BATCH_BYTES cap, or a non-JSON 200 body such as a CF interstitial) is a transient
+     * data-availability hiccup; back off (honouring Retry-After) a bounded number of times, then THROW so
+     * `sync()` fails closed. A non-dense range is rejected terminally (never retried).
      *
      * B7d / F6 DEPENDENCY: `/api/headers` serves no Access-Control-Allow-Origin today (`corsPublic` is
      * mounted on `/explorer/api`, `/trade/api` and `/api/rpc`, not here). A SAME-ORIGIN dApp (hosted on the
@@ -359,8 +373,15 @@ declare class Cairn {
      * This is best-effort corroboration, NOT the payment-grade boundary: the Cairn Wallet's OWN on-device
      * fill-SPV (0.2.60+, fails-closed before signing) is that. A dApp settling real value should still clear this
      * before building `outputs`, so it never hands the wallet a payment a lying resolver would redirect.
+     *
+     * Pass opts.pay (the CSD base units you intend to pay) to receive the PROVEN outputPlan for a whole fill of a
+     * non-partial offer, and opts.plannedOutputs to bind your planned per-address sums to it before signing; build
+     * EXACTLY the outputPlan, never resolver-served outputs.
      */
-    verifyOfferForFill(offerId: string, servedOffer?: unknown): Promise<OfferFillCheck>;
+    verifyOfferForFill(offerId: string, servedOffer?: unknown, opts?: {
+        pay?: bigint | string | number;
+        plannedOutputs?: Record<string, bigint | string | number>;
+    }): Promise<OfferFillCheck>;
     /**
      * Detect + connect the Cairn Wallet (browser only). Wires the wallet into
      * `cairn.board` for signed writes. Resolves to the connected address.

package/dist/index.js

@@ -1,22 +1,24 @@
 import {
-  RegistryClient
-} from "./chunk-BGJZF7S2.js";
+  Http,
+  RegistryClient,
+  readCapped
+} from "./chunk-7UOTIAYK.js";
 import {
   BoardClient
-} from "./chunk-2ZML7IKV.js";
+} from "./chunk-DUTVUIQF.js";
 import {
   Chain,
   LightClient
 } from "./chunk-C452UODV.js";
 import {
   ContentClient
-} from "./chunk-2L5QNDAE.js";
+} from "./chunk-OCEHXK6A.js";
 import {
   IndexerClient
 } from "./chunk-J5J4JEJ6.js";
 import {
   CairnController
-} from "./chunk-GTTLMWGY.js";
+} from "./chunk-QATE6AIP.js";
 import {
   WalletConnection,
   connect,
@@ -24,7 +26,7 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-RKR3JMIA.js";
+} from "./chunk-PIPN6FSA.js";
 import {
   CairnError,
   ContentVerificationError,
@@ -38,147 +40,7 @@ import {
   errorCode,
   mapProviderError,
   mapSubmitResultError
-} from "./chunk-MREZG2HN.js";
-
-// src/http.ts
-var DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
-var ERR_TEXT_CAP = 8 * 1024;
-async function readCapped(res, maxBytes) {
-  const cl = Number(res.headers.get("content-length"));
-  if (Number.isFinite(cl) && cl > maxBytes) throw new HttpError(res.status, res.url, `response too large (content-length ${cl} > ${maxBytes})`);
-  const body = res.body;
-  if (!body || typeof body.getReader !== "function") {
-    const buf = new Uint8Array(await res.arrayBuffer());
-    if (buf.byteLength > maxBytes) throw new HttpError(res.status, res.url, `response too large (${buf.byteLength} > ${maxBytes})`);
-    return buf;
-  }
-  const reader = body.getReader();
-  const chunks = [];
-  let total = 0;
-  for (; ; ) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    if (value) {
-      total += value.byteLength;
-      if (total > maxBytes) {
-        try {
-          await reader.cancel();
-        } catch {
-        }
-        throw new HttpError(res.status, res.url, `response exceeded ${maxBytes} bytes`);
-      }
-      chunks.push(value);
-    }
-  }
-  const out = new Uint8Array(total);
-  let off = 0;
-  for (const c of chunks) {
-    out.set(c, off);
-    off += c.byteLength;
-  }
-  return out;
-}
-var Http = class {
-  baseUrl;
-  _fetch;
-  timeoutMs;
-  maxBytes;
-  headers;
-  retries;
-  constructor(opts) {
-    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-    const f = opts.fetch ?? globalThis.fetch;
-    if (!f) throw new Error("No fetch available \u2014 pass `fetch` in the SDK options.");
-    this._fetch = opts.fetch ? opts.fetch : f.bind(globalThis);
-    this.timeoutMs = opts.timeoutMs ?? 15e3;
-    this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
-    this.headers = opts.headers ?? {};
-    this.retries = Math.min(10, Math.max(0, Math.floor(opts.retries ?? 0)));
-  }
-  /** Build an absolute URL from a path + optional query params. */
-  url(path, query) {
-    const p = path.startsWith("/") ? path : `/${path}`;
-    const u = new URL(this.baseUrl + p);
-    const basePath = new URL(this.baseUrl + "/").pathname;
-    if (basePath !== "/" && !(u.pathname + "/").startsWith(basePath)) {
-      throw new Error(`illegal path '${path}' \u2014 escapes base ${basePath}`);
-    }
-    if (query) {
-      for (const [k, v] of Object.entries(query)) {
-        if (v !== void 0 && v !== null) u.searchParams.set(k, String(v));
-      }
-    }
-    return u.toString();
-  }
-  async raw(method, path, opts) {
-    const url = this.url(path, opts?.query);
-    const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
-    try {
-      const res = await this._fetch(url, {
-        method,
-        signal: ctrl.signal,
-        headers: {
-          ...opts?.body !== void 0 ? { "content-type": "application/json" } : {},
-          ...this.headers,
-          ...opts?.headers ?? {}
-        },
-        body: opts?.body !== void 0 ? JSON.stringify(opts.body) : void 0
-      });
-      return res;
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-  // A malformed 2xx body must surface as a TYPED HttpError, not a leaked SyntaxError (B10: dApp
-  // code branches on `instanceof CairnError`; a raw parse error escaped that contract).
-  parseJson(res, text, url) {
-    try {
-      return JSON.parse(text);
-    } catch (e) {
-      throw new HttpError(res.status, url, `invalid JSON body: ${text.slice(0, 120)}`);
-    }
-  }
-  async getJson(path, query) {
-    const url = this.url(path, query);
-    for (let attempt = 0; ; attempt++) {
-      try {
-        const res = await this.raw("GET", path, { query });
-        if (!res.ok) {
-          if (!(res.status >= 500 && attempt < this.retries)) throw new HttpError(res.status, url, await safeText(res));
-          res.body?.cancel().catch(() => {
-          });
-        } else {
-          return this.parseJson(res, new TextDecoder().decode(await readCapped(res, this.maxBytes)), url);
-        }
-      } catch (e) {
-        if (e instanceof HttpError && e.status < 500) throw e;
-        if (attempt >= this.retries) throw e;
-      }
-      await new Promise((r) => setTimeout(r, Math.floor(Math.random() * Math.min(4e3, 250 * 2 ** attempt))));
-    }
-  }
-  async postJson(path, body, headers) {
-    const url = this.url(path);
-    const res = await this.raw("POST", path, { body, headers });
-    if (!res.ok) throw new HttpError(res.status, url, await safeText(res));
-    return this.parseJson(res, new TextDecoder().decode(await readCapped(res, this.maxBytes)), url);
-  }
-  /** GET raw bytes (for content retrieval). Returns null on 404. */
-  async getBytes(path) {
-    const res = await this.raw("GET", path);
-    if (res.status === 404) return null;
-    if (!res.ok) throw new HttpError(res.status, this.url(path), await safeText(res));
-    return { bytes: await readCapped(res, this.maxBytes), headers: res.headers };
-  }
-};
-async function safeText(res) {
-  try {
-    return new TextDecoder().decode(await readCapped(res, ERR_TEXT_CAP));
-  } catch {
-    return "";
-  }
-}
+} from "./chunk-ERBT4DFD.js";
 
 // src/names.ts
 import { NAME_RE, RESERVED_NAMES } from "@inversealtruism/cairnx-core";
@@ -274,6 +136,7 @@ var NamesClient = class {
 import { rpcTxToTx } from "@inversealtruism/csd-client";
 import { txid, payloadHash } from "@inversealtruism/csd-codec";
 import {
+  DOMAIN,
   parseRecord,
   feeBpsAt,
   bindOfferTerms,
@@ -349,6 +212,8 @@ async function preverifyOffer(opts) {
   if (String(provenId).toLowerCase() !== id) return { ok: false, trust: "unverified", reason: "the merkle-proven tx doesn't match the offer id" };
   const app = incl.tx.app;
   if (!app || app.type !== "Propose") return { ok: false, trust: "unverified", reason: "the offer tx is not a Propose" };
+  if (String(app.domain) !== DOMAIN)
+    return { ok: false, trust: "unverified", reason: `the offer tx is not a ${DOMAIN} Propose (wrong settlement domain)` };
   let rec;
   try {
     rec = parseRecord(app.uri, incl.appPayloadHash);
@@ -367,37 +232,47 @@ async function preverifyOffer(opts) {
   let outputPlan;
   let sumsMismatch;
   if (opts.pay !== void 0 && opts.pay !== null && !isTokenWant(offerRec.want) && offerRec.min === void 0) {
+    const servedStatus = opts.servedOffer?.status;
     const provenState = {
       id,
       seller,
       give: offerRec.give,
-      want: offerRec.want,
+      want: { ...offerRec.want, payto },
       taker: offerRec.taker,
       bid: offerRec.bid,
-      status: "open",
+      status: typeof servedStatus === "string" ? servedStatus : "open",
       expiresEpoch: 0,
       height: blockHeight,
       feeBps: terms.feeBps
     };
-    const plan = fillOutputPlan(provenState, opts.pay);
-    if (plan.kind === "csd-outputs") {
-      outputPlan = plan.outputs;
-      if (opts.plannedOutputs !== void 0 && opts.plannedOutputs !== null)
-        sumsMismatch = bindPlannedSums(opts.plannedOutputs, plan.outputs);
-    } else if (plan.kind === "undeliverable") {
-      sumsMismatch = `this pay would not deliver against the proven offer (${plan.reason}) - refusing (the CSD would be lost)`;
+    try {
+      const plan = fillOutputPlan(provenState, opts.pay);
+      if (plan.kind === "csd-outputs") {
+        outputPlan = plan.outputs;
+        if (opts.plannedOutputs !== void 0 && opts.plannedOutputs !== null)
+          sumsMismatch = bindPlannedSums(opts.plannedOutputs, plan.outputs);
+      } else if (plan.kind === "undeliverable") {
+        sumsMismatch = `this pay would not deliver against the proven offer (${plan.reason}) - refusing (the CSD would be lost)`;
+      }
+    } catch (e) {
+      sumsMismatch = `couldn't size the fill against the proven offer (${e?.message ?? e}) - refusing rather than sizing from served fields`;
     }
   }
   const base = { payto, seller, terms, blockHeight, ...outputPlan ? { outputPlan } : {} };
   if (opts.servedOffer !== void 0 && opts.servedOffer !== null) {
     const so = opts.servedOffer;
-    const servedPayto = so?.want?.payto !== void 0 && so?.want?.payto !== null ? String(so.want.payto).toLowerCase() : "";
-    if (servedPayto && servedPayto !== payto)
+    if (so?.want?.payto === void 0 || so?.want?.payto === null)
+      return { ok: false, trust: "verified", reason: "the served offer is missing want.payto (the payment recipient) - pass the resolver's full offer object, or omit servedOffer", ...base };
+    if (String(so.want.payto).toLowerCase() !== payto)
       return { ok: false, trust: "verified", reason: "the served payment recipient doesn't match the offer's on-chain author/record", ...base };
-    if (so?.seller !== void 0 && so?.seller !== null && String(so.seller).toLowerCase() !== seller)
+    if (so?.seller === void 0 || so?.seller === null)
+      return { ok: false, trust: "verified", reason: "the served offer is missing seller (the rebate recipient) - pass the resolver's full offer object, or omit servedOffer", ...base };
+    if (String(so.seller).toLowerCase() !== seller)
       return { ok: false, trust: "verified", reason: "the served seller doesn't match the offer's on-chain author (a lying resolver may be redirecting your payment)", ...base };
     if (bindOfferTerms(opts.servedOffer, terms, { give: true, wantType: true }))
       return { ok: false, trust: "verified", reason: "the served terms don't match the offer's on-chain record (fee, rebate, partial sizing, the give, or the want type - a lying resolver could mis-size or re-route the fill, redirecting or burning your payment)", ...base };
+    if (isTokenWant(offerRec.want) && (String(so?.want?.ticker) !== String(offerRec.want.ticker) || String(so?.want?.amount) !== String(offerRec.want.amount)))
+      return { ok: false, trust: "verified", reason: "the served want ticker/amount don't match the offer's on-chain record (a lying resolver could bait-and-switch the token price)", ...base };
   }
   if (sumsMismatch) return { ok: false, trust: "verified", reason: sumsMismatch, ...base };
   return { ok: true, trust: "verified", ...base };
@@ -408,6 +283,13 @@ var DEFAULT_SPV_CHECKPOINT = { height: 38142, hash: "0x00000000000140f023cc0ee14
 var DEFAULT_CAIRN = "https://cairn-substrate.com";
 var SPV_HTTP_TIMEOUT_MS = 15e3;
 var SPV_HTTP_MAX_RETRIES = 4;
+var SPV_MAX_BATCH_BYTES = 2 * 1024 * 1024;
+var SPV_TRANSIENT_RE = /\b(429|50[0-9]|timeout|timed out|abort|aborted|headers|non-dense|failed to fetch|networkerror|load failed)\b/i;
+var SPV_TRANSIENT_JSON_RE = /unexpected (token|end)|json/i;
+var spvIsTransient = (e) => {
+  const msg = String(e?.message || e);
+  return SPV_TRANSIENT_RE.test(msg) || SPV_TRANSIENT_JSON_RE.test(msg);
+};
 var spvSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var spvRetryDelayMs = (attempt, retryAfterSecs) => Math.min(4e3, Math.max(700 * (attempt + 1), retryAfterSecs * 1e3));
 var Cairn = class {
@@ -423,7 +305,10 @@ var Cairn = class {
   cairnHttp;
   // Lazily-seeded SPV light client + its checkpoint (audit M3 — PoW-verified header source).
   _spvLight = null;
-  _spvSeeded = false;
+  // MF-14: the in-flight seed promise. Concurrent first callers share ONE seed instead of racing two
+  // syncFromCheckpoint calls onto the same client (the loser would hit "seedTrusted must be called on a
+  // fresh client"). Cleared when the seed settles; a failure leaves no cached state, so the next call retries.
+  _spvSeedInflight = null;
   _spvCp;
   // W12: the cairn base the SPV header-batch provider fetches /api/headers from (same base the rest of the SDK uses).
   _cairnBase;
@@ -448,7 +333,7 @@ var Cairn = class {
       headerMerkleAt: (h) => this.verifiedHeaderMerkleAt(h)
     });
     this.content = new ContentClient({ swarm: swarmHttp, indexer: indexerHttp, cairn: this.cairnHttp });
-    this.registry = new RegistryClient({ baseUrl: indexer, fetch });
+    this.registry = new RegistryClient(indexerHttp);
     this.names = new NamesClient(this.cairnHttp);
   }
   /**
@@ -458,44 +343,90 @@ var Cairn = class {
    * checkpoint (can't verify backward) or if verification fails — the IndexerClient then degrades
    * to the honest "proof-consistent" instead of over-claiming "verified-inclusion". The verified
    * header chain is cached across calls; the first call near tip syncs the post-checkpoint span.
+   * MF-03: a STRUCTURAL forward-sync break (a reorg orphaned the cached tip) reseeds ONCE via
+   * withSpvReseed. RESIDUAL: a height at or below the cached tip answers from the cached branch with
+   * NO network touch, so a tx in a reorg-orphaned block can still read "verified-inclusion" until a
+   * read PAST the tip trips the reseed; this closes the permanent post-reorg brick, not reorg-blindness.
    */
   async verifiedHeaderMerkleAt(height) {
     if (!Number.isInteger(height) || height < this._spvCp.height)
       throw new Error(`height ${height} is below the SPV checkpoint ${this._spvCp.height} (cannot PoW-verify backward)`);
+    return this.withSpvReseed(async (lc) => {
+      const haveTo = lc.baseHeight + lc.chain.length - 1;
+      if (haveTo < height) await lc.sync(height);
+      const vh = lc.chain[height - lc.baseHeight];
+      if (!vh) throw new Error(`light client has no verified header at ${height}`);
+      return String(vh.header.merkle);
+    });
+  }
+  // MF-03: run an SPV read; on a STRUCTURAL failure (a reorg orphaned our cached tip: broken
+  // prev-link / bad PoW / hash mismatch) reseed ONCE from the pinned checkpoint into a LOCAL fresh
+  // client, retry the read on it, and commit the fresh client ONLY when both succeed (never null
+  // this._spvLight first - the wallet G8 lesson, same shape as the MF-14 seed). A TRANSIENT failure
+  // (rate limit / gateway / timeout / non-dense / CF 200-HTML) keeps the cache and rethrows: wiping
+  // on those turns one /api/headers 429 into a reseed storm (DOS-HDR-3). A second structural
+  // failure propagates fail-closed; there is no loop.
+  // RESIDUAL (recorded, not closed): heights at or below the cached tip answer from the cached
+  // branch with NO network touch, so after a reorg "verified-inclusion" can still be over-claimed
+  // for a tx in an orphaned block until some read past the tip trips this reseed. This fix closes
+  // the permanent-brick leg only.
+  async withSpvReseed(op) {
     const lc = await this.seededSpvLight();
-    const haveTo = lc.baseHeight + lc.chain.length - 1;
-    if (haveTo < height) await lc.sync(height);
-    const vh = lc.chain[height - lc.baseHeight];
-    if (!vh) throw new Error(`light client has no verified header at ${height}`);
-    return String(vh.header.merkle);
+    try {
+      return await op(lc);
+    } catch (e) {
+      if (spvIsTransient(e)) throw e;
+      const fresh = await this.seedFreshSpvLight();
+      const out = await op(fresh);
+      this._spvLight = fresh;
+      return out;
+    }
   }
-  /** The PoW-verifying SPV light client, seeded ONCE from the pinned checkpoint (shared by the M3 header-merkle
-   *  bind and the F13 offer pre-verify). Reused across calls; the first call near tip syncs the post-checkpoint span. */
-  async seededSpvLight() {
-    if (!this._spvLight) this._spvLight = new LightClient({
+  // Build + seed + tip-advance a FRESH light client into a LOCAL. Never touches this._spvLight:
+  // the caller commits the result only on success (MF-14; the wallet G8 posture - never null or
+  // dirty the shared field while an attempt is in flight).
+  async seedFreshSpvLight() {
+    const lc = new LightClient({
       client: this.chain.client,
       checkpoints: { [this._spvCp.height]: this._spvCp.hash },
       headersBatchProvider: (from, count) => this.fetchHeadersBatch(from, count)
     });
-    if (!this._spvSeeded) {
-      await this._spvLight.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
-      try {
-        const tipHeight = Number((await this.chain.tip()).height);
-        const have = this._spvLight.baseHeight + this._spvLight.chain.length - 1;
-        if (Number.isFinite(tipHeight) && tipHeight > have) await this._spvLight.sync(tipHeight);
-      } catch {
-      }
-      this._spvSeeded = true;
+    await lc.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
+    try {
+      const tipHeight = Number((await this.chain.tip()).height);
+      const have = lc.baseHeight + lc.chain.length - 1;
+      if (Number.isFinite(tipHeight) && tipHeight > have) await lc.sync(tipHeight);
+    } catch {
+    }
+    return lc;
+  }
+  /** The PoW-verifying SPV light client, seeded from the pinned checkpoint and cached across calls
+   *  (shared by the M3 header-merkle bind and the F13 offer pre-verify). The client is committed to
+   *  the field ONLY after a fully successful seed (MF-14): a failed seed leaves NO cached state, so
+   *  the next call retries on a fresh client instead of wedging on "seedTrusted must be called on a
+   *  fresh client". Concurrent first callers share ONE in-flight seed. Re-seeded only when a
+   *  structural (reorg) break is detected, see withSpvReseed. */
+  seededSpvLight() {
+    if (this._spvLight) return Promise.resolve(this._spvLight);
+    if (!this._spvSeedInflight) {
+      this._spvSeedInflight = this.seedFreshSpvLight().then((lc) => {
+        this._spvLight = lc;
+        return lc;
+      }).finally(() => {
+        this._spvSeedInflight = null;
+      });
     }
-    return this._spvLight;
+    return this._spvSeedInflight;
   }
   /**
    * W12 batch header transport for the checkpoint..tip forward sync, backed by the cairn server's
    * `/api/headers/:from/:count`. Carries ZERO trust: the LightClient re-verifies every header's PoW /
    * prev-link / LWMA, so a forged or stale row fails closed and retrying transport proves nothing new.
    * Retry budget: a 429 (per-IP header budget) or 502/503 (a height past the lagging indexer, or the
-   * server's 10s deadline) is a transient data-availability hiccup; back off (honouring Retry-After) a
-   * bounded number of times, then THROW so `sync()` fails closed. A non-dense range is rejected.
+   * server's 10s deadline), a transport/timeout error, or a body-read fault (an oversize stream past the
+   * SPV_MAX_BATCH_BYTES cap, or a non-JSON 200 body such as a CF interstitial) is a transient
+   * data-availability hiccup; back off (honouring Retry-After) a bounded number of times, then THROW so
+   * `sync()` fails closed. A non-dense range is rejected terminally (never retried).
    *
    * B7d / F6 DEPENDENCY: `/api/headers` serves no Access-Control-Allow-Origin today (`corsPublic` is
    * mounted on `/explorer/api`, `/trade/api` and `/api/rpc`, not here). A SAME-ORIGIN dApp (hosted on the
@@ -510,10 +441,14 @@ var Cairn = class {
     const url = `${this._cairnBase}/api/headers/${from}/${count}`;
     for (let attempt = 0; ; attempt++) {
       let res;
+      let parsed;
       const ctrl = new AbortController();
       const timer = setTimeout(() => ctrl.abort(), SPV_HTTP_TIMEOUT_MS);
       try {
         res = await doFetch(url, { signal: ctrl.signal });
+        if (res.ok) {
+          parsed = JSON.parse(new TextDecoder().decode(await readCapped(res, SPV_MAX_BATCH_BYTES)));
+        }
       } catch (e) {
         if (attempt >= SPV_HTTP_MAX_RETRIES) throw e;
         await spvSleep(spvRetryDelayMs(attempt, 0));
@@ -522,7 +457,7 @@ var Cairn = class {
         clearTimeout(timer);
       }
       if (res.ok) {
-        const rows = (await res.json())?.headers;
+        const rows = parsed?.headers;
         if (!Array.isArray(rows) || rows.length !== count) throw new Error(`/api/headers: non-dense range (${from}/${count})`);
         return rows.map((r) => ({ header: r.header, hash: r.hash }));
       }
@@ -546,10 +481,14 @@ var Cairn = class {
    * This is best-effort corroboration, NOT the payment-grade boundary: the Cairn Wallet's OWN on-device
    * fill-SPV (0.2.60+, fails-closed before signing) is that. A dApp settling real value should still clear this
    * before building `outputs`, so it never hands the wallet a payment a lying resolver would redirect.
+   *
+   * Pass opts.pay (the CSD base units you intend to pay) to receive the PROVEN outputPlan for a whole fill of a
+   * non-partial offer, and opts.plannedOutputs to bind your planned per-address sums to it before signing; build
+   * EXACTLY the outputPlan, never resolver-served outputs.
    */
-  async verifyOfferForFill(offerId, servedOffer) {
-    const light = await this.seededSpvLight();
-    return preverifyOffer({ light, client: this.chain.client, offerId, servedOffer });
+  async verifyOfferForFill(offerId, servedOffer, opts) {
+    const light = { verifyTxInclusion: (txidHex) => this.withSpvReseed((lc) => lc.verifyTxInclusion(txidHex)) };
+    return preverifyOffer({ light, client: this.chain.client, offerId, servedOffer, pay: opts?.pay, plannedOutputs: opts?.plannedOutputs });
   }
   /**
    * Detect + connect the Cairn Wallet (browser only). Wires the wallet into