@svsprotocol/solana 0.1.0

package/dist/bot-auth.js

@@ -0,0 +1,50 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export const DEFAULT_BOT_REQUEST_TIMESTAMP_MAX_AGE_MS = 5 * 60 * 1000;
+export const BOT_REQUEST_SIGNATURE_VERSION = "v1";
+
+export function createBotRequestSignature({ body, timestamp, secret } = {}) {
+  if (!secret) {
+    throw new Error("secret is required.");
+  }
+
+  if (!timestamp) {
+    throw new Error("timestamp is required.");
+  }
+
+  const rawBody = body === undefined || body === null ? "" : String(body);
+  const digest = createHmac("sha256", secret)
+    .update(`${timestamp}.${rawBody}`)
+    .digest("hex");
+
+  return `${BOT_REQUEST_SIGNATURE_VERSION}=${digest}`;
+}
+
+export function verifyBotRequestSignature({
+  body,
+  timestamp,
+  signature,
+  secret,
+  now = new Date(),
+  maxAgeMs = DEFAULT_BOT_REQUEST_TIMESTAMP_MAX_AGE_MS
+} = {}) {
+  if (!signature || !timestamp || !secret) {
+    return false;
+  }
+
+  const requestTime = new Date(timestamp);
+  if (Number.isNaN(requestTime.getTime())) {
+    return false;
+  }
+
+  if (Math.abs(now.getTime() - requestTime.getTime()) > maxAgeMs) {
+    return false;
+  }
+
+  const expected = createBotRequestSignature({ body, timestamp, secret });
+  const expectedBuffer = Buffer.from(expected);
+  const actualBuffer = Buffer.from(signature);
+
+  return expectedBuffer.length === actualBuffer.length &&
+    timingSafeEqual(expectedBuffer, actualBuffer);
+}

package/dist/bot-certification-evidence.js

@@ -0,0 +1,342 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { hashObject } from "./receipt.js";
+
+export const BOT_CERTIFICATION_EVIDENCE_VERSION = "svs.bot-certification-evidence.v1";
+export const BOT_CERTIFICATION_EVIDENCE_VERIFICATION_VERSION = "svs.bot-certification-evidence-verification.v1";
+export const DEFAULT_BOT_CERTIFICATION_EVIDENCE_PATH = "./data/security/bot-certification-evidence.json";
+
+export function createBotCertificationEvidenceFromResult({
+  result,
+  generatedAt = new Date()
+} = {}) {
+  const certification = result?.certification ?? {};
+  const unsigned = {
+    version: BOT_CERTIFICATION_EVIDENCE_VERSION,
+    generatedAt: generatedAt.toISOString(),
+    source: {
+      resultVersion: result?.version ?? null,
+      serverUrl: result?.serverUrl ?? null
+    },
+    reportSafety: {
+      secretsIncluded: false,
+      redactedFields: [
+        "SVS_BOT_API_KEY",
+        "SVS_BOT_REQUEST_SIGNING_SECRET",
+        "requestSigningSecret",
+        "apiKey",
+        "webhookSecret",
+        "svs-request-signature"
+      ]
+    },
+    certificationCheck: {
+      ok: result?.ok === true,
+      status: result?.status ?? null,
+      checkedAt: result?.checkedAt ?? null,
+      botId: result?.botId ?? certification?.botId ?? null,
+      integrationContract: summarizeIntegrationContractBinding(result?.integrationContract ?? result?.contract),
+      nextAction: result?.nextAction ?? certification?.nextAction ?? null
+    },
+    certification: {
+      version: certification?.version ?? null,
+      ok: certification?.ok === true,
+      status: certification?.status ?? null,
+      botId: certification?.botId ?? result?.botId ?? null,
+      certificationHash: certification?.certification?.certificationHash ??
+        certification?.certificationHash ??
+        null,
+      recordId: certification?.certification?.recordId ??
+        certification?.recordId ??
+        null,
+      found: certification?.certification?.found === true ||
+        certification?.found === true,
+      botMatches: certification?.certification?.botMatches === true ||
+        certification?.botMatches === true,
+      quality: summarizeBotIntegrationQuality(certification?.quality ?? result?.quality ?? certification?.certification?.quality)
+    },
+    qualityTarget: summarizeBotIntegrationQualityTarget(certification?.qualityTarget ?? result?.qualityTarget),
+    proofs: {
+      verificationSetHash: certification?.proofs?.verificationSetHash ??
+        certification?.evidence?.verificationSetHash ??
+        null,
+      botIntegrationReportHash: certification?.proofs?.botIntegrationReportHash ??
+        certification?.evidence?.botIntegrationReportHash ??
+        null,
+      integrationContractHash: result?.integrationContract?.certifiedContractHash ??
+        certification?.proofs?.integrationContractHash ??
+        certification?.evidence?.integrationContractHash ??
+        null,
+      currentIntegrationContractHash: result?.integrationContract?.currentContractHash ??
+        certification?.proofs?.currentIntegrationContractHash ??
+        result?.proofs?.currentIntegrationContractHash ??
+        null,
+      integrationContractCurrent: result?.integrationContract
+        ? result.integrationContract.ok === true
+        : certification?.proofs?.integrationContractCurrent === true ||
+          result?.proofs?.integrationContractCurrent === true,
+      actionRecordVerificationOk: certification?.proofs?.actionRecordVerificationOk === true ||
+        certification?.evidence?.actionRecordVerificationOk === true,
+      receiptRegistrySubmissionVerificationOk: certification?.proofs?.receiptRegistrySubmissionVerificationOk === true ||
+        certification?.evidence?.receiptRegistrySubmissionVerificationOk === true,
+      portableSetVerified: certification?.proofs?.portableSetVerified === true ||
+        certification?.evidence?.portableSetVerified === true,
+      secretsIncluded: certification?.proofs?.secretsIncluded === true ||
+        certification?.evidence?.secretsIncluded === true
+    },
+    freshness: {
+      fresh: certification?.freshness?.fresh === true,
+      stale: certification?.freshness?.stale === true,
+      ageMs: Number.isFinite(certification?.freshness?.ageMs) ? certification.freshness.ageMs : null,
+      staleAfterMs: Number.isFinite(certification?.freshness?.staleAfterMs)
+        ? certification.freshness.staleAfterMs
+        : null
+    },
+    nextAction: result?.nextAction ?? certification?.nextAction ?? null
+  };
+
+  return {
+    ...unsigned,
+    evidenceHash: hashBotCertificationEvidence(unsigned)
+  };
+}
+
+export async function persistBotCertificationEvidence({
+  result,
+  outputPath = DEFAULT_BOT_CERTIFICATION_EVIDENCE_PATH,
+  generatedAt = new Date()
+} = {}) {
+  const evidence = createBotCertificationEvidenceFromResult({ result, generatedAt });
+  const text = `${JSON.stringify(evidence, null, 2)}\n`;
+
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, text);
+
+  return {
+    path: outputPath,
+    bytes: Buffer.byteLength(text, "utf8"),
+    evidence
+  };
+}
+
+export function verifyBotCertificationEvidence(evidence, {
+  requireOk = true,
+  staleAfterMs = null,
+  now = new Date()
+} = {}) {
+  const freshness = checkBotCertificationEvidenceFreshness({
+    generatedAt: evidence?.generatedAt,
+    staleAfterMs,
+    now
+  });
+  const recomputedHash = hashBotCertificationEvidence(evidence);
+  const checks = [
+    check(
+      "Bot certification evidence version is supported",
+      evidence?.version === BOT_CERTIFICATION_EVIDENCE_VERSION,
+      evidence?.version ?? "missing"
+    ),
+    check(
+      "Bot certification evidence hash is valid",
+      evidence?.evidenceHash === recomputedHash,
+      `declared=${evidence?.evidenceHash ?? "missing"} recomputed=${recomputedHash ?? "missing"}`
+    ),
+    check(
+      "Bot certification evidence excludes secrets",
+      evidence?.reportSafety?.secretsIncluded === false && evidence?.proofs?.secretsIncluded !== true,
+      `reportSafety=${evidence?.reportSafety?.secretsIncluded ?? "missing"} proofs=${evidence?.proofs?.secretsIncluded ?? "missing"}`
+    ),
+    check(
+      "Bot certification command passed",
+      !requireOk || evidence?.certificationCheck?.ok === true,
+      `status=${evidence?.certificationCheck?.status ?? "missing"}`
+    ),
+    check(
+      "Bot integration certification is ready",
+      !requireOk ||
+        evidence?.certification?.ok === true &&
+        ["ready", "certified"].includes(evidence?.certification?.status),
+      `status=${evidence?.certification?.status ?? "missing"}`
+    ),
+    check(
+      "Bot certification references a matching certified bot",
+      !requireOk || evidence?.certification?.found === true && evidence?.certification?.botMatches === true,
+      `found=${evidence?.certification?.found ?? "missing"} botMatches=${evidence?.certification?.botMatches ?? "missing"}`
+    ),
+    check(
+      "Bot certification action record proof passed",
+      !requireOk || evidence?.proofs?.actionRecordVerificationOk === true,
+      `ok=${evidence?.proofs?.actionRecordVerificationOk ?? "missing"}`
+    ),
+    check(
+      "Bot certification custom registry proof passed",
+      !requireOk || evidence?.proofs?.receiptRegistrySubmissionVerificationOk === true,
+      `ok=${evidence?.proofs?.receiptRegistrySubmissionVerificationOk ?? "missing"}`
+    ),
+    check(
+      "Bot certification portable set proof passed",
+      !requireOk || evidence?.proofs?.portableSetVerified === true,
+      `ok=${evidence?.proofs?.portableSetVerified ?? "missing"}`
+    ),
+    check(
+      "Bot certification integration contract binding passed",
+      !requireOk ||
+        !evidence?.certificationCheck?.integrationContract ||
+        evidence.certificationCheck.integrationContract.ok === true,
+      `status=${evidence?.certificationCheck?.integrationContract?.status ?? "missing"} local=${evidence?.certificationCheck?.integrationContract?.localContractHash ?? "missing"} certified=${evidence?.certificationCheck?.integrationContract?.certifiedContractHash ?? "missing"}`
+    ),
+    check(
+      "Bot certification quality target passed",
+      !requireOk || evidence?.qualityTarget?.ready === true &&
+        evidence.qualityTarget.score === evidence.qualityTarget.targetScore &&
+        evidence.qualityTarget.status === "excellent",
+      `ready=${evidence?.qualityTarget?.ready ?? "missing"} score=${evidence?.qualityTarget?.score ?? "missing"} target=${evidence?.qualityTarget?.targetScore ?? "missing"} status=${evidence?.qualityTarget?.status ?? "missing"}`
+    )
+  ];
+
+  if (staleAfterMs !== null && staleAfterMs !== undefined) {
+    checks.push(check(
+      "Bot certification evidence is fresh",
+      !freshness.stale,
+      freshness.ageMs === null
+        ? `generatedAt=${evidence?.generatedAt ?? "missing"}`
+        : `ageMs=${freshness.ageMs} staleAfterMs=${staleAfterMs}`
+    ));
+  }
+
+  const failedChecks = checks.filter((item) => !item.ok);
+
+  return {
+    version: BOT_CERTIFICATION_EVIDENCE_VERIFICATION_VERSION,
+    ok: failedChecks.length === 0,
+    status: failedChecks.length === 0 ? "verified" : freshness.stale ? "stale" : "failed",
+    checkedAt: now.toISOString(),
+    found: Boolean(evidence),
+    generatedAt: evidence?.generatedAt ?? null,
+    stale: freshness.stale,
+    ageMs: freshness.ageMs,
+    staleAfterMs,
+    evidenceHash: evidence?.evidenceHash ?? null,
+    computedEvidenceHash: recomputedHash,
+    botId: evidence?.certificationCheck?.botId ?? evidence?.certification?.botId ?? null,
+    certificationHash: evidence?.certification?.certificationHash ?? null,
+    recordId: evidence?.certification?.recordId ?? null,
+    qualityTarget: evidence?.qualityTarget ?? null,
+    failedCheckCount: failedChecks.length,
+    failedChecks,
+    checks
+  };
+}
+
+function summarizeBotIntegrationQuality(quality) {
+  if (!quality || typeof quality !== "object") {
+    return null;
+  }
+
+  return {
+    version: quality.version ?? null,
+    score: Number.isInteger(quality.score) ? quality.score : null,
+    maxScore: Number.isInteger(quality.maxScore) ? quality.maxScore : null,
+    status: quality.status ?? null,
+    passedFactorCount: Number.isInteger(quality.passedFactorCount) ? quality.passedFactorCount : null,
+    failedFactorCount: Number.isInteger(quality.failedFactorCount) ? quality.failedFactorCount : null,
+    missingFactorCodes: Array.isArray(quality.factors)
+      ? quality.factors.filter((factor) => factor.ok !== true).map((factor) => factor.code ?? "unknown")
+      : [],
+    nextAction: quality.nextAction
+      ? {
+          code: quality.nextAction.code ?? null,
+          message: quality.nextAction.message ?? null
+        }
+      : null
+  };
+}
+
+function summarizeBotIntegrationQualityTarget(target) {
+  if (!target || typeof target !== "object") {
+    return null;
+  }
+
+  return {
+    version: target.version ?? null,
+    ready: target.ready === true,
+    score: Number.isInteger(target.score) ? target.score : null,
+    maxScore: Number.isInteger(target.maxScore) ? target.maxScore : null,
+    targetScore: Number.isInteger(target.targetScore) ? target.targetScore : null,
+    status: target.status ?? null,
+    missingFactorCount: Number.isInteger(target.missingFactorCount) ? target.missingFactorCount : null,
+    missingFactorCodes: Array.isArray(target.missingFactorCodes) ? target.missingFactorCodes : [],
+    nextAction: target.nextAction
+      ? {
+          code: target.nextAction.code ?? null,
+          message: target.nextAction.message ?? null
+        }
+      : null
+  };
+}
+
+function summarizeIntegrationContractBinding(binding) {
+  if (!binding || typeof binding !== "object") {
+    return null;
+  }
+
+  return {
+    version: binding.version ?? null,
+    required: binding.required === true,
+    ok: binding.ok === true || binding.status === "current",
+    status: binding.status ?? null,
+    localContractHash: binding.localContractHash ?? binding.currentHash ?? null,
+    dashboardContractHash: binding.dashboardContractHash ?? binding.currentHash ?? null,
+    certifiedContractHash: binding.certifiedContractHash ?? binding.certifiedHash ?? null,
+    currentContractHash: binding.currentContractHash ?? binding.currentHash ?? null,
+    drifted: binding.drifted === true,
+    contractVersion: binding.contractVersion ?? null
+  };
+}
+
+export function hashBotCertificationEvidence(evidence) {
+  if (!evidence || typeof evidence !== "object") {
+    return null;
+  }
+
+  const { evidenceHash: _evidenceHash, ...unsigned } = evidence;
+
+  return hashObject(unsigned);
+}
+
+export function checkBotCertificationEvidenceFreshness({
+  generatedAt,
+  staleAfterMs,
+  now = new Date()
+} = {}) {
+  if (staleAfterMs === null || staleAfterMs === undefined) {
+    return {
+      stale: false,
+      ageMs: null
+    };
+  }
+
+  const generatedTime = Date.parse(generatedAt);
+  const nowTime = now instanceof Date ? now.getTime() : Date.parse(now);
+
+  if (!Number.isFinite(generatedTime) || !Number.isFinite(nowTime)) {
+    return {
+      stale: true,
+      ageMs: null
+    };
+  }
+
+  const ageMs = Math.max(0, nowTime - generatedTime);
+
+  return {
+    stale: ageMs > staleAfterMs,
+    ageMs
+  };
+}
+
+function check(name, ok, detail) {
+  return {
+    name,
+    ok: Boolean(ok),
+    detail
+  };
+}

package/dist/bot-first-action-runbook.js

@@ -0,0 +1,299 @@
+import { createHash } from "node:crypto";
+import {
+  BOT_INTEGRATION_CONTRACT_VERSION,
+  BOT_INTEGRATION_QUICKSTART_VERSION,
+  hashBotIntegrationContract
+} from "./bot-integration-contract.js";
+
+export const BOT_FIRST_ACTION_RUNBOOK_VERSION = "svs.bot-first-action-runbook.v1";
+export const BOT_FIRST_ACTION_STEP_VERSION = "svs.bot-first-action-runbook-step.v1";
+
+const DEFAULT_ENV_PATH = "./examples/external-bots/signed-devnet-memo-bot.local.env";
+
+export function createBotFirstActionRunbook(contract, {
+  serverUrl = null,
+  envPath = null,
+  generatedAt = new Date().toISOString()
+} = {}) {
+  const quickstart = validateQuickstart(contract);
+  const contractHash = hashBotIntegrationContract(contract);
+  const commands = quickstart.commands ?? {};
+  const resolvedEnvPath = envPath ?? quickstart.envFile?.localPath ?? DEFAULT_ENV_PATH;
+  const resolvedServerUrl = normalizeBaseUrl(
+    serverUrl ?? quickstart.envFile?.defaults?.SVS_SERVER_URL ?? "http://127.0.0.1:4173"
+  );
+  const commandSet = createCommandSet({
+    commands,
+    resolvedServerUrl,
+    resolvedEnvPath,
+    quickstartEnvPath: quickstart.envFile?.localPath ?? null,
+    quickstartServerUrl: quickstart.envFile?.defaults?.SVS_SERVER_URL ?? null
+  });
+  const runbook = {
+    version: BOT_FIRST_ACTION_RUNBOOK_VERSION,
+    generatedAt,
+    objective: "Move a new bot from local env setup to one human-approved, production-verifiable SVS action with the fewest manual handoffs.",
+    audience: [
+      "bot-builders",
+      "operators"
+    ],
+    serverUrl: resolvedServerUrl,
+    envPath: resolvedEnvPath,
+    contract: {
+      version: contract.version,
+      quickstartVersion: quickstart.version,
+      hashAlgorithm: "sha256",
+      hash: contractHash,
+      source: quickstart.endpoints?.integrationContract ?? `${resolvedServerUrl}/api/bots/integration-contract`
+    },
+    noSecretGuarantees: [
+      "Does not include API keys.",
+      "Does not include request-signing secrets.",
+      "Does not include wallet private keys.",
+      "Only points to env fields and commands that the operator or bot runtime already controls."
+    ],
+    commandSet,
+    orderedSteps: createOrderedSteps(commandSet),
+    fallbackPath: {
+      when: "The proof-wait submit exits before the operator finishes approval, broadcast, custom-registry registration, and proof export.",
+      commands: [
+        commandSet.certifiedSubmitStatus,
+        commandSet.certifiedSubmitPromote
+      ].filter(Boolean),
+      operatorAction: "Approve, broadcast, verify action, register the custom receipt, then promote the certified-submit evidence."
+    },
+    successDefinition: {
+      botSide: "The proof-wait submit returns or later promotes a production-verified action with a fetched proof response.",
+      operatorSide: "Dashboard action lifecycle shows approved, broadcast, verified, custom registry registered, and exportable proof.",
+      auditorSide: "The resulting verification set includes action-production proof evidence and custom receipt-registry evidence."
+    },
+    nextAction: {
+      code: "run_first_action_path",
+      message: "Run the ordered steps; if the proof wait expires, use the fallback status/promote commands after the operator completes the dashboard path."
+    }
+  };
+
+  return {
+    ...runbook,
+    runbookHashAlgorithm: "sha256",
+    runbookHash: hashRunbook(runbook)
+  };
+}
+
+export function renderBotFirstActionRunbookText(runbook) {
+  const lines = [
+    "SVS first verified action runbook",
+    `Server: ${runbook.serverUrl}`,
+    `Env: ${runbook.envPath}`,
+    `Contract: ${runbook.contract.hash}`,
+    "",
+    "Ordered path:"
+  ];
+
+  for (const step of runbook.orderedSteps ?? []) {
+    lines.push(`${step.order}. [${step.actor}] ${step.title}`);
+    if (step.command) {
+      lines.push(`   ${step.command}`);
+    }
+    if (step.dashboardAction) {
+      lines.push(`   Dashboard: ${step.dashboardAction}`);
+    }
+    lines.push(`   Success: ${step.successSignal}`);
+  }
+
+  if (runbook.fallbackPath?.commands?.length) {
+    lines.push("");
+    lines.push("If proof wait expires:");
+    for (const command of runbook.fallbackPath.commands) {
+      lines.push(`   ${command}`);
+    }
+    lines.push(`   Dashboard: ${runbook.fallbackPath.operatorAction}`);
+  }
+
+  lines.push("");
+  lines.push(`Runbook hash: ${runbook.runbookHash}`);
+  return `${lines.join("\n")}\n`;
+}
+
+function validateQuickstart(contract) {
+  if (contract?.version !== BOT_INTEGRATION_CONTRACT_VERSION) {
+    throw new Error(`Unsupported bot integration contract version: ${contract?.version ?? "missing"}.`);
+  }
+
+  if (contract?.quickstart?.version !== BOT_INTEGRATION_QUICKSTART_VERSION) {
+    throw new Error(`Unsupported bot quickstart version: ${contract?.quickstart?.version ?? "missing"}.`);
+  }
+
+  return contract.quickstart;
+}
+
+function createCommandSet({
+  commands,
+  resolvedServerUrl,
+  resolvedEnvPath,
+  quickstartEnvPath,
+  quickstartServerUrl
+}) {
+  const envFlag = `--env ${resolvedEnvPath}`;
+  const normalizeCommand = (command) => rewriteCommand(command, {
+    resolvedEnvPath,
+    resolvedServerUrl,
+    quickstartEnvPath,
+    quickstartServerUrl
+  });
+
+  return {
+    quickstart: normalizeCommand(commands.quickstart) ?? `npm run bot:quickstart -- --server ${resolvedServerUrl} --write-env ${resolvedEnvPath}`,
+    preflight: normalizeCommand(commands.preflight) ?? `npm run bot:preflight -- ${envFlag}`,
+    doctor: normalizeCommand(commands.doctor) ?? `npm run bot:doctor -- ${envFlag}`,
+    report: normalizeCommand(commands.report) ?? `npm run bot:report -- ${envFlag}`,
+    certification: normalizeCommand(commands.certification) ?? `npm run bot:certification -- ${envFlag} --write-evidence`,
+    certifiedSubmitReadiness: normalizeCommand(commands.certifiedSubmitReadiness) ?? `npm run bot:certified-submit:readiness -- ${envFlag} --write-receipt`,
+    certifiedSubmitAndWaitForProof: normalizeCommand(commands.certifiedSubmitAndWaitForProof) ??
+      `npm run bot:certified-submit -- ${envFlag} --wait-production-proof true --production-proof-wait-attempts 24 --production-proof-wait-interval-ms 10000 --production-proof-check-receipt-registry-chain true`,
+    certifiedSubmitStatus: normalizeCommand(commands.certifiedSubmitStatus) ?? "npm run bot:certified-submit:status",
+    certifiedSubmitPromote: normalizeCommand(commands.certifiedSubmitPromote) ?? "npm run bot:certified-submit:promote"
+  };
+}
+
+function rewriteCommand(command, {
+  resolvedEnvPath,
+  resolvedServerUrl,
+  quickstartEnvPath,
+  quickstartServerUrl
+}) {
+  if (!command) {
+    return null;
+  }
+
+  let text = String(command);
+
+  for (const path of new Set([quickstartEnvPath, DEFAULT_ENV_PATH])) {
+    if (path && path !== resolvedEnvPath) {
+      text = text.split(path).join(resolvedEnvPath);
+    }
+  }
+
+  if (quickstartServerUrl && quickstartServerUrl !== resolvedServerUrl) {
+    text = text.split(quickstartServerUrl).join(resolvedServerUrl);
+  }
+
+  return text;
+}
+
+function createOrderedSteps(commandSet) {
+  return [
+    {
+      version: BOT_FIRST_ACTION_STEP_VERSION,
+      order: 1,
+      actor: "operator",
+      title: "Generate the bot env handoff",
+      command: commandSet.quickstart,
+      successSignal: "A local env file exists with placeholders, current server URL, and pinned integration-contract hash."
+    },
+    {
+      version: BOT_FIRST_ACTION_STEP_VERSION,
+      order: 2,
+      actor: "operator",
+      title: "Fill credentials from the dashboard Bot onboarding panel",
+      dashboardAction: "Copy bot id, API key, request-signing secret, controller wallet, and policy into the env file.",
+      successSignal: "The bot runtime has the env values; no secret material is stored in this runbook."
+    },
+    {
+      version: BOT_FIRST_ACTION_STEP_VERSION,
+      order: 3,
+      actor: "bot",
+      title: "Run safe preflight",
+      command: commandSet.preflight,
+      successSignal: "Preflight exits 0 and reports the next action without queueing a transaction."
+    },
+    {
+      version: BOT_FIRST_ACTION_STEP_VERSION,
+      order: 4,
+      actor: "bot",
+      title: "Run doctor for compatibility and credential readiness",
+      command: commandSet.doctor,
+      successSignal: "Doctor exits 0 with the current quickstart version and no missing client capabilities."
+    },
+    {
+      version: BOT_FIRST_ACTION_STEP_VERSION,
+      order: 5,
+      actor: "bot",
+      title: "Generate a shareable integration report",
+      command: commandSet.report,
+      successSignal: "The report is non-secret and gives the operator one adoption score plus next action."
+    },
+    {
+      version: BOT_FIRST_ACTION_STEP_VERSION,
+      order: 6,
+      actor: "operator",
+      title: "Certify the bot integration path",
+      command: commandSet.certification,
+      successSignal: "Certification evidence is current, contract-bound, and qualityTarget is ready before production submit."
+    },
+    {
+      version: BOT_FIRST_ACTION_STEP_VERSION,
+      order: 7,
+      actor: "bot",
+      title: "Write the certified-submit readiness receipt",
+      command: commandSet.certifiedSubmitReadiness,
+      successSignal: "A no-secret readiness receipt proves the bot can submit through the certified path."
+    },
+    {
+      version: BOT_FIRST_ACTION_STEP_VERSION,
+      order: 8,
+      actor: "bot",
+      title: "Submit the first action and wait for production proof",
+      command: commandSet.certifiedSubmitAndWaitForProof,
+      successSignal: "The helper submits with HMAC request signing, polls signed proof reads, and fetches the action production proof when the operator path completes."
+    },
+    {
+      version: BOT_FIRST_ACTION_STEP_VERSION,
+      order: 9,
+      actor: "operator",
+      title: "Approve, broadcast, verify, and register the action",
+      dashboardAction: "Use the dashboard action queue to approve with wallet, broadcast, verify action, register the custom receipt, and export proof.",
+      successSignal: "The selected action has a custom registry PDA proof and exportable verification set."
+    }
+  ];
+}
+
+function hashRunbook(runbook) {
+  return createHash("sha256")
+    .update(stableStringify(normalizeRunbookForHash(runbook)))
+    .digest("hex");
+}
+
+function normalizeRunbookForHash(value) {
+  if (Array.isArray(value)) {
+    return value.map(normalizeRunbookForHash);
+  }
+
+  if (value && typeof value === "object") {
+    return Object.keys(value)
+      .filter((key) => !["generatedAt", "runbookHash", "runbookHashAlgorithm"].includes(key))
+      .sort()
+      .reduce((result, key) => {
+        result[key] = normalizeRunbookForHash(value[key]);
+        return result;
+      }, {});
+  }
+
+  return value;
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+  }
+
+  return JSON.stringify(value);
+}
+
+function normalizeBaseUrl(value) {
+  return String(value || "http://127.0.0.1:4173").replace(/\/+$/, "");
+}