@provenonce/sdk 0.6.0 → 0.9.0

package/dist/index.mjs

@@ -1,5 +1,105 @@
 // src/beat-sdk.ts
-import { createHash } from "crypto";
+import { createHash, generateKeyPairSync, sign, verify, createPrivateKey, createPublicKey } from "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 || ""}`;
@@ -9,26 +109,240 @@ function computeBeat(prevHash, beatIndex, difficulty, nonce, anchorHash) {
   }
   return { index: beatIndex, hash: current, prev: prevHash, timestamp, nonce, anchor_hash: anchorHash };
 }
+var ED25519_PKCS8_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+function generateWalletKeypair() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const pubRaw = publicKey.export({ type: "spki", format: "der" }).subarray(12);
+  const privRaw = privateKey.export({ type: "pkcs8", format: "der" }).subarray(16);
+  return {
+    publicKey: Buffer.from(pubRaw).toString("hex"),
+    secretKey: Buffer.from(privRaw).toString("hex")
+  };
+}
+function signMessage(secretKeyHex, message) {
+  const privRaw = Buffer.from(secretKeyHex, "hex");
+  const privKeyDer = Buffer.concat([ED25519_PKCS8_PREFIX, privRaw]);
+  const keyObject = createPrivateKey({ key: privKeyDer, format: "der", type: "pkcs8" });
+  const sig = sign(null, Buffer.from(message), keyObject);
+  return Buffer.from(sig).toString("hex");
+}
 async function register(name, options) {
-  const url = options?.registryUrl || "https://provenonce.vercel.app";
-  const body = { name };
-  const headers = { "Content-Type": "application/json" };
-  if (options?.parentHash) {
-    body.parent = options.parentHash;
+  if (!name || typeof name !== "string" || name.trim().length === 0) {
+    throw new ValidationError("name is required (must be a non-empty string)");
+  }
+  if (name.length > 64) {
+    throw new ValidationError("name must be 64 characters or fewer");
   }
-  if (options?.parentApiKey) {
-    headers["Authorization"] = `Bearer ${options.parentApiKey}`;
+  const url = options?.registryUrl || "https://provenonce.io";
+  try {
+    new URL(url);
+  } catch {
+    throw new ValidationError("registryUrl is not a valid URL");
   }
+  const headers = { "Content-Type": "application/json" };
   if (options?.registrationSecret) {
     headers["x-registration-secret"] = options.registrationSecret;
   }
+  if (options?.parentHash) {
+    if (options.parentApiKey) {
+      headers["Authorization"] = `Bearer ${options.parentApiKey}`;
+    }
+    const res2 = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ name, parent: options.parentHash, ...options.metadata && { metadata: options.metadata } })
+    });
+    let data2;
+    try {
+      data2 = await res2.json();
+    } catch {
+      throw new NetworkError(`Registration failed: ${res2.status} ${res2.statusText} (non-JSON response)`);
+    }
+    if (!res2.ok) throw mapApiError(res2.status, data2, "/api/v1/register");
+    return data2;
+  }
+  if (options?.walletChain === "ethereum") {
+    if (!options.walletAddress || !options.walletSignFn) {
+      throw new ValidationError("Ethereum registration requires walletAddress and walletSignFn");
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(options.walletAddress)) {
+      throw new ValidationError("walletAddress must be a valid Ethereum address (0x + 40 hex chars)");
+    }
+    const challengeRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ name, action: "challenge", wallet_chain: "ethereum" })
+    });
+    let challengeData;
+    try {
+      challengeData = await challengeRes.json();
+    } catch {
+      throw new NetworkError(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
+    }
+    if (!challengeRes.ok || !challengeData.nonce) {
+      throw mapApiError(challengeRes.status, challengeData, "/api/v1/register");
+    }
+    const nonce = challengeData.nonce;
+    const message = `provenonce-register-ethereum:${nonce}:${options.walletAddress}:${name}`;
+    const walletSignature = await options.walletSignFn(message);
+    const registerRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name,
+        wallet_chain: "ethereum",
+        wallet_address: options.walletAddress,
+        wallet_signature: walletSignature,
+        wallet_nonce: nonce,
+        ...options.metadata && { metadata: options.metadata }
+      })
+    });
+    let data2;
+    try {
+      data2 = await registerRes.json();
+    } catch {
+      throw new NetworkError(`Ethereum registration failed: ${registerRes.status} (non-JSON response)`);
+    }
+    if (!registerRes.ok) throw mapApiError(registerRes.status, data2, "/api/v1/register");
+    data2.wallet = {
+      public_key: "",
+      secret_key: "",
+      address: data2.wallet?.address || options.walletAddress,
+      chain: "ethereum"
+    };
+    return data2;
+  }
+  if (options?.walletModel === "operator") {
+    if (!options.operatorWalletAddress || !options.operatorSignFn) {
+      throw new ValidationError("Operator registration requires operatorWalletAddress and operatorSignFn");
+    }
+    const challengeRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ name, action: "challenge", wallet_model: "operator" })
+    });
+    let challengeData;
+    try {
+      challengeData = await challengeRes.json();
+    } catch {
+      throw new NetworkError(`Registration challenge failed: ${challengeRes.status} (non-JSON response)`);
+    }
+    if (!challengeRes.ok || !challengeData.nonce) {
+      throw mapApiError(challengeRes.status, challengeData, "/api/v1/register");
+    }
+    const nonce = challengeData.nonce;
+    const message = `provenonce-register-operator:${nonce}:${options.operatorWalletAddress}:${name}`;
+    const walletSignature = await options.operatorSignFn(message);
+    const registerRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name,
+        wallet_model: "operator",
+        operator_wallet_address: options.operatorWalletAddress,
+        wallet_signature: walletSignature,
+        wallet_nonce: nonce,
+        ...options.metadata && { metadata: options.metadata }
+      })
+    });
+    let data2;
+    try {
+      data2 = await registerRes.json();
+    } catch {
+      throw new NetworkError(`Operator registration failed: ${registerRes.status} (non-JSON response)`);
+    }
+    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: "",
+      secret_key: "",
+      solana_address: addr,
+      address: addr,
+      chain: "solana"
+    };
+    return data2;
+  }
+  if (options?.walletModel === "self-custody" || options?.walletSecretKey) {
+    let walletKeys;
+    if (options?.walletSecretKey) {
+      const privRaw = Buffer.from(options.walletSecretKey, "hex");
+      const privKeyDer = Buffer.concat([ED25519_PKCS8_PREFIX, privRaw]);
+      const keyObject = createPrivateKey({ key: privKeyDer, format: "der", type: "pkcs8" });
+      const pubRaw = keyObject.export({ type: "spki", format: "der" }).subarray(12);
+      walletKeys = {
+        publicKey: Buffer.from(pubRaw).toString("hex"),
+        secretKey: options.walletSecretKey
+      };
+    } else {
+      walletKeys = generateWalletKeypair();
+    }
+    const challengeRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ name, action: "challenge" })
+    });
+    let challengeData;
+    try {
+      challengeData = await challengeRes.json();
+    } catch {
+      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 = mapApiError(challengeRes.status, challengeData, "/api/v1/register");
+      err.walletKeys = { publicKey: walletKeys.publicKey, secretKey: walletKeys.secretKey };
+      throw err;
+    }
+    const nonce = challengeData.nonce;
+    const message = `provenonce-register:${nonce}:${walletKeys.publicKey}:${name}`;
+    const walletSignature = signMessage(walletKeys.secretKey, message);
+    const registerRes = await fetch(`${url}/api/v1/register`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name,
+        wallet_public_key: walletKeys.publicKey,
+        wallet_signature: walletSignature,
+        wallet_nonce: nonce,
+        ...options?.metadata && { metadata: options.metadata }
+      })
+    });
+    let data2;
+    try {
+      data2 = await registerRes.json();
+    } catch {
+      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 = mapApiError(registerRes.status, data2, "/api/v1/register");
+      err.walletKeys = { publicKey: walletKeys.publicKey, secretKey: walletKeys.secretKey };
+      throw err;
+    }
+    const addr = data2.wallet?.address || data2.wallet?.solana_address || "";
+    data2.wallet = {
+      public_key: walletKeys.publicKey,
+      secret_key: walletKeys.secretKey,
+      solana_address: addr,
+      address: addr,
+      chain: "solana"
+    };
+    return data2;
+  }
   const res = await fetch(`${url}/api/v1/register`, {
     method: "POST",
     headers,
-    body: JSON.stringify(body)
+    body: JSON.stringify({ name, ...options?.metadata && { metadata: options.metadata } })
   });
-  const data = await res.json();
-  if (!res.ok) throw new Error(data.error || "Registration failed");
+  let data;
+  try {
+    data = await res.json();
+  } catch {
+    throw new NetworkError(`Registration failed: ${res.status} ${res.statusText} (non-JSON response)`);
+  }
+  if (!res.ok) throw mapApiError(res.status, data, "/api/v1/register");
   return data;
 }
 var BeatAgent = class {
@@ -43,13 +357,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 ValidationError("BeatAgentConfig.apiKey is required (must be a non-empty string)");
+    }
+    if (!config.registryUrl || typeof config.registryUrl !== "string") {
+      throw new ValidationError("BeatAgentConfig.registryUrl is required (must be a non-empty string)");
+    }
+    try {
+      new URL(config.registryUrl);
+    } catch {
+      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 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 ValidationError("BeatAgentConfig.checkinIntervalSec must be between 10 and 86400");
+    }
     this.config = {
       beatsPerPulse: 10,
       checkinIntervalSec: 300,
+      heartbeatIntervalSec: 300,
       onPulse: () => {
       },
       onCheckin: () => {
       },
+      onHeartbeat: () => {
+      },
       onError: () => {
       },
       onStatusChange: () => {
@@ -98,26 +435,42 @@ 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) {
-    const n = count || this.config.beatsPerPulse;
-    if (!this.latestBeat) {
-      throw new Error("Beat chain not initialized. Call init() first.");
+    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 in status '${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 ValidationError("pulse count must be an integer between 1 and 10000");
+    }
+    return this.computeBeats(count);
+  }
+  /** Internal beat computation — no status check. Used by both pulse() and resync(). */
+  computeBeats(count, onProgress) {
+    const n = count || this.config.beatsPerPulse;
+    if (!this.latestBeat) {
+      throw new StateError("Beat chain not initialized. Call init() first.", "uninitialized", "AGENT_NOT_INITIALIZED" /* AGENT_NOT_INITIALIZED */);
     }
     const newBeats = [];
     let prevHash = this.latestBeat.hash;
     let startIndex = this.latestBeat.index + 1;
     const t0 = Date.now();
+    const progressInterval = Math.max(1, Math.floor(n / 10));
     for (let i = 0; i < n; i++) {
       const beat = computeBeat(prevHash, startIndex + i, this.difficulty, void 0, this.globalAnchorHash || void 0);
       newBeats.push(beat);
       prevHash = beat.hash;
+      if (onProgress && (i + 1) % progressInterval === 0) {
+        onProgress(i + 1, n);
+      }
     }
     const elapsed = Date.now() - t0;
     this.chain.push(...newBeats);
@@ -132,27 +485,31 @@ 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() {
-    if (!this.latestBeat || this.totalBeats === this.lastCheckinBeat) {
+    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 };
     }
     try {
+      const fromBeat = this.lastCheckinBeat;
+      const toBeat = this.latestBeat.index;
       const spotChecks = [];
-      const available = this.chain.filter((b) => b.index > this.lastCheckinBeat);
-      const sampleCount = Math.min(5, available.length);
+      const toBeatEntry = this.chain.find((b) => b.index === toBeat);
+      if (toBeatEntry) {
+        spotChecks.push({ index: toBeatEntry.index, hash: toBeatEntry.hash, prev: toBeatEntry.prev, nonce: toBeatEntry.nonce });
+      }
+      const available = this.chain.filter((b) => b.index > this.lastCheckinBeat && b.index !== toBeat);
+      const sampleCount = Math.min(4, available.length);
       for (let i = 0; i < sampleCount; i++) {
         const idx = Math.floor(Math.random() * available.length);
         const beat = available[idx];
         spotChecks.push({ index: beat.index, hash: beat.hash, prev: beat.prev, nonce: beat.nonce });
         available.splice(idx, 1);
       }
-      const fromBeat = this.lastCheckinBeat;
-      const toBeat = this.latestBeat.index;
       const fromHash = this.chain.find((b) => b.index === fromBeat)?.hash || this.genesisHash;
       const toHash = this.latestBeat.hash;
       const res = await this.api("POST", "/api/v1/agent/checkin", {
@@ -186,52 +543,57 @@ 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 () => {
+      if (skipCount > 0) {
+        skipCount--;
+        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++;
         this.config.onError(err, "heartbeat");
+        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", {
@@ -243,12 +605,13 @@ var BeatAgent = class {
       const required = challenge.challenge.required_beats;
       this.difficulty = challenge.challenge.difficulty;
       this.log(`Re-sync challenge: compute ${required} beats at D=${this.difficulty}`);
+      await this.syncGlobal();
       const startHash = challenge.challenge.start_from_hash;
       const startBeat = challenge.challenge.start_from_beat;
       this.latestBeat = { index: startBeat, hash: startHash, prev: "", timestamp: Date.now() };
       this.chain = [this.latestBeat];
       const t0 = Date.now();
-      this.pulse(required);
+      this.computeBeats(required);
       const elapsed = Date.now() - t0;
       this.log(`Re-sync beats computed in ${elapsed}ms`);
       const proof = await this.api("POST", "/api/v1/agent/resync", {
@@ -261,7 +624,15 @@ var BeatAgent = class {
           to_hash: this.latestBeat.hash,
           beats_computed: required,
           global_anchor: challenge.challenge.sync_to_global,
-          spot_checks: this.chain.filter((_, i) => i % Math.ceil(required / 5) === 0).slice(0, 5).map((b) => ({ index: b.index, hash: b.hash, prev: b.prev, nonce: b.nonce }))
+          anchor_hash: this.globalAnchorHash || void 0,
+          spot_checks: (() => {
+            const toBeatEntry = this.chain.find((b) => b.index === this.latestBeat.index);
+            const available = this.chain.filter((b) => b.index !== this.latestBeat.index && b.index > startBeat);
+            const step = Math.max(1, Math.ceil(available.length / 5));
+            const others = available.filter((_, i) => i % step === 0).slice(0, 4);
+            const checks = toBeatEntry ? [toBeatEntry, ...others] : others;
+            return checks.map((b) => ({ index: b.index, hash: b.hash, prev: b.prev, nonce: b.nonce }));
+          })()
         }
       });
       if (proof.ok) {
@@ -284,6 +655,14 @@ var BeatAgent = class {
    */
   async requestSpawn(childName, childHash) {
     try {
+      if (childName !== void 0) {
+        if (typeof childName !== "string" || childName.trim().length === 0) {
+          throw new ValidationError("childName must be a non-empty string");
+        }
+        if (childName.length > 64) {
+          throw new ValidationError("childName must be 64 characters or fewer");
+        }
+      }
       const res = await this.api("POST", "/api/v1/agent/spawn", {
         child_name: childName,
         child_hash: childHash
@@ -299,6 +678,147 @@ 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 identityClass - 'narrow_task' (0.05 SOL), 'autonomous' (0.15 SOL), or 'orchestrator' (0.35 SOL)
+   * @param paymentTx - Solana transaction signature proving payment. Use 'devnet-skip' on devnet.
+   */
+  async purchaseSigil(identityClass, paymentTx) {
+    if (!identityClass || !["narrow_task", "autonomous", "orchestrator"].includes(identityClass)) {
+      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")');
+    }
+    try {
+      const res = await this.api("POST", "/api/v1/sigil", {
+        identity_class: identityClass,
+        payment_tx: paymentTx
+      });
+      if (res.lineage_proof) {
+        this.cachedProof = res.lineage_proof;
+      }
+      this.log(`SIGIL purchased: ${identityClass}`);
+      this.config.onStatusChange("sigil_issued", { identity_class: identityClass });
+      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 };
+    }
+  }
+  /**
+   * 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.
+   *
+   * @param proof - The LineageProof to verify
+   * @param authorityPubKeyHex - 32-byte hex-encoded Ed25519 public key from /.well-known/provenonce-authority.json
+   */
+  static verifyProofLocally(proof, authorityPubKeyHex) {
+    try {
+      if (Date.now() > proof.valid_until) {
+        return false;
+      }
+      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) return false;
+      const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+      const pubKeyDer = Buffer.concat([ED25519_SPKI_PREFIX, pubBytes]);
+      const keyObject = createPublicKey({ key: pubKeyDer, format: "der", type: "spki" });
+      const sigBuffer = Buffer.from(proof.provenonce_signature, "hex");
+      return verify(null, Buffer.from(canonical), keyObject, sigBuffer);
+    } catch {
+      return false;
+    }
+  }
   // ── STATUS ──
   /**
    * Get this agent's full beat status from the registry.
@@ -328,7 +848,10 @@ var BeatAgent = class {
   // ── INTERNALS ──
   async syncGlobal() {
     try {
-      const res = await fetch(`${this.config.registryUrl}/api/v1/beat/anchor`);
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 15e3);
+      const res = await fetch(`${this.config.registryUrl}/api/v1/beat/anchor`, { signal: controller.signal });
+      clearTimeout(timeout);
       const data = await res.json();
       if (data.anchor) {
         this.globalBeat = data.anchor.beat_index;
@@ -346,23 +869,51 @@ var BeatAgent = class {
       this.totalBeats = res.total_beats;
       this.genesisHash = res.genesis_hash;
       this.status = res.status;
+      this.difficulty = res.difficulty || this.difficulty;
+      this.lastCheckinBeat = res.last_checkin_beat || 0;
+      if (!this.latestBeat && this.genesisHash) {
+        this.latestBeat = {
+          index: res.latest_beat || this.totalBeats,
+          hash: res.latest_hash || this.genesisHash,
+          prev: "0".repeat(64),
+          timestamp: Date.now()
+        };
+        this.chain = [this.latestBeat];
+      }
     }
     return res;
   }
   async api(method, path, body) {
-    const res = await fetch(`${this.config.registryUrl}${path}`, {
-      method,
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.config.apiKey}`
-      },
-      body: body ? JSON.stringify(body) : void 0
-    });
-    const data = await res.json();
-    if (!res.ok && !data.ok && !data.already_initialized && !data.eligible) {
-      throw new Error(data.error || `API ${res.status}: ${res.statusText}`);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3e4);
+    try {
+      const res = await fetch(`${this.config.registryUrl}${path}`, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.config.apiKey}`
+        },
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      let data;
+      try {
+        data = await res.json();
+      } catch {
+        throw new NetworkError(`API error: ${res.status} non-JSON response from ${path}`);
+      }
+      if (!res.ok && !data.ok && !data.already_initialized && !data.eligible) {
+        throw mapApiError(res.status, data, path);
+      }
+      return data;
+    } catch (err) {
+      if (err.name === "AbortError") {
+        throw new NetworkError(`Request timeout: ${method} ${path}`, "TIMEOUT" /* TIMEOUT */);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timeout);
     }
-    return data;
   }
   log(msg) {
     if (this.config.verbose) {
@@ -371,6 +922,12 @@ var BeatAgent = class {
   }
 };
 function computeBeatsLite(startHash, startIndex, count, difficulty = 1e3, anchorHash) {
+  if (!startHash || typeof startHash !== "string") {
+    throw new ValidationError("computeBeatsLite: startHash must be a non-empty string");
+  }
+  if (!Number.isInteger(count) || count < 1) {
+    throw new ValidationError("computeBeatsLite: count must be a positive integer");
+  }
   const t0 = Date.now();
   let prev = startHash;
   let lastBeat = null;
@@ -381,9 +938,20 @@ function computeBeatsLite(startHash, startIndex, count, difficulty = 1e3, anchor
   return { lastBeat, elapsed: Date.now() - t0 };
 }
 export {
+  AuthError,
   BeatAgent,
+  ErrorCode,
+  FrozenError,
+  NetworkError,
+  NotFoundError,
+  ProvenonceError,
+  RateLimitError,
+  ServerError,
+  StateError,
+  ValidationError,
   computeBeat,
   computeBeatsLite,
+  generateWalletKeypair,
   register
 };
 //# sourceMappingURL=index.mjs.map