@provenonce/sdk 0.8.0 → 0.10.0

package/dist/index.js

@@ -20,7 +20,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AuthError: () => AuthError,
   BeatAgent: () => BeatAgent,
+  ErrorCode: () => ErrorCode,
+  FrozenError: () => FrozenError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  ProvenonceError: () => ProvenonceError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  StateError: () => StateError,
+  ValidationError: () => ValidationError,
   computeBeat: () => computeBeat,
   computeBeatsLite: () => computeBeatsLite,
   generateWalletKeypair: () => generateWalletKeypair,
@@ -30,6 +40,106 @@ module.exports = __toCommonJS(index_exports);
 
 // src/beat-sdk.ts
 var import_crypto = require("crypto");
+
+// src/errors.ts
+var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
+  ErrorCode2["VALIDATION"] = "VALIDATION";
+  ErrorCode2["AUTH_INVALID"] = "AUTH_INVALID";
+  ErrorCode2["AUTH_MISSING"] = "AUTH_MISSING";
+  ErrorCode2["RATE_LIMITED"] = "RATE_LIMITED";
+  ErrorCode2["AGENT_FROZEN"] = "AGENT_FROZEN";
+  ErrorCode2["AGENT_NOT_INITIALIZED"] = "AGENT_NOT_INITIALIZED";
+  ErrorCode2["AGENT_WRONG_STATE"] = "AGENT_WRONG_STATE";
+  ErrorCode2["NOT_FOUND"] = "NOT_FOUND";
+  ErrorCode2["NETWORK_ERROR"] = "NETWORK_ERROR";
+  ErrorCode2["TIMEOUT"] = "TIMEOUT";
+  ErrorCode2["SERVER_ERROR"] = "SERVER_ERROR";
+  return ErrorCode2;
+})(ErrorCode || {});
+var ProvenonceError = class extends Error {
+  constructor(message, code, statusCode, details) {
+    super(message);
+    this.name = "ProvenonceError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ValidationError = class extends ProvenonceError {
+  constructor(message, details) {
+    super(message, "VALIDATION" /* VALIDATION */, void 0, details);
+    this.name = "ValidationError";
+  }
+};
+var AuthError = class extends ProvenonceError {
+  constructor(message, code = "AUTH_INVALID" /* AUTH_INVALID */, statusCode) {
+    super(message, code, statusCode);
+    this.name = "AuthError";
+  }
+};
+var RateLimitError = class extends ProvenonceError {
+  constructor(message, statusCode = 429, retryAfterMs) {
+    super(message, "RATE_LIMITED" /* RATE_LIMITED */, statusCode);
+    this.name = "RateLimitError";
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var FrozenError = class extends ProvenonceError {
+  constructor(message = "Agent is frozen. Use resync() to re-establish provenance.") {
+    super(message, "AGENT_FROZEN" /* AGENT_FROZEN */);
+    this.name = "FrozenError";
+  }
+};
+var StateError = class extends ProvenonceError {
+  constructor(message, currentState, code = "AGENT_WRONG_STATE" /* AGENT_WRONG_STATE */) {
+    super(message, code);
+    this.name = "StateError";
+    this.currentState = currentState;
+  }
+};
+var NotFoundError = class extends ProvenonceError {
+  constructor(message, statusCode = 404) {
+    super(message, "NOT_FOUND" /* NOT_FOUND */, statusCode);
+    this.name = "NotFoundError";
+  }
+};
+var NetworkError = class extends ProvenonceError {
+  constructor(message, code = "NETWORK_ERROR" /* NETWORK_ERROR */) {
+    super(message, code);
+    this.name = "NetworkError";
+  }
+};
+var ServerError = class extends ProvenonceError {
+  constructor(message, statusCode = 500) {
+    super(message, "SERVER_ERROR" /* SERVER_ERROR */, statusCode);
+    this.name = "ServerError";
+  }
+};
+function mapApiError(statusCode, body, path) {
+  const msg = typeof body.error === "string" ? body.error : `API error ${statusCode}`;
+  if (statusCode === 401 || statusCode === 403) {
+    const code = statusCode === 401 ? "AUTH_MISSING" /* AUTH_MISSING */ : "AUTH_INVALID" /* AUTH_INVALID */;
+    return new AuthError(msg, code, statusCode);
+  }
+  if (statusCode === 429) {
+    const retryAfter = typeof body.retry_after_ms === "number" ? body.retry_after_ms : void 0;
+    return new RateLimitError(msg, statusCode, retryAfter);
+  }
+  if (statusCode === 404) {
+    return new NotFoundError(msg, statusCode);
+  }
+  if (statusCode >= 500) {
+    return new ServerError(msg, statusCode);
+  }
+  const lowerMsg = msg.toLowerCase();
+  if (lowerMsg.includes("frozen")) {
+    return new FrozenError(msg);
+  }
+  return new ProvenonceError(msg, "SERVER_ERROR" /* SERVER_ERROR */, statusCode);
+}
+
+// src/beat-sdk.ts
 function computeBeat(prevHash, beatIndex, difficulty, nonce, anchorHash) {
   const timestamp = Date.now();
   const seed = anchorHash ? `${prevHash}:${beatIndex}:${nonce || ""}:${anchorHash}` : `${prevHash}:${beatIndex}:${nonce || ""}`;
@@ -58,16 +168,16 @@ function signMessage(secretKeyHex, message) {
 }
 async function register(name, options) {
   if (!name || typeof name !== "string" || name.trim().length === 0) {
-    throw new Error("name is required (must be a non-empty string)");
+    throw new ValidationError("name is required (must be a non-empty string)");
   }
   if (name.length > 64) {
-    throw new Error("name must be 64 characters or fewer");
+    throw new ValidationError("name must be 64 characters or fewer");
   }
   const url = options?.registryUrl || "https://provenonce.io";
   try {
     new URL(url);
   } catch {
-    throw new Error("registryUrl is not a valid URL");
+    throw new ValidationError("registryUrl is not a valid URL");
   }
   const headers = { "Content-Type": "application/json" };
   if (options?.registrationSecret) {
@@ -86,17 +196,17 @@ async function register(name, options) {
     try {
       data2 = await res2.json();
     } catch {
-      throw new Error(`Registration failed: ${res2.status} ${res2.statusText} (non-JSON response)`);
+      throw new NetworkError(`Registration failed: ${res2.status} ${res2.statusText} (non-JSON response)`);
     }
-    if (!res2.ok) throw new Error(data2.error || "Registration failed");
+    if (!res2.ok) throw mapApiError(res2.status, data2, "/api/v1/register");
     return data2;
   }
   if (options?.walletChain === "ethereum") {
     if (!options.walletAddress || !options.walletSignFn) {
-      throw new Error("Ethereum registration requires walletAddress and walletSignFn");
+      throw new ValidationError("Ethereum registration requires walletAddress and walletSignFn");
     }
     if (!/^0x[0-9a-fA-F]{40}$/.test(options.walletAddress)) {
-      throw new Error("walletAddress must be a valid Ethereum address (0x + 40 hex chars)");
+      throw new ValidationError("walletAddress must be a valid Ethereum address (0x + 40 hex chars)");
     }
     const challengeRes = await fetch(`${url}/api/v1/register`, {
       method: "POST",
@@ -107,10 +217,10 @@ async function register(name, options) {
     try {
       challengeData = await challengeRes.json();
     } catch {
-      throw new Error(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
+      throw new NetworkError(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
     }
     if (!challengeRes.ok || !challengeData.nonce) {
-      throw new Error(challengeData.error || "Failed to get registration challenge");
+      throw mapApiError(challengeRes.status, challengeData, "/api/v1/register");
     }
     const nonce = challengeData.nonce;
     const message = `provenonce-register-ethereum:${nonce}:${options.walletAddress}:${name}`;
@@ -131,9 +241,9 @@ async function register(name, options) {
     try {
       data2 = await registerRes.json();
     } catch {
-      throw new Error(`Ethereum registration failed: ${registerRes.status} (non-JSON response)`);
+      throw new NetworkError(`Ethereum registration failed: ${registerRes.status} (non-JSON response)`);
     }
-    if (!registerRes.ok) throw new Error(data2.error || "Registration failed");
+    if (!registerRes.ok) throw mapApiError(registerRes.status, data2, "/api/v1/register");
     data2.wallet = {
       public_key: "",
       secret_key: "",
@@ -144,7 +254,7 @@ async function register(name, options) {
   }
   if (options?.walletModel === "operator") {
     if (!options.operatorWalletAddress || !options.operatorSignFn) {
-      throw new Error("Operator registration requires operatorWalletAddress and operatorSignFn");
+      throw new ValidationError("Operator registration requires operatorWalletAddress and operatorSignFn");
     }
     const challengeRes = await fetch(`${url}/api/v1/register`, {
       method: "POST",
@@ -155,10 +265,10 @@ async function register(name, options) {
     try {
       challengeData = await challengeRes.json();
     } catch {
-      throw new Error(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
+      throw new NetworkError(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
     }
     if (!challengeRes.ok || !challengeData.nonce) {
-      throw new Error(challengeData.error || "Failed to get registration challenge");
+      throw mapApiError(challengeRes.status, challengeData, "/api/v1/register");
     }
     const nonce = challengeData.nonce;
     const message = `provenonce-register-operator:${nonce}:${options.operatorWalletAddress}:${name}`;
@@ -179,9 +289,9 @@ async function register(name, options) {
     try {
       data2 = await registerRes.json();
     } catch {
-      throw new Error(`Operator registration failed: ${registerRes.status} (non-JSON response)`);
+      throw new NetworkError(`Operator registration failed: ${registerRes.status} (non-JSON response)`);
     }
-    if (!registerRes.ok) throw new Error(data2.error || "Registration failed");
+    if (!registerRes.ok) throw mapApiError(registerRes.status, data2, "/api/v1/register");
     const addr = data2.wallet?.address || data2.wallet?.solana_address || options.operatorWalletAddress;
     data2.wallet = {
       public_key: "",
@@ -215,10 +325,12 @@ async function register(name, options) {
     try {
       challengeData = await challengeRes.json();
     } catch {
-      throw new Error(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
+      const err = new NetworkError(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
+      err.walletKeys = { publicKey: walletKeys.publicKey, secretKey: walletKeys.secretKey };
+      throw err;
     }
     if (!challengeRes.ok || !challengeData.nonce) {
-      const err = new Error(challengeData.error || "Failed to get registration challenge");
+      const err = mapApiError(challengeRes.status, challengeData, "/api/v1/register");
       err.walletKeys = { publicKey: walletKeys.publicKey, secretKey: walletKeys.secretKey };
       throw err;
     }
@@ -240,12 +352,12 @@ async function register(name, options) {
     try {
       data2 = await registerRes.json();
     } catch {
-      const err = new Error(`Registration failed: ${registerRes.status} (non-JSON response)`);
+      const err = new NetworkError(`Registration failed: ${registerRes.status} (non-JSON response)`);
       err.walletKeys = { publicKey: walletKeys.publicKey, secretKey: walletKeys.secretKey };
       throw err;
     }
     if (!registerRes.ok) {
-      const err = new Error(data2.error || "Registration failed");
+      const err = mapApiError(registerRes.status, data2, "/api/v1/register");
       err.walletKeys = { publicKey: walletKeys.publicKey, secretKey: walletKeys.secretKey };
       throw err;
     }
@@ -268,9 +380,9 @@ async function register(name, options) {
   try {
     data = await res.json();
   } catch {
-    throw new Error(`Registration failed: ${res.status} ${res.statusText} (non-JSON response)`);
+    throw new NetworkError(`Registration failed: ${res.status} ${res.statusText} (non-JSON response)`);
   }
-  if (!res.ok) throw new Error(data.error || "Registration failed");
+  if (!res.ok) throw mapApiError(res.status, data, "/api/v1/register");
   return data;
 }
 var BeatAgent = class {
@@ -285,30 +397,36 @@ var BeatAgent = class {
     this.heartbeatInterval = null;
     this.globalBeat = 0;
     this.globalAnchorHash = "";
+    // ── PHASE 2: SIGIL + HEARTBEAT + PROOF ──
+    /** Cached lineage proof from the most recent heartbeat or SIGIL purchase */
+    this.cachedProof = null;
     if (!config.apiKey || typeof config.apiKey !== "string") {
-      throw new Error("BeatAgentConfig.apiKey is required (must be a non-empty string)");
+      throw new ValidationError("BeatAgentConfig.apiKey is required (must be a non-empty string)");
     }
     if (!config.registryUrl || typeof config.registryUrl !== "string") {
-      throw new Error("BeatAgentConfig.registryUrl is required (must be a non-empty string)");
+      throw new ValidationError("BeatAgentConfig.registryUrl is required (must be a non-empty string)");
     }
     try {
       new URL(config.registryUrl);
     } catch {
-      throw new Error("BeatAgentConfig.registryUrl is not a valid URL");
+      throw new ValidationError("BeatAgentConfig.registryUrl is not a valid URL");
     }
     if (config.beatsPerPulse !== void 0 && (!Number.isInteger(config.beatsPerPulse) || config.beatsPerPulse < 1 || config.beatsPerPulse > 1e4)) {
-      throw new Error("BeatAgentConfig.beatsPerPulse must be an integer between 1 and 10000");
+      throw new ValidationError("BeatAgentConfig.beatsPerPulse must be an integer between 1 and 10000");
     }
     if (config.checkinIntervalSec !== void 0 && (!Number.isFinite(config.checkinIntervalSec) || config.checkinIntervalSec < 10 || config.checkinIntervalSec > 86400)) {
-      throw new Error("BeatAgentConfig.checkinIntervalSec must be between 10 and 86400");
+      throw new ValidationError("BeatAgentConfig.checkinIntervalSec must be between 10 and 86400");
     }
     this.config = {
       beatsPerPulse: 10,
       checkinIntervalSec: 300,
+      heartbeatIntervalSec: 300,
       onPulse: () => {
       },
       onCheckin: () => {
       },
+      onHeartbeat: () => {
+      },
       onError: () => {
       },
       onStatusChange: () => {
@@ -357,16 +475,21 @@ var BeatAgent = class {
   }
   // ── PULSE (COMPUTE BEATS) ──
   /**
+   * @deprecated Phase 2: VDF computation retired (D-68). Payment is the liveness mechanism.
+   * Use heartbeat() instead. This method will be removed in the next major version.
+   *
    * Compute N beats locally (VDF hash chain).
-   * This is the "heartbeat" — proof that the agent has lived 
-   * through a specific window of computational time.
    */
   pulse(count) {
+    console.warn("[Provenonce SDK] pulse() is deprecated. Use heartbeat() instead (Phase 2).");
+    if (this.status === "frozen") {
+      throw new FrozenError("Cannot pulse: agent is frozen. Use resync() to re-establish provenance.");
+    }
     if (this.status !== "active") {
-      throw new Error(`Cannot pulse: agent is ${this.status}. Use resync() if frozen.`);
+      throw new StateError(`Cannot pulse: agent is ${this.status}.`, this.status);
     }
     if (count !== void 0 && (!Number.isInteger(count) || count < 1 || count > 1e4)) {
-      throw new Error("pulse count must be an integer between 1 and 10000");
+      throw new ValidationError("pulse count must be an integer between 1 and 10000");
     }
     return this.computeBeats(count);
   }
@@ -374,7 +497,7 @@ var BeatAgent = class {
   computeBeats(count, onProgress) {
     const n = count || this.config.beatsPerPulse;
     if (!this.latestBeat) {
-      throw new Error("Beat chain not initialized. Call init() first.");
+      throw new StateError("Beat chain not initialized. Call init() first.", "uninitialized", "AGENT_NOT_INITIALIZED" /* AGENT_NOT_INITIALIZED */);
     }
     const newBeats = [];
     let prevHash = this.latestBeat.hash;
@@ -402,12 +525,11 @@ var BeatAgent = class {
   }
   // ── CHECK-IN ──
   /**
-   * Submit a Beat proof to the registry.
-   * 
-   * "To remain on the Whitelist, an agent must periodically 
-   *  submit a proof of its Local Beats to the Registry."
+   * @deprecated Phase 2: VDF check-in retired (D-68). Use heartbeat() instead.
+   * This method will be removed in the next major version.
    */
   async checkin() {
+    console.warn("[Provenonce SDK] checkin() is deprecated. Use heartbeat() instead (Phase 2).");
     if (!this.latestBeat || this.latestBeat.index <= this.lastCheckinBeat) {
       this.log("No new beats since last check-in. Call pulse() first.");
       return { ok: true, total_beats: this.totalBeats };
@@ -461,18 +583,21 @@ var BeatAgent = class {
   // ── AUTONOMOUS HEARTBEAT ──
   /**
    * Start the autonomous heartbeat loop.
-   * Computes beats continuously and checks in periodically.
-   * This is "keeping the agent alive" in Beat time.
+   * Phase 2: Sends paid heartbeats at regular intervals.
+   *
+   * @param paymentTxFn - Optional function that returns a payment tx for each heartbeat.
+   *                      If not provided, uses 'devnet-skip' (devnet only).
    */
-  startHeartbeat() {
+  startHeartbeat(paymentTxFn) {
     if (this.heartbeatInterval) {
       this.log("Heartbeat already running.");
       return;
     }
-    if (this.status !== "active") {
-      throw new Error(`Cannot start heartbeat in status '${this.status}'.`);
+    if (this.status !== "active" && this.status !== "uninitialized") {
+      throw new StateError(`Cannot start heartbeat in status '${this.status}'.`, this.status);
     }
-    this.log("\u2661 Starting heartbeat...");
+    const intervalSec = this.config.heartbeatIntervalSec || this.config.checkinIntervalSec || 300;
+    this.log(`Starting heartbeat (interval: ${intervalSec}s)...`);
     let consecutiveErrors = 0;
     let skipCount = 0;
     this.heartbeatInterval = setInterval(async () => {
@@ -481,13 +606,8 @@ var BeatAgent = class {
         return;
       }
       try {
-        this.pulse();
-        const beatsSinceCheckin = this.latestBeat.index - this.lastCheckinBeat;
-        const shouldCheckin = beatsSinceCheckin >= this.config.beatsPerPulse * 5;
-        if (shouldCheckin) {
-          await this.checkin();
-          await this.syncGlobal();
-        }
+        const paymentTx = paymentTxFn ? await paymentTxFn() : "devnet-skip";
+        await this.heartbeat(paymentTx);
         consecutiveErrors = 0;
       } catch (err) {
         consecutiveErrors++;
@@ -495,28 +615,25 @@ var BeatAgent = class {
         skipCount = Math.min(32, Math.pow(2, consecutiveErrors - 1));
         this.log(`Heartbeat error #${consecutiveErrors}, backing off ${skipCount} ticks`);
       }
-    }, this.config.checkinIntervalSec * 1e3 / 10);
+    }, intervalSec * 1e3);
   }
   /**
-   * Stop the heartbeat. Agent's time "freezes."
-   * Must call resync() when waking up.
+   * Stop the heartbeat loop.
    */
   stopHeartbeat() {
     if (this.heartbeatInterval) {
       clearInterval(this.heartbeatInterval);
       this.heartbeatInterval = null;
-      this.log("\u2661 Heartbeat stopped. Time frozen.");
+      this.log("Heartbeat stopped.");
     }
   }
   // ── RE-SYNC ──
   /**
-   * Re-sync after being offline/frozen.
-   * 
-   * "When an agent powers down, its time 'freezes.' Upon waking,
-   *  it must perform a Re-Sync Challenge with the Registry to 
-   *  fill the 'Temporal Gap' and re-establish its provenance."
+   * @deprecated Phase 2: Resync retired (D-67). Dormancy resume is free — just call heartbeat().
+   * This method will be removed in the next major version.
    */
   async resync() {
+    console.warn("[Provenonce SDK] resync() is deprecated (D-67). Use heartbeat() to resume (Phase 2).");
     try {
       this.log("Requesting re-sync challenge...");
       const challenge = await this.api("POST", "/api/v1/agent/resync", {
@@ -580,10 +697,10 @@ var BeatAgent = class {
     try {
       if (childName !== void 0) {
         if (typeof childName !== "string" || childName.trim().length === 0) {
-          throw new Error("childName must be a non-empty string");
+          throw new ValidationError("childName must be a non-empty string");
         }
         if (childName.length > 64) {
-          throw new Error("childName must be 64 characters or fewer");
+          throw new ValidationError("childName must be 64 characters or fewer");
         }
       }
       const res = await this.api("POST", "/api/v1/agent/spawn", {
@@ -601,6 +718,210 @@ var BeatAgent = class {
       throw err;
     }
   }
+  /**
+   * Purchase a SIGIL (cryptographic identity) for this agent.
+   * SIGILs gate heartbeating, lineage proofs, and offline verification.
+   * One-time purchase — cannot be re-purchased.
+   *
+   * @param options - SIGIL purchase options (identity_class, principal, tier, name, payment_tx, + optional metadata)
+   *
+   * Legacy signature (deprecated):
+   * @param identityClass - 'narrow_task' | 'autonomous' | 'orchestrator'
+   * @param paymentTx - Solana transaction signature or 'devnet-skip'
+   */
+  async purchaseSigil(optionsOrClass, paymentTx) {
+    let body;
+    if (typeof optionsOrClass === "string") {
+      if (!optionsOrClass || !["narrow_task", "autonomous", "orchestrator"].includes(optionsOrClass)) {
+        throw new ValidationError("identityClass must be narrow_task, autonomous, or orchestrator");
+      }
+      if (!paymentTx || typeof paymentTx !== "string") {
+        throw new ValidationError('paymentTx is required (Solana transaction signature or "devnet-skip")');
+      }
+      body = {
+        identity_class: optionsOrClass,
+        payment_tx: paymentTx
+        // Legacy calls without principal/tier — server will require these now
+        // Callers must migrate to the options object form
+      };
+    } else {
+      const opts = optionsOrClass;
+      if (!opts.identity_class || !["narrow_task", "autonomous", "orchestrator"].includes(opts.identity_class)) {
+        throw new ValidationError("identity_class must be narrow_task, autonomous, or orchestrator");
+      }
+      if (!opts.principal || typeof opts.principal !== "string") {
+        throw new ValidationError("principal is required");
+      }
+      if (!opts.tier || !["sov", "org", "ind", "eph", "sbx"].includes(opts.tier)) {
+        throw new ValidationError("tier must be one of: sov, org, ind, eph, sbx");
+      }
+      if (!opts.payment_tx || typeof opts.payment_tx !== "string") {
+        throw new ValidationError("payment_tx is required");
+      }
+      body = { ...opts };
+    }
+    try {
+      const res = await this.api("POST", "/api/v1/sigil", body);
+      if (res.lineage_proof) {
+        this.cachedProof = res.lineage_proof;
+      }
+      const sigilStr = res.sigil?.sigil || res.sigil?.identity_class || "";
+      this.log(`SIGIL purchased: ${sigilStr}`);
+      this.config.onStatusChange("sigil_issued", { sigil: sigilStr });
+      return {
+        ok: true,
+        sigil: res.sigil,
+        lineage_proof: res.lineage_proof,
+        fee: res.fee
+      };
+    } catch (err) {
+      this.config.onError(err, "purchaseSigil");
+      return { ok: false, error: err.message };
+    }
+  }
+  /**
+   * Update mutable SIGIL metadata fields.
+   * Requires a SIGIL. Cannot modify immutable fields.
+   *
+   * @param fields - Subset of mutable SIGIL fields to update
+   */
+  async updateMetadata(fields) {
+    if (!fields || Object.keys(fields).length === 0) {
+      throw new ValidationError("At least one metadata field is required");
+    }
+    try {
+      const res = await this.api("PATCH", "/api/v1/agent/metadata", fields);
+      this.log(`Metadata updated: ${res.updated_fields?.join(", ") || "unknown"}`);
+      return {
+        ok: true,
+        sigil: res.sigil,
+        generation: res.generation,
+        updated_fields: res.updated_fields
+      };
+    } catch (err) {
+      this.config.onError(err, "updateMetadata");
+      return { ok: false, error: err.message };
+    }
+  }
+  /**
+   * Send a paid heartbeat to the registry.
+   * Requires a SIGIL. Returns a signed lineage proof.
+   * This is the Phase 2 replacement for pulse() + checkin().
+   *
+   * @param paymentTx - Solana transaction signature. Omit or 'devnet-skip' on devnet.
+   * @param globalAnchor - Optional: the global anchor index to reference.
+   */
+  async heartbeat(paymentTx, globalAnchor) {
+    try {
+      const res = await this.api("POST", "/api/v1/agent/heartbeat", {
+        payment_tx: paymentTx || "devnet-skip",
+        global_anchor: globalAnchor
+      });
+      if (res.lineage_proof) {
+        this.cachedProof = res.lineage_proof;
+      }
+      if (res.ok) {
+        this.status = "active";
+        const onHb = this.config.onHeartbeat || this.config.onCheckin;
+        if (onHb) onHb(res);
+        this.log(`Heartbeat accepted: epoch=${res.billing_epoch}, count=${res.heartbeat_count_epoch}`);
+      }
+      return {
+        ok: res.ok,
+        lineage_proof: res.lineage_proof,
+        heartbeat_count_epoch: res.heartbeat_count_epoch,
+        billing_epoch: res.billing_epoch,
+        current_beat: res.current_beat,
+        fee: res.fee
+      };
+    } catch (err) {
+      this.config.onError(err, "heartbeat");
+      return { ok: false, error: err.message };
+    }
+  }
+  /**
+   * Reissue a lineage proof. "Reprint, not a renewal."
+   * Does NOT create a new lineage event.
+   *
+   * @param paymentTx - Solana transaction signature. Omit or 'devnet-skip' on devnet.
+   */
+  async reissueProof(paymentTx) {
+    try {
+      const res = await this.api("POST", "/api/v1/agent/reissue-proof", {
+        payment_tx: paymentTx || "devnet-skip"
+      });
+      if (res.lineage_proof) {
+        this.cachedProof = res.lineage_proof;
+      }
+      return { ok: true, lineage_proof: res.lineage_proof };
+    } catch (err) {
+      this.config.onError(err, "reissueProof");
+      return { ok: false, error: err.message };
+    }
+  }
+  /**
+   * Get the latest cached lineage proof (no network call).
+   * Returns null if no proof has been obtained yet.
+   */
+  getLatestProof() {
+    return this.cachedProof;
+  }
+  /**
+   * Get the agent's passport (alias for getLatestProof).
+   * The passport is the agent's portable, offline-verifiable credential.
+   * Returns null if no passport has been issued yet (requires SIGIL + heartbeat).
+   */
+  getPassport() {
+    return this.cachedProof;
+  }
+  /**
+   * Verify a lineage proof locally using the authority public key.
+   * Offline verification — no API call, no SOL cost.
+   *
+   * Returns a VerificationResult object. The object is truthy when valid,
+   * so `if (BeatAgent.verifyProofLocally(proof, key))` still works.
+   *
+   * @param proof - The LineageProof to verify
+   * @param authorityPubKeyHex - 32-byte hex-encoded Ed25519 public key from /.well-known/provenonce-authority.json
+   * @param currentBeat - Optional current global beat index (for beatsSinceHeartbeat calculation)
+   */
+  static verifyProofLocally(proof, authorityPubKeyHex, currentBeat) {
+    const now = Date.now();
+    const expired = now > proof.valid_until;
+    let signatureValid = false;
+    try {
+      const canonical = JSON.stringify({
+        agent_hash: proof.agent_hash,
+        agent_public_key: proof.agent_public_key,
+        identity_class: proof.identity_class,
+        registered_at_beat: proof.registered_at_beat,
+        sigil_issued_at_beat: proof.sigil_issued_at_beat,
+        last_heartbeat_beat: proof.last_heartbeat_beat,
+        lineage_chain_hash: proof.lineage_chain_hash,
+        issued_at: proof.issued_at,
+        valid_until: proof.valid_until
+      });
+      const pubBytes = Buffer.from(authorityPubKeyHex, "hex");
+      if (pubBytes.length === 32) {
+        const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+        const pubKeyDer = Buffer.concat([ED25519_SPKI_PREFIX, pubBytes]);
+        const keyObject = (0, import_crypto.createPublicKey)({ key: pubKeyDer, format: "der", type: "spki" });
+        const sigBuffer = Buffer.from(proof.provenonce_signature, "hex");
+        signatureValid = (0, import_crypto.verify)(null, Buffer.from(canonical), keyObject, sigBuffer);
+      }
+    } catch {
+      signatureValid = false;
+    }
+    const valid = signatureValid && !expired;
+    const beatsSinceHeartbeat = currentBeat != null ? currentBeat - proof.last_heartbeat_beat : null;
+    let warning;
+    if (expired) {
+      warning = "Proof has expired. Reissue with reissueProof() or send a heartbeat.";
+    } else if (beatsSinceHeartbeat != null && beatsSinceHeartbeat > 60) {
+      warning = `Agent is ${beatsSinceHeartbeat} beats behind. Heartbeat may be stale.`;
+    }
+    return { valid, signatureValid, expired, lastHeartbeatBeat: proof.last_heartbeat_beat, beatsSinceHeartbeat, warning };
+  }
   // ── STATUS ──
   /**
    * Get this agent's full beat status from the registry.
@@ -682,16 +1003,15 @@ var BeatAgent = class {
       try {
         data = await res.json();
       } catch {
-        throw new Error(`API error: ${res.status} non-JSON response from ${path}`);
+        throw new NetworkError(`API error: ${res.status} non-JSON response from ${path}`);
       }
       if (!res.ok && !data.ok && !data.already_initialized && !data.eligible) {
-        const serverMsg = typeof data.error === "string" ? data.error : `API error ${res.status}`;
-        throw new Error(serverMsg);
+        throw mapApiError(res.status, data, path);
       }
       return data;
     } catch (err) {
       if (err.name === "AbortError") {
-        throw new Error(`Request timeout: ${method} ${path}`);
+        throw new NetworkError(`Request timeout: ${method} ${path}`, "TIMEOUT" /* TIMEOUT */);
       }
       throw err;
     } finally {
@@ -706,10 +1026,10 @@ var BeatAgent = class {
 };
 function computeBeatsLite(startHash, startIndex, count, difficulty = 1e3, anchorHash) {
   if (!startHash || typeof startHash !== "string") {
-    throw new Error("computeBeatsLite: startHash must be a non-empty string");
+    throw new ValidationError("computeBeatsLite: startHash must be a non-empty string");
   }
   if (!Number.isInteger(count) || count < 1) {
-    throw new Error("computeBeatsLite: count must be a positive integer");
+    throw new ValidationError("computeBeatsLite: count must be a positive integer");
   }
   const t0 = Date.now();
   let prev = startHash;
@@ -722,7 +1042,17 @@ function computeBeatsLite(startHash, startIndex, count, difficulty = 1e3, anchor
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AuthError,
   BeatAgent,
+  ErrorCode,
+  FrozenError,
+  NetworkError,
+  NotFoundError,
+  ProvenonceError,
+  RateLimitError,
+  ServerError,
+  StateError,
+  ValidationError,
   computeBeat,
   computeBeatsLite,
   generateWalletKeypair,