@inversealtruism/cairn-sdk 0.3.2 → 0.4.1

package/dist/index.cjs

@@ -46,16 +46,21 @@ __export(index_exports, {
   discoverProviders: () => discoverProviders,
   errorCode: () => errorCode,
   feeBpsAt: () => import_cairnx_core2.feeBpsAt,
+  fillEndorsement: () => import_cairnx_core2.fillEndorsement,
+  fillIsSafe: () => import_cairnx_core2.fillIsSafe,
+  fillOutputPlan: () => import_cairnx_core2.fillOutputPlan,
   getWallet: () => getWallet,
   isInstalled: () => isInstalled,
   mapProviderError: () => mapProviderError,
   mapSubmitResultError: () => mapSubmitResultError,
-  preverifyOffer: () => preverifyOffer
+  preverifyOffer: () => preverifyOffer,
+  previewFill: () => import_cairnx_core2.previewFill,
+  requiredFillOutputs: () => import_cairnx_core2.requiredFillOutputs
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.3.2";
+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. */
@@ -147,7 +152,7 @@ var SubmitInFlightError = class extends CairnError {
     this.txid = txid3;
   }
 };
-var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+var NATIVE_CODES = /* @__PURE__ */ new Set(["FIRST_PARTY_ONLY", "RATE_LIMITED", "FORBIDDEN", "INTERNAL"]);
 var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN"]);
 var NESTED_TERMINAL = /* @__PURE__ */ new Set([
   "FILL_UNSAFE",
@@ -889,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.
@@ -911,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() {
@@ -1015,6 +1033,7 @@ var NamesClient = class {
 };
 
 // src/connect.ts
+var DEFAULT_PROVIDER_TIMEOUT_MS = 10 * 6e4;
 function discoverProviders(opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 1e3;
   return new Promise((resolve) => {
@@ -1094,8 +1113,27 @@ function unwrapWrite(reply) {
 var WalletConnection = class {
   provider;
   _addr = null;
-  constructor(provider) {
+  /** B7c: per-call provider timeout (ms). GENEROUS by default so it never rejects an in-flight human
+   *  approval; 0 disables it. Every provider call (writes especially) races against it. */
+  _timeoutMs;
+  constructor(provider, opts = {}) {
     this.provider = provider;
+    this._timeoutMs = opts.timeoutMs ?? DEFAULT_PROVIDER_TIMEOUT_MS;
+  }
+  // B7c: race a provider call against the per-call timeout. On timeout, throw a fail-closed CairnError
+  // (retryable:false: a write may already have reached the wallet, so never invite a blind auto-retry). The
+  // genuine wallet resolves quickly once the user acts; this only fires on a truly hung/absent response.
+  call(op, label) {
+    const ms = this._timeoutMs;
+    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([invoke(), timeout]).finally(() => clearTimeout(timer));
   }
   /** The wallet's version string (e.g. "0.2.x"). */
   get version() {
@@ -1107,13 +1145,13 @@ var WalletConnection = class {
   }
   /** Request connection. First time per origin prompts the user; afterwards may be silent. */
   async connect() {
-    const { addr } = unwrap(await this.provider.connect());
+    const { addr } = unwrap(await this.call(() => this.provider.connect(), "connect"));
     this._addr = addr;
     return addr;
   }
   /** Get the connected address (does not force a new connection prompt if already consented). */
   async getAddress() {
-    const { addr } = unwrap(await this.provider.getAddress());
+    const { addr } = unwrap(await this.call(() => this.provider.getAddress(), "getAddress"));
     this._addr = addr;
     return addr;
   }
@@ -1126,7 +1164,7 @@ var WalletConnection = class {
     if (typeof this.provider.signIn !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet does not expose signIn()"));
     }
-    return Promise.resolve(this.provider.signIn()).then(unwrap);
+    return this.call(() => this.provider.signIn(), "signIn").then(unwrap);
   }
   /**
    * Audience-bound "Sign in with CSD" (SIWC) — the secure, replay-resistant third-party login.
@@ -1142,7 +1180,7 @@ var WalletConnection = class {
     if (typeof this.provider.signInWithCsd !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet predates Sign-in-with-CSD \u2014 ask the user to update the Cairn Wallet"));
     }
-    return Promise.resolve(this.provider.signInWithCsd(params)).then(unwrap);
+    return this.call(() => this.provider.signInWithCsd(params), "signInWithCsd").then(unwrap);
   }
   /** True if this wallet supports audience-bound SIWC (safe to call `signInWithCsd`). */
   get supportsSiwc() {
@@ -1152,7 +1190,7 @@ var WalletConnection = class {
   async getCapabilities() {
     if (typeof this.provider.getCapabilities !== "function") return null;
     try {
-      return await this.provider.getCapabilities();
+      return await this.call(() => this.provider.getCapabilities(), "getCapabilities");
     } catch {
       return null;
     }
@@ -1168,24 +1206,40 @@ 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"));
     }
-    return Promise.resolve(this.provider.fillOffer(params)).then(unwrapWrite);
+    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 [];
-    return unwrap(await this.provider.getPermissions());
+    return unwrap(await this.call(() => this.provider.getPermissions(), "getPermissions"));
   }
   /** Explicitly request permission to see the address (prompts, like connect). */
   requestPermissions() {
     if (typeof this.provider.requestPermissions !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet predates requestPermissions \u2014 use connect()"));
     }
-    return Promise.resolve(this.provider.requestPermissions()).then(unwrap);
+    return this.call(() => this.provider.requestPermissions(), "requestPermissions").then(unwrap);
   }
   /** Revoke THIS origin's own access (silent). Returns { revoked }. Safe no-op on older wallets. */
   async revokePermissions() {
     if (typeof this.provider.revokePermissions !== "function") return { revoked: false };
-    return unwrap(await this.provider.revokePermissions());
+    return unwrap(await this.call(() => this.provider.revokePermissions(), "revokePermissions"));
   }
   /**
    * Subscribe to provider events. `accountsChanged` fires with `[]` when this site loses access
@@ -1201,26 +1255,26 @@ var WalletConnection = class {
   }
   /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
   send(params) {
-    return Promise.resolve(this.provider.send(params)).then(unwrapWrite);
+    return this.call(() => this.provider.send(params), "send").then(unwrapWrite);
   }
   /** Low-level Propose (always prompts). Prefer `cairn.board.propose()` which computes the hash/uri/expiry. */
   propose(params) {
-    return Promise.resolve(this.provider.propose(params)).then(unwrapWrite);
+    return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
   }
   /** Attest/support a proposal (always prompts). */
   attest(params) {
-    return Promise.resolve(this.provider.attest(params)).then(unwrapWrite);
+    return this.call(() => this.provider.attest(params), "attest").then(unwrapWrite);
   }
   /** Seal a commit-reveal claim (always prompts; salt stays inside the wallet). */
   sealClaim(params) {
-    return Promise.resolve(this.provider.sealClaim(params)).then(unwrapWrite);
+    return this.call(() => this.provider.sealClaim(params), "sealClaim").then(unwrapWrite);
   }
   /** Reveal a previously sealed claim by its sealing txid (always prompts). */
   revealClaim(txid3) {
     if (typeof txid3 !== "string" || !txid3) {
       return Promise.reject(new UnsupportedMethodError("revealClaim requires the sealing txid"));
     }
-    return Promise.resolve(this.provider.revealClaim(txid3)).then(unwrapWrite);
+    return this.call(() => this.provider.revealClaim(txid3), "revealClaim").then(unwrapWrite);
   }
 };
 async function getWallet(opts = {}) {
@@ -1239,6 +1293,23 @@ var import_cairnx_core2 = require("@inversealtruism/cairnx-core");
 var ADDR = /^0x[0-9a-f]{40}$/;
 var HASH = /^0x[0-9a-f]{64}$/;
 var COINBASE = "0x" + "00".repeat(32);
+function bindPlannedSums(planned, proven) {
+  const provenMap = new Map(proven.map((o) => [o.to.toLowerCase(), o.value]));
+  const plannedMap = /* @__PURE__ */ new Map();
+  try {
+    for (const [a, v] of Object.entries(planned)) {
+      const k = String(a).toLowerCase();
+      plannedMap.set(k, (plannedMap.get(k) ?? 0n) + BigInt(v));
+    }
+  } catch {
+    return "invalid plannedOutputs (amounts must be base-unit integers)";
+  }
+  for (const k of /* @__PURE__ */ new Set([...provenMap.keys(), ...plannedMap.keys()])) {
+    if ((provenMap.get(k) ?? 0n) !== (plannedMap.get(k) ?? 0n))
+      return `your planned payment doesn't match the proven fill outputs (${k}: planned ${(plannedMap.get(k) ?? 0n).toString()}, proven ${(provenMap.get(k) ?? 0n).toString()}) - refusing (an overpay past the proven amount is unrecoverable, and a missing or low leg is a doomed underpay)`;
+  }
+  return void 0;
+}
 async function provenAuthor(client, provenTx) {
   const in0 = provenTx.inputs?.[0];
   if (!in0 || String(in0.prevTxid).toLowerCase() === COINBASE && Number(in0.vout) === 4294967295) return null;
@@ -1283,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);
@@ -1294,27 +1367,56 @@ async function preverifyOffer(opts) {
     return { ok: false, trust: "unverified", reason: "the offer record doesn't match the on-chain (merkle-proven) commitment" };
   const seller = await provenAuthor(opts.client, provenTx);
   if (!seller) return { ok: false, trust: "verified", transient: true, blockHeight, reason: "couldn't prove the offer's on-chain author yet; the chain view may be catching up, try again" };
+  const offerRec = rec;
   const w = rec.want ?? {};
   const payto = w.payto && ADDR.test(String(w.payto).toLowerCase()) ? String(w.payto).toLowerCase() : seller;
-  const terms = {
-    height: blockHeight,
-    feeBps: (0, import_cairnx_core2.feeBpsAt)(blockHeight),
-    value: w.value !== void 0 ? String(w.value) : void 0,
-    taker: rec.taker !== void 0 ? String(rec.taker).toLowerCase() : void 0,
-    bid: rec.bid !== void 0 ? String(rec.bid).toLowerCase() : void 0,
-    min: rec.min !== void 0 ? String(rec.min) : void 0
-  };
-  const base = { payto, seller, terms, blockHeight };
+  const terms = (0, import_cairnx_core2.provenOfferTerms)(offerRec, blockHeight);
+  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, payto },
+      taker: offerRec.taker,
+      bid: offerRec.bid,
+      status: typeof servedStatus === "string" ? servedStatus : "open",
+      expiresEpoch: 0,
+      height: blockHeight,
+      feeBps: terms.feeBps
+    };
+    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))
-      return { ok: false, trust: "verified", reason: "the served fee/rebate/partial terms don't match the offer's on-chain record (a lying resolver could mis-size the fill, causing a rejected fill after 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 };
 }
 
@@ -1323,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;
@@ -1375,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);
   };
 };
@@ -1410,6 +1524,17 @@ var CairnController = class {
 // src/index.ts
 var DEFAULT_SPV_CHECKPOINT = { height: 38142, hash: "0x00000000000140f023cc0ee1457a40833f2fcb4de44291b9d373e50f17b97232" };
 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 {
   config;
   chain;
@@ -1423,8 +1548,13 @@ 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;
   constructor(config = {}) {
     this.config = config;
     const fetch = config.fetch;
@@ -1433,6 +1563,7 @@ var Cairn = class {
     const rpc = config.baseUrls?.rpc ?? `${cairn}/api/rpc`;
     const indexer = (config.baseUrls?.indexer ?? `${cairn}/explorer/api`).replace(/\/+$/, "");
     this.cairnHttp = new Http({ baseUrl: cairn, fetch, timeoutMs });
+    this._cairnBase = cairn;
     const indexerHttp = new Http({ baseUrl: indexer, fetch, timeoutMs });
     const swarmHttp = config.baseUrls?.swarm ? new Http({ baseUrl: config.baseUrls.swarm.replace(/\/+$/, ""), fetch, timeoutMs }) : void 0;
     this._spvCp = config.spvCheckpoint ?? DEFAULT_SPV_CHECKPOINT;
@@ -1445,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);
   }
   /**
@@ -1455,26 +1586,132 @@ 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({ client: this.chain.client, checkpoints: { [this._spvCp.height]: this._spvCp.hash } });
-    if (!this._spvSeeded) {
-      await this._spvLight.syncFromCheckpoint(this._spvCp.height, this._spvCp.hash);
-      this._spvSeeded = true;
+    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)
+    });
+    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._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), 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
+   * cairn base) reaches it now; a CROSS-ORIGIN third-party dApp cannot until B7d adds the CORS mount and
+   * restarts the cairn service. This code is correct as written; it becomes reachable cross-origin only
+   * once B7d ships. This is a recorded dependency, not a blocker for authoring/testing.
+   */
+  async fetchHeadersBatch(from, count) {
+    const g = this.config.fetch ?? globalThis.fetch;
+    if (!g) throw new Error("No fetch available for SPV header sync - pass `fetch` in the SDK options.");
+    const doFetch = this.config.fetch ? this.config.fetch : g.bind(globalThis);
+    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));
+        continue;
+      } finally {
+        clearTimeout(timer);
+      }
+      if (res.ok) {
+        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 }));
+      }
+      if ((res.status === 429 || res.status === 502 || res.status === 503) && attempt < SPV_HTTP_MAX_RETRIES) {
+        res.body?.cancel?.().catch(() => {
+        });
+        await spvSleep(spvRetryDelayMs(attempt, Number(res.headers.get("retry-after")) || 0));
+        continue;
+      }
+      throw new Error(`/api/headers ${res.status}`);
     }
-    return this._spvLight;
   }
   /**
    * F13 — corroborate an offer ON-CHAIN before building a `fillOffer` payment's `outputs`. Merkle-proves the
@@ -1487,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
@@ -1539,9 +1780,14 @@ var Cairn = class {
   discoverProviders,
   errorCode,
   feeBpsAt,
+  fillEndorsement,
+  fillIsSafe,
+  fillOutputPlan,
   getWallet,
   isInstalled,
   mapProviderError,
   mapSubmitResultError,
-  preverifyOffer
+  preverifyOffer,
+  previewFill,
+  requiredFillOutputs
 });