@sleep2agi/commhub-server 0.9.0-preview.2 → 0.9.0-preview.21

package/src/create-node.ts

@@ -0,0 +1,346 @@
+// RFC-026 v4 hub-side runtime — pendingEnvBlobs Map (F1 mint-stream-
+// evict) + sweeper (C4 orphan ntok revoke) + content-match finalize
+// helper (called from report_status when a child first registers).
+//
+// The actual MCP tools (create_node / get_create_request /
+// ack_create_request) are registered in tools.ts and call into this
+// module. Keeping the heavy state + sweeper here makes the tool layer
+// thin + this module independently testable.
+
+import { db, uuidv4 } from "./db.js";
+
+// ── §4.4 F1 — pendingEnvBlobs Map ─────────────────────────────────
+// In-memory ONLY. Never touches disk / never enters the SQL store.
+// Daemon `get_create_request(request_id)` consumes + evicts. Untaken
+// blobs are GC'd at TTL expiry.
+
+export interface PendingEnvBlob {
+  request_id: string;
+  daemon_node_id: string;          // hub uses this for C2 cross-daemon check
+  env_blob: Record<string, string>; // KEY → secret value (plaintext, never logged)
+  child_token: string;              // freshly minted ntok_ for the child
+  child_token_id: string;           // tokens.token_id for sweeper revoke
+  expires_at: number;               // ms epoch
+}
+
+const TTL_MS = 60_000;                      // 60s per RFC-026 v4 §4.4
+const SWEEPER_INTERVAL_MS = 30_000;         // 30s per RFC-026 v4 §4.4.8
+const REAPER_TTL_MS = 60_000;               // 60s timeout for pending/delivered rows
+
+const pendingEnvBlobs = new Map<string, PendingEnvBlob>();
+let gcTimer: ReturnType<typeof setInterval> | null = null;
+let sweeperTimer: ReturnType<typeof setInterval> | null = null;
+
+export function putPendingEnvBlob(b: Omit<PendingEnvBlob, "expires_at">): void {
+  pendingEnvBlobs.set(b.request_id, { ...b, expires_at: Date.now() + TTL_MS });
+}
+
+/** Get the pending env_blob for daemon. Returns null if not found OR
+ *  if caller's daemon_node_id doesn't match (C2 cross-daemon guard).
+ *  Atomically deletes the entry from the Map (one-shot consume). */
+export function takePendingEnvBlob(
+  request_id: string,
+  callerDaemonNodeId: string,
+): PendingEnvBlob | null {
+  const b = pendingEnvBlobs.get(request_id);
+  if (!b) return null;
+  if (b.daemon_node_id !== callerDaemonNodeId) return null;
+  if (Date.now() > b.expires_at) {
+    pendingEnvBlobs.delete(request_id);
+    return null;
+  }
+  pendingEnvBlobs.delete(request_id);  // §4.4 evict immediately
+  return b;
+}
+
+/** Test/diagnostic helper — does NOT consume. */
+export function peekPendingEnvBlob(request_id: string): PendingEnvBlob | null {
+  return pendingEnvBlobs.get(request_id) || null;
+}
+
+export function evictExpired(now = Date.now()): number {
+  let evicted = 0;
+  for (const [k, v] of pendingEnvBlobs) {
+    if (now > v.expires_at) {
+      pendingEnvBlobs.delete(k);
+      evicted++;
+    }
+  }
+  return evicted;
+}
+
+export function startPendingEnvGcTimer(): void {
+  if (gcTimer) return;
+  gcTimer = setInterval(() => {
+    const n = evictExpired();
+    if (n > 0) console.log(`[create-node] GC: evicted ${n} expired env_blob(s)`);
+  }, 5_000);
+  (gcTimer as any).unref?.();
+}
+
+// ── §4.4.8 C4 — orphan ntok revoke sweeper ────────────────────────
+// Scans `node_create_requests` for non-terminal rows older than
+// REAPER_TTL_MS. Atomically marks request as failed/expired AND
+// revokes the matching api_tokens.row (via request_id link) so the
+// orphan child-ntok cannot be used by anyone who scraped it.
+
+export function runOrphanSweepOnce(now = Date.now()): { swept: number; revoked: number } {
+  const cutoffAge = REAPER_TTL_MS;
+  const cutoffMs = now - cutoffAge;
+  // Two cohorts (per RFC §4.4.8 case table):
+  //  F-1 status='pending'   age > TTL → hub crashed before daemon get
+  //  F-2 status='delivered' age > TTL → daemon got blob but never ack'd
+  const stale = db.all<{ request_id: string; status: string; child_token_id: string | null }>(
+    `SELECT request_id, status, child_token_id
+       FROM node_create_requests
+      WHERE status IN ('pending', 'delivered')
+        AND created_at < ?1`,
+    cutoffMs,
+  );
+  if (stale.length === 0) return { swept: 0, revoked: 0 };
+
+  let swept = 0; let revoked = 0;
+  // SQLite Bun driver doesn't expose BEGIN/COMMIT cleanly across the
+  // wrapper here; fold per-row into a transaction.
+  try {
+    db.exec("BEGIN");
+    for (const row of stale) {
+      // Revoke the child-ntok first (sweeper is server-side ground
+      // truth per §4.4.8). If child_token_id null somehow, skip
+      // revoke (request never made it that far) but still mark
+      // failed.
+      if (row.child_token_id) {
+        // db.run returns the SQLite adapter's RunResult (changes counter
+        // if driver-supported). Only count a revoke when the UPDATE
+        // actually touched a row — under the bun:sqlite adapter the
+        // changes prop is reliable; on adapters returning undefined we
+        // fall back to a post-UPDATE SELECT to confirm revoked_at IS
+        // NOT NULL (DB is ground truth). Avoids over-counting when
+        // child_token_id is stale or already revoked. (通信龙 nit 2)
+        const r = db.run(
+          `UPDATE api_tokens SET revoked_at = datetime('now') WHERE token_id = ?1 AND revoked_at IS NULL`,
+          [row.child_token_id],
+        );
+        const changes = (r as any)?.changes;
+        if (typeof changes === "number") {
+          if (changes > 0) revoked++;
+        } else {
+          // Adapter didn't report; verify via SELECT
+          const after = db.get<{ revoked_at: string | null }>(
+            `SELECT revoked_at FROM api_tokens WHERE token_id = ?1`, row.child_token_id,
+          );
+          if (after?.revoked_at) revoked++;
+        }
+      }
+      const newStatus = row.status === "pending" ? "failed" : "expired";
+      const err = row.status === "pending" ? "sweeper_revoked_before_delivery" : "sweeper_revoked_after_delivery_no_ack";
+      db.run(
+        `UPDATE node_create_requests SET status = ?1, error = ?2, acked_at = ?3 WHERE request_id = ?4 AND status IN ('pending', 'delivered')`,
+        [newStatus, err, now, row.request_id],
+      );
+      // Also drop any lingering env_blob (defense; should already be
+      // gone for delivered, but pending could leak if GC hasn't run).
+      pendingEnvBlobs.delete(row.request_id);
+      swept++;
+    }
+    db.exec("COMMIT");
+  } catch (e: any) {
+    try { db.exec("ROLLBACK"); } catch { /* swallow */ }
+    console.warn(`[create-node] sweeper transaction failed: ${e?.message || e}`);
+    return { swept: 0, revoked: 0 };
+  }
+  if (swept > 0) {
+    console.log(`[commhub] ✓ create-node sweeper: swept ${swept} stale request(s), revoked ${revoked} child-ntok(s)`);
+    auditCreateNode({
+      action: "create_node_sweeper_revoked",
+      detail: { swept, revoked, sweeper_run_at_ms: now },
+    });
+  }
+  return { swept, revoked };
+}
+
+export function startSweeperTimer(): void {
+  if (sweeperTimer) return;
+  // Boot-time sweep: catch any rows left over from a prior process
+  // crash (case F-1: hub crashed after mint, before daemon get).
+  try { runOrphanSweepOnce(); } catch (e: any) {
+    console.warn(`[create-node] boot sweeper failed: ${e?.message || e}`);
+  }
+  sweeperTimer = setInterval(() => {
+    try { runOrphanSweepOnce(); }
+    catch (e: any) { console.warn(`[create-node] periodic sweeper failed: ${e?.message || e}`); }
+  }, SWEEPER_INTERVAL_MS);
+  (sweeperTimer as any).unref?.();
+}
+
+export function stopBackgroundTimersForTest(): void {
+  if (gcTimer) { clearInterval(gcTimer); gcTimer = null; }
+  if (sweeperTimer) { clearInterval(sweeperTimer); sweeperTimer = null; }
+  pendingEnvBlobs.clear();
+}
+
+// ── content-match finalize on child first register ────────────────
+// Called from tools.ts report_status handler when a node registers (or
+// re-registers). If there's a pending node_create_requests row whose
+// `child_name` matches the incoming alias AND the daemon_node_id is
+// in caller's network, mark it succeeded and stamp the real
+// child_node_id. Mirrors RFC-024 finalizePendingMatchingUpdates.
+
+export function finalizeCreateOnFirstRegister(
+  incoming: { node_id: string; alias: string; network_id: string | null },
+): { finalized: number; matchedIds: string[] } {
+  if (!incoming.node_id || !incoming.alias) return { finalized: 0, matchedIds: [] };
+  const net = incoming.network_id ?? "default";
+  const pending = db.all<{ request_id: string; daemon_node_id: string }>(
+    `SELECT request_id, daemon_node_id FROM node_create_requests
+      WHERE child_name = ?1 AND network_id = ?2 AND status IN ('delivered', 'pending')
+      ORDER BY created_at ASC`,
+    incoming.alias, net,
+  );
+  if (pending.length === 0) return { finalized: 0, matchedIds: [] };
+
+  const matchedIds: string[] = [];
+  for (const row of pending) {
+    const r = db.run(
+      `UPDATE node_create_requests
+          SET status = 'succeeded', child_node_id = ?1, acked_at = ?2
+        WHERE request_id = ?3 AND status IN ('delivered', 'pending')`,
+      [incoming.node_id, Date.now(), row.request_id],
+    );
+    matchedIds.push(row.request_id);
+    console.log(`[commhub] ✓ create-node finalize: request=${row.request_id} child=${incoming.alias} (${incoming.node_id}) daemon=${row.daemon_node_id}`);
+    auditCreateNode({
+      action: "create_node_succeeded",
+      network_id: net,
+      target_id: row.request_id,
+      detail: { child_node_id: incoming.node_id, child_alias: incoming.alias, daemon_node_id: row.daemon_node_id },
+    });
+  }
+  return { finalized: matchedIds.length, matchedIds };
+}
+
+export function newRequestId(): string {
+  return `cr_${uuidv4()}`;
+}
+
+// §4.1.4 C2 — resolve the caller daemon's node row by **token-bound
+// identity** (PR #299 BLOCKER #1). Module-level so unit tests can
+// import + call directly (per 通信龙 nit 1 — don't inline-mirror SQL
+// in tests; that's exactly the helper-drift anti-pattern the tools.ts
+// comment warns against).
+export type DaemonResolveResult =
+  | { ok: true; daemonNodeId: string; daemonAlias: string; networkId: string }
+  | { ok: false; error: string };
+
+export function resolveCallerDaemonTokenBound(opts: {
+  callerTokenIsNetwork: boolean;
+  callerTokenId: string | null | undefined;
+  enforceNetworkId: string | null | undefined;
+}): DaemonResolveResult {
+  if (!opts.callerTokenIsNetwork || !opts.callerTokenId) {
+    return { ok: false, error: "caller_not_a_daemon" };
+  }
+  if (!opts.enforceNetworkId) {
+    return { ok: false, error: "caller_not_a_daemon" };
+  }
+  const tokRow = db.get<{ name: string; network_id: string | null }>(
+    `SELECT name, network_id FROM api_tokens WHERE token_id = ?1 AND revoked_at IS NULL`,
+    opts.callerTokenId,
+  );
+  if (!tokRow || !tokRow.name || !tokRow.name.startsWith("node:")) {
+    return { ok: false, error: "caller_not_a_daemon" };
+  }
+  if (tokRow.network_id !== opts.enforceNetworkId) {
+    return { ok: false, error: "caller_not_a_daemon" };
+  }
+  const tokenAlias = tokRow.name.slice(5);
+  const nodeRow = db.get<{ node_id: string; alias: string; network_id: string }>(
+    `SELECT node_id, alias, network_id FROM nodes WHERE alias = ?1 AND network_id = ?2 LIMIT 1`,
+    tokenAlias, tokRow.network_id,
+  );
+  if (!nodeRow) {
+    return { ok: false, error: "caller_not_a_daemon" };
+  }
+  return {
+    ok: true,
+    daemonNodeId: nodeRow.node_id,
+    daemonAlias: nodeRow.alias,
+    networkId: nodeRow.network_id,
+  };
+}
+
+// RFC-026 §4.5 — append a row to audit_log for every create_node
+// lifecycle event. Best-effort: never throw out (calling tool should
+// continue even if audit insert fails for any reason).
+/** RFC-027 §4.5 D8 — tx-aware variant. Identical SQL to auditCreateNode
+ *  but RE-THROWS on failure so a BEGIN..COMMIT around lifecycle UPDATE +
+ *  audit INSERT can ROLLBACK if the audit row would have been lost.
+ *  Required for the "no audit-but state changed" window that §4.5 / D8
+ *  explicitly closes (PR1 SF-2 review catch — auditCreateNode's
+ *  swallow-and-warn defeats atomicity).
+ *
+ *  Callers in a non-transaction context should keep using auditCreateNode
+ *  (best-effort, never throws). */
+export function auditCreateNodeStrict(input: {
+  action: Parameters<typeof auditCreateNode>[0]["action"];
+  user_id?: string | null;
+  username?: string | null;
+  network_id?: string | null;
+  target_id?: string | null;
+  detail: Record<string, unknown>;
+}): void {
+  db.run(
+    `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, network_id)
+     VALUES (?1, ?2, ?3, 'node_create_request', ?4, ?5, ?6)`,
+    [
+      input.user_id || null,
+      input.username || null,
+      input.action,
+      input.target_id || null,
+      JSON.stringify(input.detail),
+      input.network_id || null,
+    ],
+  );
+}
+
+export function auditCreateNode(input: {
+  action:
+    | "create_node_dispatched"
+    | "create_node_rejected"
+    | "create_node_succeeded"
+    | "create_node_sweeper_revoked"
+    | "daemon_capability_lied"                  // RFC-026 §9.3 D2 — daemon declared runtime support, child died before serving
+    // RFC-027 §4.5 — stop/delete lifecycle audit action enum extension.
+    // Re-using auditCreateNode is fine: the action column carries the
+    // discriminator; target_type stays 'node_create_request' which is a
+    // misnomer for stop/delete rows but updating the schema would force a
+    // wider migration (see P1.1 issue).
+    | "stop_node_dispatched"
+    | "stop_node_completed"
+    | "delete_node_dispatched"
+    | "delete_node_completed"
+    | "forced_stop_with_in_flight"
+    | "backup_purged";
+  user_id?: string | null;
+  username?: string | null;
+  network_id?: string | null;
+  target_id?: string | null;   // request_id
+  detail: Record<string, unknown>;
+}): void {
+  try {
+    db.run(
+      `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, network_id)
+       VALUES (?1, ?2, ?3, 'node_create_request', ?4, ?5, ?6)`,
+      [
+        input.user_id || null,
+        input.username || null,
+        input.action,
+        input.target_id || null,
+        JSON.stringify(input.detail),
+        input.network_id || null,
+      ],
+    );
+  } catch (e: any) {
+    console.warn(`[commhub] audit_log insert (create_node) failed: ${e?.message || e}`);
+  }
+}

package/src/db.ts

@@ -301,6 +301,72 @@ try {
   if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
 }
 
+// RFC-026 §9 / #338 PR2 — daemon self-declare fields promoted from
+// config_snapshot to first-class indexable columns. The hub
+// `list_host_supervisors` MCP tool reads these directly without parsing
+// the snapshot JSON on every list call.
+//
+// Both fields are JSON arrays of strings:
+//   runtimes_supported    e.g. ["claude-agent-sdk","codex-sdk","grok-build-acp"]
+//   allowed_secret_keys   e.g. ["ANTHROPIC_API_KEY","OPENAI_API_KEY"]
+//
+// Stored as TEXT (JSON-encoded) — SQLite has no native array type and
+// the wrapper code is small. Both nullable for pre-PR2 daemons; the
+// list endpoint falls back to [] when null.
+try {
+  db.exec(`ALTER TABLE nodes ADD COLUMN runtimes_supported TEXT`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+try {
+  db.exec(`ALTER TABLE nodes ADD COLUMN allowed_secret_keys TEXT`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+
+// RFC-027 §2.3 — state machine for stop/delete (D5). 'active' default
+// matches pre-RFC behavior for every existing row. Transitions:
+//   active → stopping → stopped → (back to active via restart_node)
+//   active → deleting → (row gone)
+//   stopped → deleting → (row gone)
+// Used as the inbox-enqueue gate per §2.3 race-free invariant:
+// pushEvent / INSERT INTO inbox must refuse a non-active target so the
+// SIGTERM-in-flight window never gets a new task.
+try {
+  db.exec(`ALTER TABLE nodes ADD COLUMN lifecycle_state TEXT DEFAULT 'active'`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+
+// RFC-027 §2 — stop/delete request envelope. Mirrors
+// node_create_requests structure so the daemon-side pull/ack pattern
+// is symmetric with create_node. action='stop'|'delete' picks which
+// branch (delete adds backup_path + revokes ntok on ack).
+db.exec(`
+  CREATE TABLE IF NOT EXISTS node_stop_requests (
+    request_id TEXT PRIMARY KEY,
+    network_id TEXT NOT NULL,
+    daemon_node_id TEXT NOT NULL,
+    child_node_id TEXT NOT NULL,
+    child_alias TEXT NOT NULL,
+    action TEXT NOT NULL CHECK (action IN ('stop', 'delete')),
+    delete_config INTEGER NOT NULL DEFAULT 1,
+    grace_seconds INTEGER NOT NULL DEFAULT 10,
+    force INTEGER NOT NULL DEFAULT 0,
+    in_flight_at_dispatch INTEGER NOT NULL DEFAULT 0,
+    created_by_token TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    error TEXT,
+    backup_path TEXT,
+    exit_signal TEXT,
+    created_at INTEGER NOT NULL,
+    delivered_at INTEGER,
+    acked_at INTEGER
+  )
+`);
+db.exec(`CREATE INDEX IF NOT EXISTS idx_stop_req_daemon ON node_stop_requests(daemon_node_id, status)`);
+db.exec(`CREATE INDEX IF NOT EXISTS idx_stop_req_child ON node_stop_requests(child_node_id)`);
+
 // `node_config_updates` — pending + history. One row per dashboard write.
 // At most one row per node may be in a non-terminal state at a time
 // (single-flight enforced at the tool layer; this table just stores).
@@ -376,6 +442,136 @@ db.exec(`
   CREATE INDEX IF NOT EXISTS idx_tokens_user ON api_tokens(user_id);
 `);
 
+// RFC-026 v4 §4.4.8 C4 — api_tokens metadata so sweeper can revoke
+// orphan child-ntoks without ever touching plaintext tokens. ALTER in
+// try/catch (idempotent for already-migrated DBs).
+//   request_id  — links a child token to the create_node request that
+//                 minted it; sweeper joins on this
+//   revoked_at  — explicit revoke; resolveToken treats non-NULL as
+//                 invalid even before expiry
+for (const ddl of [
+  "ALTER TABLE api_tokens ADD COLUMN request_id TEXT",
+  "ALTER TABLE api_tokens ADD COLUMN revoked_at TEXT",
+  "ALTER TABLE api_tokens ADD COLUMN role TEXT",
+]) {
+  try { db.exec(ddl); }
+  catch (e: any) {
+    if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+  }
+}
+try { db.exec(`CREATE INDEX IF NOT EXISTS idx_tokens_request ON api_tokens(request_id)`); }
+catch (e: any) { /* index may already exist */ void e; }
+
+// RFC-026 v4 §2.5 + §4.4 — node_create_requests. Metadata only;
+// env_blob NEVER lives in this table (F1 mint-stream-evict — secret
+// blob is in-memory Map keyed by request_id, drained on daemon get,
+// TTL 60s GC).
+//
+// env_keys is a JSON array of secret KEY NAMES only (for audit). The
+// actual values flow through pendingEnvBlobs Map and never touch
+// disk.
+db.exec(`
+  CREATE TABLE IF NOT EXISTS node_create_requests (
+    request_id        TEXT PRIMARY KEY,
+    daemon_node_id    TEXT NOT NULL,
+    child_name        TEXT NOT NULL,
+    network_id        TEXT NOT NULL,
+    runtime           TEXT NOT NULL,
+    model             TEXT NOT NULL,
+    flags_json        TEXT NOT NULL,
+    env_keys          TEXT NOT NULL,
+    status            TEXT NOT NULL,
+    error             TEXT,
+    child_token_id    TEXT,
+    created_at        INTEGER NOT NULL,
+    created_by_token  TEXT NOT NULL,
+    delivered_at      INTEGER,
+    acked_at          INTEGER,
+    child_node_id     TEXT
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_ncr_daemon_status ON node_create_requests(daemon_node_id, status);
+  CREATE INDEX IF NOT EXISTS idx_ncr_network ON node_create_requests(network_id);
+  CREATE INDEX IF NOT EXISTS idx_ncr_child_name ON node_create_requests(child_name);
+`);
+try {
+  // Single-flight per (daemon, child_name) — prevents racing dashboard
+  // create on same name. Mirrors RFC-024 uniq_ncu_node_inflight.
+  db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS uniq_ncr_inflight ON node_create_requests(daemon_node_id, child_name) WHERE status IN ('pending', 'delivered')`);
+} catch (e: any) {
+  console.warn(`[commhub] partial unique index uniq_ncr_inflight skipped: ${e?.message || e}`);
+}
+
+// RFC-028 P1 v4 §2.2 — providers + provider_models + network_secrets +
+// probe_results. All 4 tables idempotent CREATE TABLE IF NOT EXISTS. F2
+// lazy gate: tables created on hub boot regardless; vault master key
+// (ANET_HUB_SECRET_VAULT_KEY env) only required when these tables get
+// their first non-empty row (lazy in vault.ts). Empty tables = hub
+// boots fine without env (critical for existing prod hub升级 不 brick).
+db.exec(`
+  CREATE TABLE IF NOT EXISTS providers (
+    provider_id     TEXT PRIMARY KEY,
+    network_id      TEXT NOT NULL,
+    name            TEXT NOT NULL,
+    vendor          TEXT NOT NULL,
+    base_url        TEXT NOT NULL,
+    secret_key_ref  TEXT NOT NULL,
+    created_at      INTEGER NOT NULL,
+    created_by      TEXT NOT NULL,
+    enabled         INTEGER NOT NULL DEFAULT 1,
+    UNIQUE(network_id, name)
+  );
+  CREATE INDEX IF NOT EXISTS idx_providers_network ON providers(network_id);
+`);
+db.exec(`
+  CREATE TABLE IF NOT EXISTS provider_models (
+    model_id        TEXT PRIMARY KEY,
+    provider_id     TEXT NOT NULL,
+    model_name      TEXT NOT NULL,
+    display_name    TEXT,
+    context_window  INTEGER,
+    supports_vision INTEGER NOT NULL DEFAULT 0,
+    enabled         INTEGER NOT NULL DEFAULT 1,
+    created_at      INTEGER NOT NULL,
+    UNIQUE(provider_id, model_name)
+  );
+  CREATE INDEX IF NOT EXISTS idx_models_provider ON provider_models(provider_id);
+`);
+// network_secrets — encrypted-at-rest vault. ciphertext + iv + tag are
+// AES-GCM output; plaintext NEVER touches this table. master key from
+// ANET_HUB_SECRET_VAULT_KEY env (lazy gate in vault.ts).
+db.exec(`
+  CREATE TABLE IF NOT EXISTS network_secrets (
+    network_id   TEXT NOT NULL,
+    key          TEXT NOT NULL,
+    ciphertext   BLOB NOT NULL,
+    iv           BLOB NOT NULL,
+    tag          BLOB NOT NULL,
+    created_at   INTEGER NOT NULL,
+    updated_at   INTEGER NOT NULL,
+    PRIMARY KEY (network_id, key)
+  );
+`);
+// probe_results — connectivity matrix history. v3 R3 lock: error_label
+// is HUB-DERIVED ONLY from (status, raw_status_code) — daemon CANNOT
+// submit arbitrary error string. status enum mirrors ProbeAckPayload.
+db.exec(`
+  CREATE TABLE IF NOT EXISTS probe_results (
+    probe_id        TEXT PRIMARY KEY,
+    provider_id     TEXT NOT NULL,
+    model_name      TEXT NOT NULL,
+    daemon_node_id  TEXT NOT NULL,
+    network_id      TEXT NOT NULL,
+    status          TEXT NOT NULL,
+    latency_ms      INTEGER,
+    error_label     TEXT,
+    probed_at       INTEGER NOT NULL,
+    probed_by_user  TEXT,
+    raw_status_code INTEGER
+  );
+  CREATE INDEX IF NOT EXISTS idx_probe_matrix ON probe_results(network_id, provider_id, model_name, daemon_node_id, probed_at DESC);
+`);
+
 // ── V3: audit_log table ──
 db.exec(`
   CREATE TABLE IF NOT EXISTS audit_log (