@inversealtruism/cairn-sdk 0.4.6 → 0.5.0

package/README.md

@@ -6,9 +6,8 @@ The **Compute Substrate dApp kit:** one cohesive toolkit for building apps on CS
 |---|---|
 | `cairn.wallet` | Connect the **Cairn Wallet**, sign things (clear-signed approvals). The key never leaves the extension. |
 | `cairn.chain` | Node RPC + transaction builders + a verifying **light client** (re-exports the `csd-*` primitives). |
-| `cairn.board` | The signal **board** + work graph. Reads are public; writes are wallet-signed. |
 | `cairn.index` | The L2 **explorer/indexer**: REST + merkle proofs + live SSE/WS feeds. |
-| `cairn.content` | **Self-certifying content:** publish via the board, fetch with client-side verification. |
+| `cairn.content` | **Self-certifying content:** hash for an on-chain Propose, fetch with client-side verification. |
 | `cairn.registry` | L3 **peer / gateway / identity** resolution. |
 | `cairn.names` | **.csd names + CairnX reads:** name resolution, reverse/primary lookup, tokens, offers, bids, canonical state. |
 
@@ -24,21 +23,17 @@ import { Cairn } from "@inversealtruism/cairn-sdk";
 const cairn = new Cairn({ network: "mainnet" });   // defaults to cairn-substrate.com
 
 // reads need no wallet
-const top = await cairn.board.top({ domain: "csd:apps" });
 const tip = await cairn.chain.tip();
+const domains = await cairn.index.domains();
 
 // connect the user's wallet (browser): prompts once, then "connected"
 await cairn.connect();
 
-// publish a board item, signed by the user's wallet (clear-signed approval)
-const { txid } = await cairn.board.propose({
-  domain: "csd:apps",
-  title: "My dApp",
-  body: "Built with the Cairn SDK",
-});
+// a payment, signed by the user's wallet (clear-signed approval every time)
+const { txid } = await cairn.wallet!.send({ to: "0x…", amount: 100_000_000 }); // 1 CSD
 
-// watch it land, live
-cairn.index.streamAll({ onProposal: (e) => console.log("new proposal", e) });
+// watch the chain, live
+cairn.index.streamAll({ onBlock: (e) => console.log("new block", e) });
 ```
 
 ## How wallet connection works (and why it's safe)
@@ -62,9 +57,7 @@ try {
 
 ## API by namespace
 
-**`cairn.board`:** `top()/board({domain,window})`, `item(id)`, `domains()`, `quests()/quest(id)`, `profile(addr)`, `leaderboard()`, `network()/networkSeries()/miner(addr)`, `activity()`, `wall()`; writes `propose({domain,title,body,links?,fee?})`, `support(id,{score?,confidence?,fee?})`.
-
-**`cairn.index`:** `tipHeight()`, `block()/blockTxids()`, `tx()/txStatus()/txMerkleProof()`, `address()/addressTxs()/addressUtxo()`, `proposal()/attestations()`, `reputation()`, `registryPeers()/registryGateways()/identity()`, **`verifyInclusion(txid)`** (trust-minimized), `streamAll()/streamBlocks()/streamDomain()` (SSE), `subscribe()` (WS).
+**`cairn.index`:** `tipHeight()`, `block()/blockTxids()`, `tx()/txStatus()/txMerkleProof()`, `address()/addressTxs()/addressUtxo()`, `domains()/domainProposals(domain)`, `proposal()/attestations()`, `reputation()`, `registryPeers()/registryGateways()/identity()`, **`verifyInclusion(txid)`** (trust-minimized), `streamAll()/streamBlocks()/streamDomain()` (SSE), `subscribe()` (WS).
 
 **`cairn.names`:** `resolve(name)` (display-path name to address), `name(name)`/`nameHistory(name)`, `primary(addr)` (reverse lookup)/`namesOf(addr)`, `names()`, `tokens()/token(ticker)`, `offers()`, `bids()`, `state()` (the canonical CairnX state). Reads go through the public `/trade/api/cairnx/*` proxy; for payment-grade name resolution verify through the wallet or a replaying resolver, not a bare read (see `src/names.ts` header).
 
@@ -74,17 +67,17 @@ try {
 
 **`cairn.registry`:** `gateways()`, `peers()`, `resolveName(handle)`, `reverseName(addr)`, `.fromRecords` (deterministic local resolvers).
 
-Subpath imports are available for tree-shaking: `@inversealtruism/cairn-sdk/{connect,board,indexer,content,registry,chain}`.
+Subpath imports are available for tree-shaking: `@inversealtruism/cairn-sdk/{connect,indexer,content,registry,chain,controller,react}`.
 
 ## Examples
 
-- **`examples/read-only.mjs`:** runs today against live mainnet, no wallet, no build: `npm run test:live`. Demonstrates chain/board/indexer/registry reads + verified merkle inclusion + verified content fetch.
-- **`examples/hello-csd/`:** a no-framework browser dApp (connect → read board → publish → live feed). Build the bundle with `npm run build:example`, then serve the folder from **localhost** (the wallet injects there) with the Cairn Wallet installed.
+- **`examples/read-only.mjs`:** runs today against live mainnet, no wallet, no build: `npm run test:live`. Demonstrates chain/indexer/registry reads + verified merkle inclusion + verified content fetch.
+- **`examples/hello-csd/`:** a no-framework browser dApp (connect → read recent proposals → live feed). Build the bundle with `npm run build:example`, then serve the folder from **localhost** (the wallet injects there) with the Cairn Wallet installed.
 
 ## Trust model & honest limits
 
 - **Content is always verified client-side.** `cairn.content.get()` rejects bytes that don't hash to the requested `payloadHash`, an untrusted gateway can't serve tampered content.
-- **Merkle inclusion is trust-minimized, to the strength of your header source.** `verifyInclusion()` folds the proof and, when a header-merkle source is wired, cross-checks the root against it → `trustLevel: "verified-inclusion"`; otherwise `"proof-consistent"` (indexer trusted). That cross-check only means something against an *independent* header, so the default `Cairn` wiring enables it ONLY when your node RPC is a different origin than the indexer (the default same-origin proxy stays at `"proof-consistent"`, a single compromised server can't be cross-checked against itself). For full trust-minimization against a lying node too, supply a PoW-verifying `headerMerkleAt` (e.g. backed by `cairn.chain.light()`).
+- **Merkle inclusion is trust-minimized, to the strength of your header source.** `verifyInclusion()` folds the proof and cross-checks its root against a header merkle from `headerMerkleAt`. The default `Cairn` wiring backs that with a light client that PoW-verifies headers forward from a pinned checkpoint, so a match reads `trustLevel: "verified-inclusion"` with `included: true`. A header within 12 blocks of the light client's cached tip is first compared with the header the base serves at that height, so a block orphaned by a reorg stops counting; the hosted base edge-caches rows at or below its tip minus 6, so there this catches reorgs of up to 6 blocks. When no header can be verified (below the checkpoint, header source unreachable, no source configured) the result is `"proof-consistent"` with `included: false` and a `reason`: the indexer alone vouches for it. Gate on `included` or on `trustLevel === "verified-inclusion"`; they agree.
 - **Balances are RPC-trusted.** Headers don't commit to the UTXO set; balance reads trust the node/proxy (same as every light client).
 - **Indexer/swarm run behind the cairn proxy.** By default `cairn.index` and content resolution use the cairn server's hardened, read-only, rate-limited `/explorer/api` reverse proxy (no separate public indexer needed). **SSE works through it; `subscribe()` (WebSocket) needs a direct indexer endpoint:** set `baseUrls.indexer` to a private/localhost indexer for WS.
 - **The wallet injects on every site** (connect-anywhere shipped in 0.2.4x) behind a per-origin consent gate: a site sees nothing until the user approves the connection, and some request kinds stay first-party-only (the `FIRST_PARTY_ONLY` error code).
@@ -95,7 +88,7 @@ Subpath imports are available for tree-shaking: `@inversealtruism/cairn-sdk/{con
 new Cairn({
   network: "mainnet",
   baseUrls: {
-    cairn:   "https://cairn-substrate.com",        // board + /api/rpc proxy + /content origin
+    cairn:   "https://cairn-substrate.com",        // /api/rpc proxy + /api/headers + /content origin + names
     rpc:     "https://cairn-substrate.com/api/rpc", // node RPC (proxy)
     indexer: "https://cairn-substrate.com/explorer/api",
     swarm:   undefined,                             // optional direct swarm gateway
@@ -112,10 +105,9 @@ new Cairn({
 pnpm build && pnpm test         # unit (offline): error mapping, client paths, content+merkle verify
 pnpm test:e2e:read              # live reads vs mainnet + adversarial (free)
 pnpm test:e2e:wallet            # real extension + real connector under Xvfb: connect/consent/sign (free)
-pnpm test:e2e:write             # full pipeline incl. a real on-chain Propose+Attest (spends ~0.3 CSD)
 ```
 
-See [`test/e2e/README.md`](test/e2e/README.md) for coverage, requirements, and cost of each layer. The unit + live-read + wallet-connector suites are CI-friendly and free; the write suite needs a funded key and is opt-in.
+See [`test/e2e/README.md`](test/e2e/README.md) for coverage, requirements, and cost of each layer. All three suites are free; none spends CSD.
 
 ## License
 

package/dist/{chunk-FWTPXLGV.js → chunk-5RGFC2JR.js}

@@ -4,7 +4,7 @@ import {
   UnsupportedMethodError,
   mapProviderError,
   mapSubmitResultError
-} from "./chunk-ZFVE6MU7.js";
+} from "./chunk-OSPAN7GX.js";
 
 // src/connect.ts
 var DEFAULT_PROVIDER_TIMEOUT_MS = 10 * 6e4;
@@ -231,7 +231,7 @@ var WalletConnection = class {
   send(params) {
     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. */
+  /** Low-level Propose (always prompts). The caller computes the payload hash, uri and expiry epoch. */
   propose(params) {
     return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
   }

package/dist/{chunk-2HP3ZXBO.js → chunk-BL6VFALH.js}

@@ -1,6 +1,6 @@
 import {
   HttpError
-} from "./chunk-ZFVE6MU7.js";
+} from "./chunk-OSPAN7GX.js";
 
 // src/registry.ts
 import { fromRecords } from "@inversealtruism/csd-registry";
@@ -8,6 +8,26 @@ import { fromRecords } from "@inversealtruism/csd-registry";
 // src/http.ts
 var DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
 var ERR_TEXT_CAP = 8 * 1024;
+var MAX_RETRY_AFTER_MS = 6e4;
+function retryAfterMs(res) {
+  const secs = Number(res.headers.get("retry-after"));
+  return Number.isFinite(secs) && secs > 0 ? Math.min(secs * 1e3, MAX_RETRY_AFTER_MS) : 0;
+}
+var RetryWaitBudget = class {
+  left;
+  constructor(totalMs) {
+    this.left = totalMs;
+  }
+  /** The ms to sleep before the next attempt (`ownMs` is the caller's backoff, clipped to what is left), or
+   *  null when the server's hint exceeds the remaining budget. */
+  take(ownMs, serverMs) {
+    if (serverMs > this.left) return null;
+    const ms = Math.min(Math.max(ownMs, serverMs), this.left);
+    this.left -= ms;
+    return ms;
+  }
+};
+var HTTP_RETRY_WAIT_BUDGET_MS = 3e4;
 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})`);
@@ -56,9 +76,10 @@ var Http = class {
     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.maxBytes = Number.isFinite(opts.maxBytes) && opts.maxBytes >= 1 ? Math.floor(opts.maxBytes) : DEFAULT_MAX_BYTES;
     this.headers = opts.headers ?? {};
-    this.retries = Math.min(10, Math.max(0, Math.floor(opts.retries ?? 0)));
+    const retries = Number(opts.retries ?? 0);
+    this.retries = Number.isNaN(retries) ? 0 : Math.min(10, Math.max(0, Math.floor(retries)));
   }
   /** Build an absolute URL from a path + optional query params. */
   url(path, query) {
@@ -107,11 +128,16 @@ var Http = class {
   }
   async getJson(path, query) {
     const url = this.url(path, query);
+    const budget = new RetryWaitBudget(HTTP_RETRY_WAIT_BUDGET_MS);
     for (let attempt = 0; ; attempt++) {
+      let serverWaitMs = 0;
+      let last;
       try {
         const { res, body } = await this.raw("GET", path, { query });
         if (!res.ok) {
-          if (!(res.status >= 500 && attempt < this.retries)) throw new HttpError(res.status, url, errText(body));
+          last = new HttpError(res.status, url, errText(body));
+          if (!(res.status >= 500 && attempt < this.retries)) throw last;
+          serverWaitMs = retryAfterMs(res);
         } else {
           return this.parseJson(res, new TextDecoder().decode(body), url);
         }
@@ -119,7 +145,10 @@ var Http = class {
         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))));
+      const jitterMs = Math.floor(Math.random() * Math.min(4e3, 250 * 2 ** attempt));
+      const waitMs = budget.take(jitterMs, serverWaitMs);
+      if (waitMs === null) throw last ?? new HttpError(0, url, "retry wait budget exhausted");
+      await new Promise((r) => setTimeout(r, waitMs));
     }
   }
   async postJson(path, body, headers) {
@@ -207,6 +236,8 @@ var RegistryClient = class {
 };
 
 export {
+  retryAfterMs,
+  RetryWaitBudget,
   readCapped,
   Http,
   RegistryClient,

package/dist/{chunk-E4YQRWZZ.js → chunk-CZAQNZZG.js}

@@ -1,6 +1,7 @@
 import {
+  CairnError,
   ContentVerificationError
-} from "./chunk-ZFVE6MU7.js";
+} from "./chunk-OSPAN7GX.js";
 
 // src/content.ts
 import { payloadHash, canonicalJson, verifyContentBytes } from "@inversealtruism/csd-codec";
@@ -24,7 +25,7 @@ var ContentClient = class {
       bytes: new TextEncoder().encode(canonical)
     };
   }
-  /** Alias for `prepare()` — emphasises this does not itself publish (anchor via board.propose). */
+  /** Alias for `prepare()`. It does not publish anything; anchor the hash with a Propose. */
   put(obj) {
     return this.prepare(obj);
   }
@@ -34,12 +35,15 @@ var ContentClient = class {
   }
   /**
    * Fetch content by hash and VERIFY it self-certifies (sha256(bytes) == hash).
-   * Tries each configured source in order. Returns raw bytes, or null if no
-   * source holds it. Throws ContentVerificationError if a source returns bytes
-   * that don't match the hash (tampering / wrong object).
+   * Tries each configured source in order; a source that is unreachable, lacks
+   * the content or serves bytes that don't match the hash is skipped. Returns the
+   * first verified bytes, or null if no source holds it. Throws
+   * ContentVerificationError only when no source served verified bytes and at
+   * least one served mismatching bytes (tampering / wrong object).
    */
   async getBytes(hash) {
     const h = normalizeHash(hash);
+    let mismatched = false;
     for (const src of this.sources) {
       let got = null;
       try {
@@ -49,17 +53,24 @@ var ContentClient = class {
       }
       if (!got) continue;
       if (!verifyContentBytes(got.bytes, h)) {
-        throw new ContentVerificationError(h);
+        mismatched = true;
+        continue;
       }
       return got.bytes;
     }
+    if (mismatched) throw new ContentVerificationError(h);
     return null;
   }
-  /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. */
+  /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. Throws a CairnError with code
+   *  CONTENT_NOT_JSON when the verified bytes are not JSON. */
   async get(hash) {
     const bytes = await this.getBytes(hash);
     if (!bytes) return null;
-    return JSON.parse(new TextDecoder().decode(bytes));
+    try {
+      return JSON.parse(new TextDecoder().decode(bytes));
+    } catch (e) {
+      throw new CairnError(`Content ${normalizeHash(hash)} verified against its hash but is not JSON; use getBytes() for raw content.`, { code: "CONTENT_NOT_JSON", cause: e });
+    }
   }
   /** Verify already-fetched bytes against a hash (no network). */
   verify(bytes, hash) {

package/dist/{chunk-J5J4JEJ6.js → chunk-K5MGEYEU.js}

@@ -113,17 +113,27 @@ var IndexerClient = class {
     if (!folds) {
       return { included: false, trustLevel: "not-found", blockHeight: proof.block_height, reason: "merkle branch does not fold to the claimed root" };
     }
+    let unverified;
     if (this.opts.headerMerkleAt) {
+      let onchain;
       try {
-        const onchain = await this.opts.headerMerkleAt(proof.block_height);
+        onchain = await this.opts.headerMerkleAt(proof.block_height);
+      } catch (e) {
+        onchain = "";
+        unverified = `header at ${proof.block_height} not verified (${e?.message ?? String(e)})`;
+      }
+      if (onchain) {
         if (norm(onchain) !== norm(proof.merkle_root)) {
           return { included: false, trustLevel: "not-found", equivocation: true, blockHeight: proof.block_height, reason: "proof root != on-chain header merkle (indexer disagrees with chain)" };
         }
         return { included: true, trustLevel: "verified-inclusion", blockHeight: proof.block_height, pos: proof.pos, merkleRoot: proof.merkle_root };
-      } catch {
       }
+      unverified ??= `header source returned no merkle root for ${proof.block_height}`;
+    } else {
+      unverified = "no header source configured (headerMerkleAt)";
     }
-    return { included: true, trustLevel: "proof-consistent", blockHeight: proof.block_height, pos: proof.pos, merkleRoot: proof.merkle_root };
+    const trivial = proof.merkle.length === 0 && norm(proof.merkle_root) === norm(txid) ? "; empty branch (root equals the txid)" : "";
+    return { included: false, trustLevel: "proof-consistent", blockHeight: proof.block_height, pos: proof.pos, merkleRoot: proof.merkle_root, reason: `indexer proof only, ${unverified}${trivial}` };
   }
   // ---- live streams ------------------------------------------------------
   /** Stream all events (blocks, proposals, attestations, reorgs) via SSE. */

package/dist/{chunk-OB33SSGA.js → chunk-OE5BEEQY.js}

@@ -1,14 +1,15 @@
 import {
   getWallet
-} from "./chunk-FWTPXLGV.js";
+} from "./chunk-5RGFC2JR.js";
 
 // src/controller.ts
 var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error: null });
 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).
+  // Connect/disconnect generation token. disconnect(), the wallet's `disconnect` event and an empty
+  // accountsChanged (lock, account switch, revoke) bump it; a connect() whose await straddled the bump must
+  // never commit "connected" over the torn-down session.
   epoch = 0;
   listeners = /* @__PURE__ */ new Set();
   getWalletFn;
@@ -39,6 +40,7 @@ var CairnController = class {
   }
   onAccounts = (accounts) => {
     if (!Array.isArray(accounts) || accounts.length === 0) {
+      this.epoch++;
       this.setState({ status: "disconnected", account: null });
       return;
     }
@@ -50,6 +52,7 @@ var CairnController = class {
     }
   };
   onDisconnect = () => {
+    this.epoch++;
     this.setState({ status: "disconnected", account: null });
   };
   // Detach the provider listeners (ghost-reconnect fix). Idempotent + best-effort.

package/dist/{chunk-ZFVE6MU7.js → chunk-OSPAN7GX.js}

@@ -1,5 +1,5 @@
 // src/errors.ts
-var SDK_VERSION = "0.4.6";
+var SDK_VERSION = "0.5.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */

package/dist/connect.cjs

@@ -30,7 +30,7 @@ __export(connect_exports, {
 module.exports = __toCommonJS(connect_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.4.6";
+var SDK_VERSION = "0.5.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -376,7 +376,7 @@ var WalletConnection = class {
   send(params) {
     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. */
+  /** Low-level Propose (always prompts). The caller computes the payload hash, uri and expiry epoch. */
   propose(params) {
     return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
   }

package/dist/connect.d.cts

@@ -16,7 +16,7 @@ interface SignInResult {
     nonce?: string;
     [k: string]: unknown;
 }
-/** Low-level Propose params (matches the wallet exactly). Prefer `cairn.board.propose()` for ergonomics. */
+/** Low-level Propose params (matches the wallet exactly). `payloadHash` is csd-codec `payloadHash` of your content. */
 interface ProposeParams {
     domain: string;
     payloadHash: string;
@@ -270,7 +270,7 @@ declare class WalletConnection {
     off(event: string, handler: (data: any) => void): void;
     /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
     send(params: SendParams): Promise<TxResult>;
-    /** Low-level Propose (always prompts). Prefer `cairn.board.propose()` which computes the hash/uri/expiry. */
+    /** Low-level Propose (always prompts). The caller computes the payload hash, uri and expiry epoch. */
     propose(params: ProposeParams): Promise<TxResult>;
     /** Attest/support a proposal (always prompts). */
     attest(params: AttestParams): Promise<TxResult>;

package/dist/connect.d.ts

@@ -16,7 +16,7 @@ interface SignInResult {
     nonce?: string;
     [k: string]: unknown;
 }
-/** Low-level Propose params (matches the wallet exactly). Prefer `cairn.board.propose()` for ergonomics. */
+/** Low-level Propose params (matches the wallet exactly). `payloadHash` is csd-codec `payloadHash` of your content. */
 interface ProposeParams {
     domain: string;
     payloadHash: string;
@@ -270,7 +270,7 @@ declare class WalletConnection {
     off(event: string, handler: (data: any) => void): void;
     /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
     send(params: SendParams): Promise<TxResult>;
-    /** Low-level Propose (always prompts). Prefer `cairn.board.propose()` which computes the hash/uri/expiry. */
+    /** Low-level Propose (always prompts). The caller computes the payload hash, uri and expiry epoch. */
     propose(params: ProposeParams): Promise<TxResult>;
     /** Attest/support a proposal (always prompts). */
     attest(params: AttestParams): Promise<TxResult>;

package/dist/connect.js

@@ -5,8 +5,8 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-FWTPXLGV.js";
-import "./chunk-ZFVE6MU7.js";
+} from "./chunk-5RGFC2JR.js";
+import "./chunk-OSPAN7GX.js";
 export {
   WalletConnection,
   connect,

package/dist/content.cjs

@@ -26,7 +26,7 @@ module.exports = __toCommonJS(content_exports);
 var import_csd_codec = require("@inversealtruism/csd-codec");
 
 // src/errors.ts
-var SDK_VERSION = "0.4.6";
+var SDK_VERSION = "0.5.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -99,7 +99,7 @@ var ContentClient = class {
       bytes: new TextEncoder().encode(canonical)
     };
   }
-  /** Alias for `prepare()` — emphasises this does not itself publish (anchor via board.propose). */
+  /** Alias for `prepare()`. It does not publish anything; anchor the hash with a Propose. */
   put(obj) {
     return this.prepare(obj);
   }
@@ -109,12 +109,15 @@ var ContentClient = class {
   }
   /**
    * Fetch content by hash and VERIFY it self-certifies (sha256(bytes) == hash).
-   * Tries each configured source in order. Returns raw bytes, or null if no
-   * source holds it. Throws ContentVerificationError if a source returns bytes
-   * that don't match the hash (tampering / wrong object).
+   * Tries each configured source in order; a source that is unreachable, lacks
+   * the content or serves bytes that don't match the hash is skipped. Returns the
+   * first verified bytes, or null if no source holds it. Throws
+   * ContentVerificationError only when no source served verified bytes and at
+   * least one served mismatching bytes (tampering / wrong object).
    */
   async getBytes(hash) {
     const h = normalizeHash(hash);
+    let mismatched = false;
     for (const src of this.sources) {
       let got = null;
       try {
@@ -124,17 +127,24 @@ var ContentClient = class {
       }
       if (!got) continue;
       if (!(0, import_csd_codec.verifyContentBytes)(got.bytes, h)) {
-        throw new ContentVerificationError(h);
+        mismatched = true;
+        continue;
       }
       return got.bytes;
     }
+    if (mismatched) throw new ContentVerificationError(h);
     return null;
   }
-  /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. */
+  /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. Throws a CairnError with code
+   *  CONTENT_NOT_JSON when the verified bytes are not JSON. */
   async get(hash) {
     const bytes = await this.getBytes(hash);
     if (!bytes) return null;
-    return JSON.parse(new TextDecoder().decode(bytes));
+    try {
+      return JSON.parse(new TextDecoder().decode(bytes));
+    } catch (e) {
+      throw new CairnError(`Content ${normalizeHash(hash)} verified against its hash but is not JSON; use getBytes() for raw content.`, { code: "CONTENT_NOT_JSON", cause: e });
+    }
   }
   /** Verify already-fetched bytes against a hash (no network). */
   verify(bytes, hash) {

package/dist/content.d.cts

@@ -24,18 +24,21 @@ declare class ContentClient {
      * This is byte-identical to what the cairn server and wallet compute.
      */
     prepare(obj: unknown): PreparedContent;
-    /** Alias for `prepare()` — emphasises this does not itself publish (anchor via board.propose). */
+    /** Alias for `prepare()`. It does not publish anything; anchor the hash with a Propose. */
     put(obj: unknown): PreparedContent;
     /** Just the payload hash for an object. */
     hash(obj: unknown): string;
     /**
      * Fetch content by hash and VERIFY it self-certifies (sha256(bytes) == hash).
-     * Tries each configured source in order. Returns raw bytes, or null if no
-     * source holds it. Throws ContentVerificationError if a source returns bytes
-     * that don't match the hash (tampering / wrong object).
+     * Tries each configured source in order; a source that is unreachable, lacks
+     * the content or serves bytes that don't match the hash is skipped. Returns the
+     * first verified bytes, or null if no source holds it. Throws
+     * ContentVerificationError only when no source served verified bytes and at
+     * least one served mismatching bytes (tampering / wrong object).
      */
     getBytes(hash: string): Promise<Uint8Array | null>;
-    /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. */
+    /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. Throws a CairnError with code
+     *  CONTENT_NOT_JSON when the verified bytes are not JSON. */
     get<T = unknown>(hash: string): Promise<T | null>;
     /** Verify already-fetched bytes against a hash (no network). */
     verify(bytes: Uint8Array, hash: string): boolean;

package/dist/content.d.ts

@@ -24,18 +24,21 @@ declare class ContentClient {
      * This is byte-identical to what the cairn server and wallet compute.
      */
     prepare(obj: unknown): PreparedContent;
-    /** Alias for `prepare()` — emphasises this does not itself publish (anchor via board.propose). */
+    /** Alias for `prepare()`. It does not publish anything; anchor the hash with a Propose. */
     put(obj: unknown): PreparedContent;
     /** Just the payload hash for an object. */
     hash(obj: unknown): string;
     /**
      * Fetch content by hash and VERIFY it self-certifies (sha256(bytes) == hash).
-     * Tries each configured source in order. Returns raw bytes, or null if no
-     * source holds it. Throws ContentVerificationError if a source returns bytes
-     * that don't match the hash (tampering / wrong object).
+     * Tries each configured source in order; a source that is unreachable, lacks
+     * the content or serves bytes that don't match the hash is skipped. Returns the
+     * first verified bytes, or null if no source holds it. Throws
+     * ContentVerificationError only when no source served verified bytes and at
+     * least one served mismatching bytes (tampering / wrong object).
      */
     getBytes(hash: string): Promise<Uint8Array | null>;
-    /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. */
+    /** Fetch + verify + parse as UTF-8 JSON. Returns null if not found. Throws a CairnError with code
+     *  CONTENT_NOT_JSON when the verified bytes are not JSON. */
     get<T = unknown>(hash: string): Promise<T | null>;
     /** Verify already-fetched bytes against a hash (no network). */
     verify(bytes: Uint8Array, hash: string): boolean;

package/dist/content.js

@@ -1,7 +1,7 @@
 import {
   ContentClient
-} from "./chunk-E4YQRWZZ.js";
-import "./chunk-ZFVE6MU7.js";
+} from "./chunk-CZAQNZZG.js";
+import "./chunk-OSPAN7GX.js";
 export {
   ContentClient
 };

package/dist/controller.cjs

@@ -25,7 +25,7 @@ __export(controller_exports, {
 module.exports = __toCommonJS(controller_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.4.6";
+var SDK_VERSION = "0.5.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -348,7 +348,7 @@ var WalletConnection = class {
   send(params) {
     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. */
+  /** Low-level Propose (always prompts). The caller computes the payload hash, uri and expiry epoch. */
   propose(params) {
     return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
   }
@@ -377,8 +377,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).
+  // Connect/disconnect generation token. disconnect(), the wallet's `disconnect` event and an empty
+  // accountsChanged (lock, account switch, revoke) bump it; a connect() whose await straddled the bump must
+  // never commit "connected" over the torn-down session.
   epoch = 0;
   listeners = /* @__PURE__ */ new Set();
   getWalletFn;
@@ -409,6 +410,7 @@ var CairnController = class {
   }
   onAccounts = (accounts) => {
     if (!Array.isArray(accounts) || accounts.length === 0) {
+      this.epoch++;
       this.setState({ status: "disconnected", account: null });
       return;
     }
@@ -420,6 +422,7 @@ var CairnController = class {
     }
   };
   onDisconnect = () => {
+    this.epoch++;
     this.setState({ status: "disconnected", account: null });
   };
   // Detach the provider listeners (ghost-reconnect fix). Idempotent + best-effort.

package/dist/controller.js

@@ -1,8 +1,8 @@
 import {
   CairnController
-} from "./chunk-OB33SSGA.js";
-import "./chunk-FWTPXLGV.js";
-import "./chunk-ZFVE6MU7.js";
+} from "./chunk-OE5BEEQY.js";
+import "./chunk-5RGFC2JR.js";
+import "./chunk-OSPAN7GX.js";
 export {
   CairnController
 };