@uuaid/pillar 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/escrow/verify.mjs

@@ -0,0 +1,119 @@
+/**
+ * TransferVerifier — the VDA-1 `transfer` instrument (spec: docs/VDA-1-SPEC.md).
+ * "Did transfer X (from, to, amount, asset) really settle on rail R?" is
+ * answered from the RAIL'S OWN record (chain receipt + logs at depth), never
+ * from the claimant's story, and emitted as a signed, content-addressed
+ * VDA-1 envelope.
+ *
+ * Design carried from the uuaid/iaaso governance stack: content-addressed
+ * ids (sha256(jcs(claim))[:16]); Ed25519 over JCS (offline verification);
+ * fail-closed token registry; instrument-blind honesty (fleet SOP §4.12) —
+ * a rail structurally blind to a claim answers "instrument-blind", never a
+ * vacuous negative.  Every envelope carries a mandatory instrument-coverage
+ * statement (spec §5.1).
+ *
+ * Envelopes emitted before VDA-1 (kind "transfer-attestation", claims
+ * without `kind`) remain verifiable via verifyAttestationSig/verifyEnvelope —
+ * accepted read-only, never emitted (spec §4 legacy note).
+ */
+import { jcs } from "../identity/jcs.mjs";
+import { Keychain } from "../identity/keychain.mjs";
+import { railKeyOfTerms } from "./rails/index.mjs";
+import { normalizeClaim, buildAttestation } from "../vda/core.mjs";
+
+export const ATTESTATION_V = 1;
+
+// NOTE: the old 16-hex `claimId` export was deleted (RedTeam round-2 rec 5)
+// so a truncated join key cannot be resurrected.  Legacy envelope ids are
+// handled inside vda/core.mjs (legacyClaimId, read-only branch).
+
+/** Offline signature check for VDA-1 AND legacy envelopes. */
+export function verifyAttestationSig(publicKeyHex, attestation) {
+  try {
+    const { sig, ...rest } = attestation;
+    if (attestation.v !== ATTESTATION_V || typeof sig !== "string") return false;
+    return Keychain.verifyDetached(publicKeyHex, Buffer.from(jcs(rest), "utf-8"), Buffer.from(sig, "hex"));
+  } catch (_e) {
+    return false;
+  }
+}
+
+export class TransferVerifier {
+  /**
+   * @param rails         RailSet (rails may implement verifyTransfer; those
+   *                      that don't are instrument-blind for standalone claims)
+   * @param keychain      loaded Keychain; attestations are signed by it.
+   *                      Omit for unsigned (local-only) verification.
+   * @param tokenRegistry optional fail-closed allowlist (chains + tokens)
+   */
+  constructor({ rails, keychain = null, tokenRegistry = null }) {
+    if (!rails) throw new Error("TransferVerifier: rails required");
+    this.rails = rails;
+    this.keychain = keychain;
+    this.tokenRegistry = tokenRegistry;
+  }
+
+  /**
+   * Verify one transfer claim and return a (signed) VDA-1 attestation.
+   * claim: { rail: "evm"|"zilligon", chainId?, txId, from?, to, amount, asset? }
+   * Amounts are decimal base-unit strings (wei / Gons) — spec §2.
+   */
+  async verify(claimRaw) {
+    const n = normalizeClaim({ ...claimRaw, kind: "transfer" });
+    const coverageRefused =
+      "Verifier refused before consulting any instrument; this attestation observes nothing about the event.";
+    if (!n.ok) {
+      const claim = normalizeClaim({ kind: "malformed", originalKind: "transfer" }).claim;
+      return buildAttestation({ claim, verdict: "unsupported", reason: n.reason, coverage: coverageRefused, keychain: this.keychain });
+    }
+    const claim = n.claim;
+    const finish = (verdict, extra = {}) => buildAttestation({ claim, verdict, keychain: this.keychain, ...extra });
+
+    const railKey = railKeyOfTerms({ v: 2, rail: claim.rail, chainId: claim.chainId });
+    const rail = railKey ? this.rails.get(railKey) : null;
+    if (!rail) return finish("unsupported", { reason: "rail-unsupported", coverage: coverageRefused });
+
+    // Fail-closed allowlist, same gate the escrow applies at the door.
+    if (this.tokenRegistry && claim.rail === "evm") {
+      if (!this.tokenRegistry.isChainApproved(claim.chainId)) {
+        return finish("unsupported", { reason: "chain-not-registered", coverage: coverageRefused });
+      }
+      if (claim.asset !== "native" && !this.tokenRegistry.isAssetApproved(claim.chainId, claim.asset)) {
+        return finish("unsupported", { reason: "token-not-registered", coverage: coverageRefused });
+      }
+    }
+
+    if (typeof rail.verifyTransfer !== "function") {
+      return finish("instrument-blind", {
+        reason: "rail-cannot-attest-standalone-claims",
+        coverage:
+          "Instrument: this rail sees only its own wallet's rows and cannot observe arbitrary third-party transfers; " +
+          "this verdict is explicitly NOT evidence the transfer did not settle.",
+      });
+    }
+
+    const coverage =
+      `Instrument: the ${claim.rail} rail's own record (receipt and event logs at confirmation depth) via a single ` +
+      "RPC endpoint; full sight of the transaction hash space on that chain, subject to that endpoint's honesty — " +
+      "use a quorum of independent verifiers to bound endpoint trust.";
+
+    let res;
+    try {
+      res = await rail.verifyTransfer({ txId: claim.txId, from: claim.from, to: claim.to, amount: claim.amount, asset: claim.asset });
+    } catch (e) {
+      return finish("unsupported", { reason: `instrument-error: ${String(e.message ?? e)}`, coverage });
+    }
+    if (res?.verified) {
+      return finish("verified", {
+        coverage,
+        // blockNumber as a string: spec §3 — quantities that can exceed 2^53
+        evidence: { blockNumber: String(res.blockNumber), depth: res.depth, from: res.from, to: res.to, amount: res.amount, asset: res.asset },
+      });
+    }
+    if (res?.reason === "unconfirmed") return finish("pending", { reason: "below-confirmation-depth", coverage });
+    if (res?.reason === "instrument-blind") {
+      return finish("instrument-blind", { reason: res.detail ?? "instrument-blind", coverage });
+    }
+    return finish("failed", { reason: res?.reason ?? "not-found", coverage });
+  }
+}

package/src/escrow/zilligon.mjs

@@ -0,0 +1,266 @@
+/**
+ * Zilligon ZGN rail client — the ONLY money surface of the blind escrow.
+ *
+ * VERIFIED live against zilligon.com (2026-08-21, read-only / OPTIONS /
+ * invalid-body probes — no money has ever moved):
+ *   POST /api/v1/auth/token   {apiKey, grantType:"api_key"}
+ *        -> {success, data:{accessToken, expiresIn:900, scopes}}
+ *   POST /api/v1/wallet/transfer {recipientHandle, amount}   (JWT Bearer)
+ *        The route EXISTS (OPTIONS -> 204 Allow: OPTIONS, POST) though it
+ *        appears in NO docs.  Validation, elicited with invalid bodies:
+ *        recipientHandle required string; amount must be a positive number
+ *        (strings rejected, non-integers NOT rejected at validation);
+ *        unknown handle -> 404 RECIPIENT_NOT_FOUND; self-transfer -> 400
+ *        SELF_TRANSFER; extra fields tolerated.
+ *        LIVE-VERIFIED end-to-end 2026-08-21: the rewards-service sidecar is
+ *        now DEPLOYED on the prod cluster (REWARDS_SERVICE_URL +
+ *        INTERNAL_SERVICE_SECRET wired on the live task-def) and an
+ *        owner-authorized 10-Gon transfer returned HTTP 200 with
+ *        {transactionId, newBalance, recipient, amount}.  transactionId is
+ *        the Tip row's id, which equals BOTH wallet rows' sourceId — the
+ *        response's txId is the cross-side link (verified on the live rows).
+ *        Also verified live: recipient must be status "ACTIVE" or the route
+ *        returns 404 RECIPIENT_NOT_FOUND — 46,162 of the agents are DORMANT
+ *        and only 37 platform-wide can receive transfers at all.
+ *   GET  /api/token/wallet?handle=<h>   public by handle, NO auth — but a
+ *        browser User-Agent is REQUIRED (403 "Automated access not
+ *        permitted" without one, 200 with).  Last ~20 tx rows:
+ *        -> {handle, reputation, wallet:{zgnBalance, zgnLocked, zgnStaked,
+ *            transactions:[{type, amount, currency, status, source, date}]}}
+ *
+ * VERIFIED tx vocabulary (20 rows sampled across 3 wallets, 2026-08-21):
+ * every observed row is {type:"EARNING", currency:"GONS",
+ * status:"CONFIRMED", source:"CODE_FORGE", date:ISO}.
+ *
+ * TRANSFER ROW CONTRACT (verified LIVE in-container 2026-08-21 on the prod
+ * DB — matches services/rewards-service internal.ts:290-348): one Tip + two
+ * WalletTransaction rows in a single prisma.$transaction:
+ *   sender   row: type "TIP_SENT",   amount NEGATIVE, fee set,
+ *   receiver row: type "TIP_RECEIVED", amount net
+ *                 (amount - floor(amount*0.005)), fee unset -> 0,
+ *   both rows: currency "GONS", sourceType "transfer" (public API projects
+ *   `source: "transfer"`), sourceId = tip.id (the ONLY link between the two
+ *   sides — and the id the transfer API returns as transactionId), status
+ *   "CONFIRMED", balanceAfter set.  A row's own Prisma cuid `id` is NOT the
+ *   transactionId.
+ * The public wallet API (/api/token/wallet) historically projected ONLY
+ * {type, amount, currency, status, source, date}; an additive projection fix
+ * (Zilligon-Lead, 2026-08-21) adds {id, sourceId, fee, balanceAfter}.
+ * Consequence for the matchers:
+ *   - "source" on a transfer row is the literal string "transfer", NOT a
+ *     handle — source-binding is only enforced when the field actually
+ *     looks like a handle ("@..."), otherwise the row stays unbound.
+ *   - TIP_SENT rows carry NEGATIVE amounts — the payout matcher compares
+ *     magnitudes.
+ *   - A buyer's claimed txId (the transfer response's transactionId) equals
+ *     row.sourceId, NOT row.id — the matchers accept a claimed txId against
+ *     EITHER, bind on an explicit sourceId claim, and HARD-REJECT a row
+ *     whose sourceId disagrees with the claim (no silent amount+window
+ *     fallthrough).  Pre-fix rows (no id/sourceId in the projection) still
+ *     degrade to amount+window attestation — the documented caveat for the
+ *     IAASO ratification doc.
+ *
+ * Fee (verified in source: config.ts:52 tipFeePercent 0.005 + internal.ts:288
+ * fee = floor(amount * 0.005)): every transfer below 200 Gons is FEE-FREE;
+ * the receiver nets exactly `amount`.  200 Gons is the first amount that
+ * pays 1.  The escrow fee math in terms.mjs mirrors this exactly.
+ */
+
+const BROWSER_UA = "Mozilla/5.0"; // the exact UA verified to pass the wallet-view gate
+
+/**
+ * Verified background-noise tx types — never a payment/payout signal.
+ * TIP_SENT / TIP_RECEIVED (the transfer-created rows) are NOT noise — they
+ * are the exchange rows the matchers hunt for.
+ */
+export const TX_NOISE_TYPES = ["earning"];
+
+export class ZilligonClient {
+  constructor({ baseUrl = "https://zilligon.com", apiKey, handle }) {
+    if (!apiKey) throw new Error("ZilligonClient: apiKey required");
+    if (!handle) throw new Error("ZilligonClient: handle required (escrow's own @handle)");
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.handle = handle;
+    this._token = null; // { accessToken, expiresAt }
+  }
+
+  async getToken() {
+    if (this._token && this._token.expiresAt > Date.now() + 30_000) return this._token.accessToken;
+    const res = await fetch(`${this.baseUrl}/api/v1/auth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ apiKey: this.apiKey, grantType: "api_key" }),
+    });
+    if (!res.ok) throw new Error(`zilligon auth/token: HTTP ${res.status}`);
+    const json = await res.json();
+    if (json.success !== true || !json.data?.accessToken) {
+      throw new Error(`zilligon auth/token rejected: ${json.error || json.message || "unknown"}`);
+    }
+    this._token = {
+      accessToken: json.data.accessToken,
+      expiresAt: Date.now() + (json.data.expiresIn ?? 900) * 1000,
+    };
+    return this._token.accessToken;
+  }
+
+  async _authed(method, path, body) {
+    const token = await this.getToken();
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok || json.success === false) {
+      throw new Error(`zilligon ${path}: HTTP ${res.status} ${json.error || json.message || ""}`.trim());
+    }
+    return json;
+  }
+
+  /**
+   * Transfer Gons to a handle.  The body carries ONLY the verified fields
+   * {recipientHandle, amount}.  Local guards mirror the rail's verified
+   * rejection set (self-transfer) plus an integer guard stricter than the
+   * rail's validation (which accepts any positive number — Gons are whole).
+   */
+  async transfer({ recipientHandle, amount }) {
+    if (typeof amount !== "number" || !Number.isInteger(amount) || amount < 1) {
+      throw new Error(`transfer: amount must be an integer >= 1 Gons, got ${amount}`);
+    }
+    if (recipientHandle === this.handle) throw new Error("transfer: self-transfer rejected by rail");
+    return this._authed("POST", "/api/v1/wallet/transfer", { recipientHandle, amount });
+  }
+
+  /** Public wallet view for a handle — needs a browser User-Agent (verified). */
+  async getWallet(handle = this.handle) {
+    const res = await fetch(`${this.baseUrl}/api/token/wallet?handle=${encodeURIComponent(handle)}`, {
+      headers: { "User-Agent": BROWSER_UA },
+    });
+    if (!res.ok) throw new Error(`zilligon wallet?handle=: HTTP ${res.status}`);
+    return res.json();
+  }
+
+  /**
+   * Attest the buyer's payment from THIS client's wallet: poll until a
+   * matching non-noise row appears.  Returns the row, or null once attempts
+   * are exhausted.
+   */
+  async findPayment({ buyerHandle, expectedAmount, txId, sourceId, since, attempts = 6, delayMs = 5000 }) {
+    for (let i = 0; i < attempts; i++) {
+      let view;
+      try {
+        view = await this.getWallet(this.handle);
+      } catch (_e) {
+        view = null; // transient rail hiccup — retry
+      }
+      const hit = view ? findPaymentInWallet(view, { buyerHandle, expectedAmount, txId, sourceId, since }) : null;
+      if (hit) return hit;
+      await new Promise((r) => setTimeout(r, delayMs));
+    }
+    return null;
+  }
+}
+
+/** Extract a transaction id from any shape the rail might return. */
+export function txIdOf(tx) {
+  return tx?.txId ?? tx?.id ?? tx?.transactionId ?? tx?._id ?? null;
+}
+
+const asNum = (v) => {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : null;
+};
+
+/**
+ * Handle-like source/destination fields ("@handle") bind a row to a
+ * counterparty.  Transfer rows carry the literal type string ("transfer") in
+ * `source` — NOT a handle — so binding must only fire on handle-shaped values.
+ */
+const looksLikeHandle = (s) => typeof s === "string" && s.startsWith("@");
+
+/** A row is a candidate payment/payout iff its type is not verified noise. */
+function isExchangeRow(tx) {
+  const t = String(tx?.type ?? "").toLowerCase();
+  if (!t) return true; // unknown vocabulary — can't classify as noise
+  return !TX_NOISE_TYPES.includes(t);
+}
+
+/** ISO-string window check; rows that can't be compared are NOT filtered. */
+function afterSince(dateStr, sinceStr) {
+  const d = Date.parse(dateStr);
+  const s = Date.parse(sinceStr);
+  if (Number.isNaN(d) || Number.isNaN(s)) return true;
+  return d >= s;
+}
+
+/**
+ * Pure matcher — shared by the live client and the integration-test mock so
+ * the mock exercises the SAME attestation logic.  A payment hit needs:
+ *   1. a non-noise row (only EARNING rows are proven noise; transfer rows
+ *      are TIP_SENT/TIP_RECEIVED — non-noise, see header),
+ *   2. amount === expectedAmount Gons exactly,
+ *   3. date >= since, when a window is given,
+ *   4. counterparty binding, strongest first (verified live 2026-08-21: the
+ *      transfer response's transactionId equals BOTH rows' sourceId, NOT a
+ *      row's own id — so a claimed txId matches against EITHER):
+ *        a. claimed txId === row.id OR row.sourceId  -> hit;
+ *        b. explicit sourceId claim === row.sourceId -> hit;
+ *        c. row.sourceId present but DISAGREEING with a claim -> the row is
+ *           someone else's transfer: hard-skip, never amount+window
+ *           fallthrough;
+ *   5. and — when the row carries a handle-SHAPED source field ("@...") and
+ *      buyerHandle is known — that source equals the buyer.  A non-handle
+ *      source (the literal "transfer" on rail rows) with no id/sourceId
+ *      (pre-projection-fix rows) leaves the row UNBOUND: it attests by
+ *      amount+window alone.
+ */
+export function findPaymentInWallet(walletView, { buyerHandle, expectedAmount, txId, sourceId, since }) {
+  const wallet = walletView?.wallet ?? walletView ?? {};
+  const txs = Array.isArray(wallet.transactions) ? wallet.transactions : [];
+  for (const tx of txs) {
+    if (typeof tx !== "object" || tx === null) continue;
+    if (!isExchangeRow(tx)) continue;
+    if (asNum(tx.amount) !== expectedAmount) continue;
+    if (since && !afterSince(tx.date, since)) continue;
+    const source = tx.source ?? tx.from ?? tx.senderHandle ?? null;
+    const id = txIdOf(tx);
+    const rowSourceId = tx.sourceId ?? null;
+    // (a) claimed txId matches row id or row sourceId — the strongest link
+    //     (the transfer API's transactionId IS the rows' sourceId).
+    if (txId && ((id && String(id) === String(txId)) || (rowSourceId && String(rowSourceId) === String(txId)))) return tx;
+    // (b) explicit sourceId claim matches the row's.
+    if (sourceId && rowSourceId && String(rowSourceId) === String(sourceId)) return tx;
+    // (c) the row carries a sourceId that conflicts with our claims — it is
+    //     someone else's transfer: hard-skip.
+    if (rowSourceId && ((txId && String(rowSourceId) !== String(txId)) || (sourceId && String(rowSourceId) !== String(sourceId)))) continue;
+    if (buyerHandle && looksLikeHandle(source) && source !== buyerHandle) continue; // bound and mismatched
+    return tx;
+  }
+  return null;
+}
+
+/**
+ * Matcher for the escrow's own payout: a non-noise row of the exact amount
+ * (magnitude — the escrow's sender-side rows are TIP_SENT with NEGATIVE
+ * amounts, see header).  dest-binding only fires on handle-shaped fields;
+ * an explicit sourceId claim binds hard (match -> hit, disagreement -> skip).
+ */
+export function findPayoutInWallet(walletView, { sellerHandle, amount, sourceId, since }) {
+  const wallet = walletView?.wallet ?? walletView ?? {};
+  const txs = Array.isArray(wallet.transactions) ? wallet.transactions : [];
+  for (const tx of txs) {
+    if (typeof tx !== "object" || tx === null) continue;
+    if (!isExchangeRow(tx)) continue;
+    const mag = asNum(tx.amount);
+    if (mag === null || Math.abs(mag) !== amount) continue; // TIP_SENT rows are negative (see header)
+    if (since && !afterSince(tx.date, since)) continue;
+    const rowSourceId = tx.sourceId ?? null;
+    if (sourceId && rowSourceId && String(rowSourceId) === String(sourceId)) return tx;
+    if (sourceId && rowSourceId && String(rowSourceId) !== String(sourceId)) continue; // hard disagreement — someone else's transfer
+    const dest = tx.destination ?? tx.to ?? tx.recipientHandle ?? null;
+    if (sellerHandle && looksLikeHandle(dest) && dest !== sellerHandle) continue; // bound and mismatched
+    return tx;
+  }
+  return null;
+}

package/src/identity/keychain.mjs

@@ -15,6 +15,22 @@ import { randomBytes, createHash, generateKeyPairSync, sign, verify, createPubli
 
 const KEYCHAIN_VERSION = 1;
 
+/**
+ * Derive a stable, publishable local id from a raw Ed25519 public key.  This
+ * makes the UUAID self-authenticating: given the UUAID, anyone can
+ * independently check that the public key hashes to the expected local-id.
+ *
+ * Public because consumers verifying a UUAID against a public key need it
+ * without reaching into `Keychain._localIdFromKey`.
+ */
+export function localIdFromKey(rawPub) {
+  const h = createHash("sha256").update(rawPub).digest();
+  // First 16 bytes -> UUID-style dash format for readability.
+  const b = h.slice(0, 16);
+  const hex = Buffer.from(b).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
 export class Keychain {
   constructor(path) {
     this.path = path;
@@ -48,16 +64,17 @@ export class Keychain {
     };
   }
 
-  static _localIdFromKey(rawPub) {
-    // Derive a stable, publishable local id from the public key.  This makes
-    // the UUAID self-authenticating: given the UUAID, anyone can independently
-    // check that the public key hashes to the expected local-id.
-    const h = createHash("sha256").update(rawPub).digest();
-    // First 16 bytes -> UUID-style dash format for readability.
-    const b = h.slice(0, 16);
-    const hex = Buffer.from(b).toString("hex");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-  }
+  /**
+   * Derive the local-id from a raw Ed25519 public key.
+   *
+   * Kept on the class for the call sites that already reach for it; the
+   * implementation is the module-level `localIdFromKey`, which is the public
+   * export.
+   */
+  static localIdFromKey = localIdFromKey;
+
+  /** @deprecated Alias kept for compatibility — use `localIdFromKey`. */
+  static _localIdFromKey = localIdFromKey;
 
   /**
    * Load an identity from disk.

package/src/index.mjs

@@ -7,7 +7,7 @@
  * Entry point.  Not intended for import in browsers today — browser build
  * lives at @uuaid/pillar-browser (later).
  */
-export { Keychain } from "./identity/keychain.mjs";
+export { Keychain, localIdFromKey } from "./identity/keychain.mjs";
 export { jcs } from "./identity/jcs.mjs";
 export { seal, open, decrypt, envelopeSha, keychainSeed, ENVELOPE_VERSION, E2E_ALG } from "./net/envelope.mjs";
 export { sealPayload, openPayload, edPubToX25519, edSeedToX25519 } from "./crypto/e2e.mjs";

package/src/mailbox/mailbox.mjs

@@ -151,6 +151,16 @@ export class Mailbox {
     return !!this.db.prepare("select 1 from outbox where envelope_id = ?").get(envelopeId);
   }
 
+  /** Full outbox row by envelope id (VDA message-delivery instrument). */
+  getOutbound(envelopeId) {
+    return this.db.prepare("select * from outbox where envelope_id = ?").get(envelopeId) ?? null;
+  }
+
+  /** Full inbox row by envelope id (VDA message-delivery instrument). */
+  getInbound(envelopeId) {
+    return this.db.prepare("select * from inbox where envelope_id = ?").get(envelopeId) ?? null;
+  }
+
   markOutboundDelivered(envelopeId, ackSha256) {
     this.db.prepare("update outbox set status = 'delivered', delivered_at = ?, ack_sha256 = ? where envelope_id = ?")
       .run(new Date().toISOString(), ackSha256 ?? null, envelopeId);

package/src/net/carrier-client.mjs

@@ -97,6 +97,8 @@ export class CarrierClient {
   /**
    * Long-poll every carrier in parallel forever, invoking onEnvelope for each
    * new envelope.  Tracks per-carrier cursor.  Returns a stop() function.
+   * onError(error, { carrier }) — the carrier context is passed so callers
+   * can attribute failures per carrier in metrics.
    */
   startPolling({ onEnvelope, cursors = {}, waitS = 25, onError }) {
     this._stopPolling = false;
@@ -108,10 +110,10 @@ export class CarrierClient {
           for (const { seq, envelope } of r.envelopes) {
             state.cursors[base] = Math.max(state.cursors[base] ?? 0, seq);
             try { await onEnvelope(envelope, { carrier: base, seq }); }
-            catch (e) { onError?.(new Error(`onEnvelope threw: ${e.message}`)); }
+            catch (e) { onError?.(new Error(`onEnvelope threw: ${e.message}`), { carrier: base }); }
           }
         } catch (e) {
-          onError?.(e);
+          onError?.(e, { carrier: base });
           // Back off on error so a dead carrier doesn't spin the CPU.
           await new Promise(r2 => setTimeout(r2, 2000));
         }

package/src/observability.mjs

@@ -0,0 +1,141 @@
+/**
+ * Observability — metrics/analytics for the Pillar communication system.
+ *
+ * Zero-dependency, in-memory counters / gauges / histograms with an optional
+ * append-only JSONL sink (same pattern as the escrow journal).  Every Pillar
+ * and EscrowService owns one instance; when none is passed in, a default is
+ * created internally so instrumentation sites never null-check.
+ *
+ *   inc("sent.via.carrier")            counters — labels compose into dotted
+ *                                      keys at the CALL SITE, e.g.
+ *                                      `inc(\`received.kind.${kind}\`)`
+ *   setGauge("escrow.offers.open", 3)  gauges — last write wins
+ *   observe("send.latencyMs", ms)      histograms — fixed latency buckets
+ *
+ * Sink: journal({event, ...}) appends an event line; flush() appends a full
+ * state snapshot.  An external analytics pipeline can tail the file without
+ * a live process.  summary() renders the one-glance human view.
+ *
+ * Keys are sanitized (lowercased, non-alphanumerics folded to "-") so
+ * attacker-influenced strings (envelope kinds, error reasons) can never
+ * fabricate keys or escape the dotted namespace.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+// Fixed latency buckets (ms) — covers fast local sends (<10 ms) up to slow
+// carrier round-trips (>10 s).  Values above the top bucket still count into
+// n/sum/max; percentiles interpolate within the top bucket's upper bound.
+export const LATENCY_BUCKETS = [10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+
+const MAX_KEY = 64;
+
+export function slugKey(key) {
+  return String(key)
+    .toLowerCase()
+    .replace(/[^a-z0-9.-]+/g, "-")
+    .replace(/^-+|-+$/g, "") // a trailing "!!!" run must not leave a dangling dash
+    .slice(0, MAX_KEY);
+}
+
+function newHistogram() {
+  return { n: 0, sum: 0, min: Infinity, max: -Infinity, buckets: new Array(LATENCY_BUCKETS.length).fill(0) };
+}
+
+function percentile(h, p) {
+  if (h.n === 0) return 0;
+  const target = h.n * p;
+  let acc = 0;
+  let lower = 0;
+  for (let i = 0; i < LATENCY_BUCKETS.length; i++) {
+    acc += h.buckets[i];
+    if (acc >= target) {
+      const upper = LATENCY_BUCKETS[i];
+      const inBucket = h.buckets[i];
+      const frac = inBucket === 0 ? 0 : (target - (acc - inBucket)) / inBucket;
+      return Math.round(lower + frac * (upper - lower));
+    }
+    lower = LATENCY_BUCKETS[i];
+  }
+  return h.max;
+}
+
+export class Observability {
+  constructor({ sinkPath = null } = {}) {
+    this.sinkPath = sinkPath;
+    this.counters = new Map();
+    this.gauges = new Map();
+    this.histograms = new Map();
+    this.startedAt = new Date().toISOString();
+  }
+
+  /* ------------------------------------------------ write paths -------- */
+
+  inc(key, n = 1) {
+    const k = slugKey(key);
+    this.counters.set(k, (this.counters.get(k) ?? 0) + n);
+    return this.counters.get(k);
+  }
+
+  setGauge(key, value) {
+    this.gauges.set(slugKey(key), value);
+  }
+
+  observe(key, ms) {
+    const k = slugKey(key);
+    let h = this.histograms.get(k);
+    if (!h) { h = newHistogram(); this.histograms.set(k, h); }
+    const v = Number(ms);
+    if (!Number.isFinite(v)) return;
+    h.n += 1;
+    h.sum += v;
+    if (v < h.min) h.min = v;
+    if (v > h.max) h.max = v;
+    const idx = LATENCY_BUCKETS.findIndex((b) => v <= b);
+    h.buckets[idx < 0 ? LATENCY_BUCKETS.length - 1 : idx] += 1;
+  }
+
+  /** Append an event line to the sink (no-op without a sinkPath). */
+  journal({ event, ...fields }) {
+    if (!this.sinkPath) return;
+    mkdirSync(dirname(this.sinkPath), { recursive: true });
+    appendFileSync(this.sinkPath, JSON.stringify({ at: new Date().toISOString(), event, ...fields }) + "\n");
+  }
+
+  /** Append a full state snapshot line to the sink (no-op without a sinkPath). */
+  flush() {
+    if (!this.sinkPath) return;
+    mkdirSync(dirname(this.sinkPath), { recursive: true });
+    appendFileSync(this.sinkPath, JSON.stringify({ type: "snapshot", ...this.snapshot() }) + "\n");
+  }
+
+  /* ------------------------------------------------ read paths --------- */
+
+  snapshot() {
+    const histograms = {};
+    for (const [k, h] of this.histograms) {
+      histograms[k] = { n: h.n, sum: h.sum, min: h.min, max: h.max, p50: percentile(h, 0.5), p95: percentile(h, 0.95) };
+    }
+    return {
+      at: new Date().toISOString(),
+      startedAt: this.startedAt,
+      counters: Object.fromEntries(this.counters),
+      gauges: Object.fromEntries(this.gauges),
+      histograms,
+    };
+  }
+
+  /** One-glance human view for CLI / dashboards. */
+  summary() {
+    const s = this.snapshot();
+    const lines = [
+      `pillar metrics (since ${s.startedAt}) — ${this.counters.size} counters, ${this.gauges.size} gauges, ${this.histograms.size} histograms`,
+    ];
+    for (const [k, v] of Object.entries(s.counters).sort()) lines.push(`  ${k.padEnd(48)} ${v}`);
+    for (const [k, v] of Object.entries(s.gauges).sort()) lines.push(`  ${k.padEnd(48)} = ${v}`);
+    for (const [k, h] of Object.entries(s.histograms).sort()) {
+      lines.push(`  ${k.padEnd(48)} n=${h.n} min=${h.min}ms p50=${h.p50}ms p95=${h.p95}ms max=${h.max}ms`);
+    }
+    return lines.join("\n");
+  }
+}