@inversealtruism/cairn-sdk 0.4.0 → 0.4.1

package/dist/controller.d.ts

@@ -12,6 +12,7 @@ interface CairnControllerOptions extends DetectOptions {
 declare class CairnController {
     private state;
     private conn;
+    private epoch;
     private readonly listeners;
     private readonly getWalletFn;
     private readonly detectOpts;
@@ -28,7 +29,9 @@ declare class CairnController {
     private detach;
     /** Detect + connect (prompts the user the first time per origin). Resolves the connected address. */
     connect: () => Promise<string>;
-    /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort). */
+    /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort).
+     *  Local teardown is IMMEDIATE and unconditional; the wallet-side revoke happens after, so a hung
+     *  provider can never hold a torn-down session in "connected". */
     disconnect: () => Promise<void>;
     /** Audience-bound sign-in (must connect() first). Returns the signed artifact to verify server-side. */
     signInWithCsd: (params: SiwcParams) => Promise<SiwcResult>;

package/dist/controller.js

@@ -1,8 +1,8 @@
 import {
   CairnController
-} from "./chunk-GTTLMWGY.js";
-import "./chunk-RKR3JMIA.js";
-import "./chunk-MREZG2HN.js";
+} from "./chunk-QATE6AIP.js";
+import "./chunk-PIPN6FSA.js";
+import "./chunk-ERBT4DFD.js";
 export {
   CairnController
 };

package/dist/index.cjs

@@ -60,7 +60,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.4.1";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -894,17 +894,20 @@ function normalizeHash(hash) {
 var import_csd_registry = require("@inversealtruism/csd-registry");
 var import_csd_registry2 = require("@inversealtruism/csd-registry");
 var RegistryClient = class {
-  src;
-  constructor(opts) {
-    this.src = { baseUrl: opts.baseUrl.replace(/\/+$/, ""), fetch: opts.fetch };
+  http;
+  /** Accepts the SDK's hardened Http directly (the Cairn facade path) or the legacy
+   *  { baseUrl, fetch } options (kept for direct constructors; they now get the same
+   *  hardened transport, built internally). */
+  constructor(src) {
+    this.http = src instanceof Http ? src : new Http({ baseUrl: src.baseUrl, fetch: src.fetch });
   }
   /** Discover ranked content/pin gateways (GET /registry/gateways). */
   gateways() {
-    return (0, import_csd_registry.discoverGateways)(this.src);
+    return this.http.getJson("/registry/gateways");
   }
   /** Discover ranked libp2p peers (GET /registry/peers). */
   peers() {
-    return (0, import_csd_registry.discoverPeers)(this.src);
+    return this.http.getJson("/registry/peers");
   }
   /**
    * Resolve a handle → identity (GET /identity/:handle). Returns null if unresolved.
@@ -916,12 +919,22 @@ var RegistryClient = class {
    * source (the wallet's namespv union cure). Treat `verified` here as a hint, not a guarantee.
    */
   resolveName(handle) {
-    return (0, import_csd_registry.resolveName)(this.src, handle);
+    return this.getOr404Null(`/identity/${encodeURIComponent(handle)}`);
   }
   /** Reverse-resolve an address → identity (GET /address/:addr/identity).
    *  ⚠ Same indexer-trust caveat as resolveName — `verified` is the indexer's claim, not a client proof. */
   reverseName(address) {
-    return (0, import_csd_registry.reverseName)(this.src, address);
+    return this.getOr404Null(`/address/${encodeURIComponent(address)}/identity`);
+  }
+  // MF-12: 404 → null (the preserved csd-registry contract for both name resolvers); every other
+  // failure rethrows the typed HttpError/CairnError the hardened Http raises.
+  async getOr404Null(path) {
+    try {
+      return await this.http.getJson(path);
+    } catch (e) {
+      if (e instanceof HttpError && e.status === 404) return null;
+      return Promise.reject(e);
+    }
   }
   /** The deterministic, client-side resolvers (recompute from raw ChainRecord[]). */
   get fromRecords() {
@@ -1112,12 +1125,15 @@ var WalletConnection = class {
   // genuine wallet resolves quickly once the user acts; this only fires on a truly hung/absent response.
   call(op, label) {
     const ms = this._timeoutMs;
-    if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve(op());
+    const invoke = () => new Promise((resolve) => {
+      resolve(op());
+    });
+    if (!Number.isFinite(ms) || ms <= 0) return invoke();
     let timer;
     const timeout = new Promise((_, reject) => {
       timer = setTimeout(() => reject(new CairnError(`the wallet did not respond to ${label} within ${ms}ms`, { retryable: false })), ms);
     });
-    return Promise.race([Promise.resolve(op()), timeout]).finally(() => clearTimeout(timer));
+    return Promise.race([invoke(), timeout]).finally(() => clearTimeout(timer));
   }
   /** The wallet's version string (e.g. "0.2.x"). */
   get version() {
@@ -1190,8 +1206,24 @@ var WalletConnection = class {
     if (typeof this.provider.fillOffer !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
     }
+    this.adviseFillSpvCapability();
     return this.call(() => this.provider.fillOffer(params), "fillOffer").then(unwrapWrite);
   }
+  // P75-5 MF-10: ONE capability advisory per connection. The wallet's on-device fill-SPV (0.2.60+) is the
+  // payment-grade fill boundary; when the provider SELF-REPORTS an older version, warn the integrator once
+  // and STILL RELAY. WARN, NEVER BLOCK: a hard version gate would decline honest fills (version strings are
+  // spoofable and unparseable forks exist), and the wallet itself is the enforcement point. Reads only the
+  // sync `provider.version`; never an awaited getCapabilities() round-trip on the fill hot path. An
+  // unparseable version never warns (no false alarms).
+  _fillSpvAdvised = false;
+  adviseFillSpvCapability() {
+    if (this._fillSpvAdvised) return;
+    this._fillSpvAdvised = true;
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(this.provider?.version ?? ""));
+    if (!m) return;
+    const below = Number(m[1]) === 0 && (Number(m[2]) < 2 || Number(m[2]) === 2 && Number(m[3]) < 60);
+    if (below) console.warn(`[cairn-sdk] this Cairn Wallet (v${m[0]}) predates the on-device fill-SPV boundary (cairn-wallet 0.2.60+). The fill proceeds; suggest a wallet update for payment-grade offer verification.`);
+  }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
   async getPermissions() {
     if (typeof this.provider.getPermissions !== "function") return [];
@@ -1322,6 +1354,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) !== import_cairnx_core2.DOMAIN)
+    return { ok: false, trust: "unverified", reason: `the offer tx is not a ${import_cairnx_core2.DOMAIN} Propose (wrong settlement domain)` };
   let rec;
   try {
     rec = (0, import_cairnx_core2.parseRecord)(app.uri, incl.appPayloadHash);
@@ -1340,37 +1374,47 @@ async function preverifyOffer(opts) {
   let outputPlan;
   let sumsMismatch;
   if (opts.pay !== void 0 && opts.pay !== null && !(0, import_cairnx_core2.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 = (0, import_cairnx_core2.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 = (0, import_cairnx_core2.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 ((0, import_cairnx_core2.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 ((0, import_cairnx_core2.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 };
@@ -1381,6 +1425,9 @@ var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error:
 var CairnController = class {
   state = DISCONNECTED;
   conn = null;
+  // MF-15: connect/disconnect generation token. disconnect() bumps it; a connect() whose await straddled
+  // the bump must never commit "connected" over the torn-down session (a zombie null-connection session).
+  epoch = 0;
   listeners = /* @__PURE__ */ new Set();
   getWalletFn;
   detectOpts;
@@ -1433,34 +1480,43 @@ var CairnController = class {
   }
   /** Detect + connect (prompts the user the first time per origin). Resolves the connected address. */
   connect = async () => {
+    const epoch = this.epoch;
     this.setState({ status: "connecting", error: null });
     try {
-      if (!this.conn) {
-        this.conn = await this.getWalletFn(this.detectOpts);
-        this.conn.on("accountsChanged", this.onAccounts);
-        this.conn.on("disconnect", this.onDisconnect);
+      let conn = this.conn;
+      if (!conn) {
+        conn = await this.getWalletFn(this.detectOpts);
+        if (epoch !== this.epoch) throw new Error("connection was torn down while connecting - call connect() again");
+        conn.on("accountsChanged", this.onAccounts);
+        conn.on("disconnect", this.onDisconnect);
+        this.conn = conn;
       }
-      const addr = await this.conn.connect();
+      const addr = await conn.connect();
+      if (epoch !== this.epoch) throw new Error("connection was torn down while awaiting approval - call connect() again");
       this.setState({ status: "connected", account: addr, error: null });
       return addr;
     } catch (e) {
-      this.setState({ status: "disconnected", account: null, error: e?.message ?? String(e) });
+      if (epoch === this.epoch) this.setState({ status: "disconnected", account: null, error: e?.message ?? String(e) });
       throw e;
     }
   };
-  /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort). */
+  /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort).
+   *  Local teardown is IMMEDIATE and unconditional; the wallet-side revoke happens after, so a hung
+   *  provider can never hold a torn-down session in "connected". */
   disconnect = async () => {
-    try {
-      await this.conn?.revokePermissions();
-    } catch {
-    }
+    this.epoch++;
+    const conn = this.conn;
     this.detach();
     this.conn = null;
     this.setState({ status: "disconnected", account: null, error: null });
+    try {
+      await conn?.revokePermissions();
+    } catch {
+    }
   };
   /** Audience-bound sign-in (must connect() first). Returns the signed artifact to verify server-side. */
   signInWithCsd = (params) => {
-    if (!this.conn) return Promise.reject(new Error("call connect() before signInWithCsd()"));
+    if (!this.conn || this.state.status !== "connected") return Promise.reject(new Error("call connect() before signInWithCsd()"));
     return this.conn.signInWithCsd(params);
   };
 };
@@ -1470,6 +1526,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 {
@@ -1485,7 +1548,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;
@@ -1510,7 +1576,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);
   }
   /**
@@ -1520,44 +1586,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);
-  }
-  /** 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 import_csd_light.LightClient({
+    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;
+    }
+  }
+  // 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 import_csd_light.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 this._spvLight;
+    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._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
@@ -1572,10 +1684,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));
@@ -1584,7 +1700,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 }));
       }
@@ -1608,10 +1724,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

package/dist/index.d.cts

@@ -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.