sigrank 0.15.5 → 0.16.1

package/preflight.mjs

@@ -0,0 +1,191 @@
+/**
+ * preflight.mjs — local plausibility pre-checks for the MCP submit path.
+ *
+ * Mirrors ONLY the server's public plausibility gate (gates.ts:86-137) —
+ * totals consistency, turns/sessions ratios, output rate, cache ratio,
+ * cadence. These are integrity guards labeled "NOT the proprietary RS.xx"
+ * and are safe to replicate in an open agent.
+ *
+ * The proprietary battery (Benford / cadence / contamination) is SERVER-ONLY
+ * and must NOT be shipped in the agent. The server always runs its own
+ * battery after the POST — this preflight is a client-side preview of the
+ * public plausibility checks only, not a replacement for the full gate chain.
+ *
+ * If preflight flags, the operator sees WHY their submission would be
+ * rejected or flagged, and can fix the issue or submit anyway.
+ *
+ * Source of truth: lib/ingest/gates.ts (plausibilityGate). This port must
+ * stay in sync with the plausibility gate ONLY.
+ */
+
+// ── plausibility checks (from gates.ts:86-137) ──────────────────────────────
+
+const GATE_LIMITS = {
+  TOTALS_TOLERANCE_FRAC: 0.01,
+  MAX_OUTPUT_TOKENS_PER_MIN: 20_000,
+  // Tightened range-plausibility bounds (deviewreview3)
+  MAX_CACHE_REUSE_RATIO: 35,
+  MIN_CACHE_WRITE_RATIO: 0.5,
+  MIN_INPUT_SHARE_FRAC: 0.0003,
+  MAX_CADENCE_PER_MIN: 15,
+};
+
+/**
+ * Run plausibility checks against a payload's raw_telemetry.
+ * Returns array of issues: { severity, code, detail }
+ */
+export function plausibilityCheck(rt, window) {
+  const out = [];
+  const pillars =
+    rt.tokens_input_fresh +
+    rt.tokens_output +
+    rt.tokens_cache_read +
+    rt.tokens_cache_creation;
+
+  if (rt.tokens_total > 0) {
+    const tol = Math.max(
+      1,
+      rt.tokens_total * GATE_LIMITS.TOTALS_TOLERANCE_FRAC,
+    );
+    if (Math.abs(pillars - rt.tokens_total) > tol) {
+      out.push({
+        severity: "reject",
+        code: "totals_inconsistent",
+        detail: `Σ4 pillars (${pillars}) ≠ tokens_total (${rt.tokens_total})`,
+      });
+    }
+    if (rt.sessions_count === 0) {
+      out.push({
+        severity: "reject",
+        code: "tokens_without_sessions",
+        detail: `tokens_total ${rt.tokens_total} with sessions_count 0`,
+      });
+    }
+  }
+  if (rt.turns_total < rt.sessions_count) {
+    out.push({
+      severity: "reject",
+      code: "turns_lt_sessions",
+      detail: `turns_total ${rt.turns_total} < sessions_count ${rt.sessions_count}`,
+    });
+  }
+  if (rt.tokens_output > 0 && rt.turns_total === 0) {
+    out.push({
+      severity: "reject",
+      code: "output_without_turns",
+      detail: `tokens_output ${rt.tokens_output} with turns_total 0`,
+    });
+  }
+
+  if (window) {
+    const spanMin =
+      (Date.parse(window.end) - Date.parse(window.start)) / 60_000;
+    if (Number.isFinite(spanMin) && rt.active_minutes_est > spanMin + 1) {
+      out.push({
+        severity: "flag",
+        code: "active_exceeds_window",
+        detail: `active_minutes_est ${rt.active_minutes_est} > window span ${Math.round(spanMin)}m`,
+      });
+    }
+  }
+
+  const outPerMin = rt.tokens_output / Math.max(rt.active_minutes_est, 1);
+  if (outPerMin > GATE_LIMITS.MAX_OUTPUT_TOKENS_PER_MIN) {
+    out.push({
+      severity: "flag",
+      code: "implausible_output_rate",
+      detail: `${Math.round(outPerMin)} output tok/min > ${GATE_LIMITS.MAX_OUTPUT_TOKENS_PER_MIN}`,
+    });
+  }
+
+  // Cross-field ratio checks (defense-in-depth — also in the plausibility gate)
+  // Bounds tightened (deviewreview3): original 100:1 + 50/min were too loose.
+  if (rt.tokens_cache_read > 1_000 && rt.tokens_cache_creation === 0) {
+    out.push({
+      severity: "flag",
+      code: "cache_without_creation",
+      detail: `${rt.tokens_cache_read} cache_read with 0 cache_creation (impossible cascade)`,
+    });
+  }
+  if (
+    rt.tokens_cache_creation > 0 &&
+    rt.tokens_cache_read / rt.tokens_cache_creation >
+      GATE_LIMITS.MAX_CACHE_REUSE_RATIO
+  ) {
+    out.push({
+      severity: "flag",
+      code: "extreme_cache_ratio",
+      detail: `cache_read/cache_creation = ${(rt.tokens_cache_read / rt.tokens_cache_creation).toFixed(1)}:1 (real max ~30:1)`,
+    });
+  }
+  if (
+    rt.tokens_output > 1_000 &&
+    rt.tokens_cache_creation / rt.tokens_output <
+      GATE_LIMITS.MIN_CACHE_WRITE_RATIO
+  ) {
+    out.push({
+      severity: "flag",
+      code: "low_cache_write_ratio",
+      detail: `cache_creation/output = ${(rt.tokens_cache_creation / rt.tokens_output).toFixed(2)}:1 (real min ~1.5:1)`,
+    });
+  }
+  if (
+    pillars > 10_000 &&
+    rt.tokens_input_fresh / pillars < GATE_LIMITS.MIN_INPUT_SHARE_FRAC
+  ) {
+    out.push({
+      severity: "flag",
+      code: "implausible_input_share",
+      detail: `input is ${((rt.tokens_input_fresh / pillars) * 100).toFixed(3)}% of total (real min ~0.3%)`,
+    });
+  }
+  if (
+    rt.active_minutes_est > 0 &&
+    rt.turns_total / rt.active_minutes_est > GATE_LIMITS.MAX_CADENCE_PER_MIN
+  ) {
+    out.push({
+      severity: "flag",
+      code: "implausible_cadence",
+      detail: `${(rt.turns_total / rt.active_minutes_est).toFixed(1)} turns/min (real: 0.5-10)`,
+    });
+  }
+
+  return out;
+}
+
+// ── full preflight (plausibility only — NO battery) ─────────────────────────
+
+/**
+ * Run preflight plausibility checks against a payload. Returns:
+ *   { pass: true, issues: [] }                    — clean submission
+ *   { pass: false, issues: [...], wouldDowngrade } — would be flagged/rejected
+ *
+ * NOTE: this only mirrors the PUBLIC plausibility gate. The server runs
+ * additional proprietary checks (the battery) that this preflight does NOT
+ * replicate. A "pass" here means "passes the plausibility gate," not
+ * "guaranteed to pass all server gates."
+ */
+export function preflight(payload) {
+  const issues = plausibilityCheck(payload.raw_telemetry, payload.window);
+
+  const hasReject = issues.some((i) => i.severity === "reject");
+  const hasFlag = issues.some((i) => i.severity === "flag");
+
+  return {
+    pass: issues.length === 0,
+    wouldReject: hasReject,
+    wouldDowngrade: hasFlag,
+    issues,
+    summary: hasReject
+      ? `REJECT: ${issues
+          .filter((i) => i.severity === "reject")
+          .map((i) => i.code)
+          .join(", ")}`
+      : hasFlag
+        ? `FLAG (verified → flagged, not ranked): ${issues
+            .filter((i) => i.severity === "flag")
+            .map((i) => i.code)
+            .join(", ")}`
+        : "clean — passes plausibility gate (server runs additional proprietary checks)",
+  };
+}

package/sign.mjs

@@ -12,54 +12,64 @@
 // The canon-parity fixture (tests/fixtures/canon_parity.json) + sign.test.mjs + the
 // sigrank-app canon_parity gate together lock this byte-for-byte.
 
-import { createHash, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto'
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  sign as edSign,
+  verify as edVerify,
+} from "node:crypto";
 
 /** Agent fields excluded from the canonical (signed/hashed) body — they derive from it. */
-const DERIVED_AGENT_FIELDS = ['signature', 'snapshot_hash']
+const DERIVED_AGENT_FIELDS = ["signature", "snapshot_hash"];
 
 /** Recursively sort object keys (matches the server's Object.keys(...).sort()); arrays keep order. */
 function sortDeep(v) {
-  if (Array.isArray(v)) return v.map(sortDeep)
-  if (v && typeof v === 'object') {
-    const out = {}
-    for (const k of Object.keys(v).sort()) out[k] = sortDeep(v[k])
-    return out
+  if (Array.isArray(v)) return v.map(sortDeep);
+  if (v && typeof v === "object") {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sortDeep(v[k]);
+    return out;
   }
-  return v
+  return v;
 }
 
 /** Canonical JSON string the agent signs/hashes (derived agent fields stripped). */
 export function canonicalJson(payload) {
-  const clone = JSON.parse(JSON.stringify(payload))
-  const agent = clone.agent
-  if (agent && typeof agent === 'object') {
-    for (const f of DERIVED_AGENT_FIELDS) delete agent[f]
+  const clone = JSON.parse(JSON.stringify(payload));
+  const agent = clone.agent;
+  if (agent && typeof agent === "object") {
+    for (const f of DERIVED_AGENT_FIELDS) delete agent[f];
   }
-  return JSON.stringify(sortDeep(clone))
+  return JSON.stringify(sortDeep(clone));
 }
 
 /** UTF-8 bytes of the canonical JSON — the exact bytes that get signed. */
 export function canonicalBytes(payload) {
-  return Buffer.from(canonicalJson(payload), 'utf-8')
+  return Buffer.from(canonicalJson(payload), "utf-8");
 }
 
 /** "sha256:<hex>" over the canonical bytes (matches the server snapshotHash). */
 export function snapshotHash(payload) {
-  return `sha256:${createHash('sha256').update(canonicalBytes(payload)).digest('hex')}`
+  return `sha256:${createHash("sha256").update(canonicalBytes(payload)).digest("hex")}`;
 }
 
 /** SPKI DER prefix for a raw 32-byte ed25519 public key. */
-const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex')
+const ED25519_SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
 
 /** Build a node KeyObject from an "ed25519:<base64>" (or bare base64) public key, or null. */
 function publicKeyFrom(pk) {
   try {
-    const body = pk.startsWith('ed25519:') ? pk.slice('ed25519:'.length) : pk
-    const raw = Buffer.from(body, 'base64')
-    if (raw.length !== 32) return null
-    return createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, raw]), format: 'der', type: 'spki' })
+    const body = pk.startsWith("ed25519:") ? pk.slice("ed25519:".length) : pk;
+    const raw = Buffer.from(body, "base64");
+    if (raw.length !== 32) return null;
+    return createPublicKey({
+      key: Buffer.concat([ED25519_SPKI_PREFIX, raw]),
+      format: "der",
+      type: "spki",
+    });
   } catch {
-    return null
+    return null;
   }
 }
 
@@ -68,8 +78,12 @@ function publicKeyFrom(pk) {
  * The returned string is the X-Agent-Signature header value.
  */
 export function signPayload(payload, privateKeyPkcs8B64) {
-  const key = createPrivateKey({ key: Buffer.from(privateKeyPkcs8B64, 'base64'), format: 'der', type: 'pkcs8' })
-  return edSign(null, canonicalBytes(payload), key).toString('base64')
+  const key = createPrivateKey({
+    key: Buffer.from(privateKeyPkcs8B64, "base64"),
+    format: "der",
+    type: "pkcs8",
+  });
+  return edSign(null, canonicalBytes(payload), key).toString("base64");
 }
 
 /**
@@ -77,11 +91,16 @@ export function signPayload(payload, privateKeyPkcs8B64) {
  * and as a pre-send sanity check. Returns false on any malformation, never throws.
  */
 export function verifyPayload(payload, signatureB64, publicKey) {
-  const key = publicKeyFrom(publicKey)
-  if (!key) return false
+  const key = publicKeyFrom(publicKey);
+  if (!key) return false;
   try {
-    return edVerify(null, canonicalBytes(payload), key, Buffer.from(signatureB64, 'base64'))
+    return edVerify(
+      null,
+      canonicalBytes(payload),
+      key,
+      Buffer.from(signatureB64, "base64"),
+    );
   } catch {
-    return false
+    return false;
   }
 }

package/submit.mjs

@@ -9,54 +9,78 @@
 // TODO(tokenpull): emit real sessions_count / turns_total / active_minutes per window so
 // the display signa_rate reflects true session shape (the ranked Υ is already exact).
 
-import { snapshotHash, signPayload } from './sign.mjs'
+import { snapshotHash, signPayload } from "./sign.mjs";
+import { preflight } from "./preflight.mjs";
 
-const WINDOW_TYPE = { '7d': '7d', '30d': '30d', '90d': '90d', all: 'all_time' }
-const WINDOW_SPAN_DAYS = { '7d': 7, '30d': 30, '90d': 90, all_time: 3650 }
-const PLATFORM_ENUM = new Set(['claude', 'chatgpt', 'gemini', 'pi', 'codex', 'multi', 'other'])
+const WINDOW_TYPE = { "7d": "7d", "30d": "30d", "90d": "90d", all: "all_time" };
+const WINDOW_SPAN_DAYS = { "7d": 7, "30d": 30, "90d": 90, all_time: 3650 };
+const PLATFORM_ENUM = new Set([
+  "claude",
+  "chatgpt",
+  "gemini",
+  "pi",
+  "codex",
+  "multi",
+  "other",
+]);
 // Provenance tag only — the board ranks by Υ (no RS.xx weights, §0.1).
-const RULESET_VERSION = 'sigrank-token-1'
-const DAY_MS = 86_400_000
+const RULESET_VERSION = "sigrank-token-1";
+const DAY_MS = 86_400_000;
 
-const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x))
+const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x));
 const round = (n, dp) => {
-  const f = 10 ** dp
-  return Math.round(n * f) / f
-}
+  const f = 10 ** dp;
+  return Math.round(n * f) / f;
+};
 
 /** Map any tokenpull platform to the Schema 1.0 platform.primary enum (others → 'other'). */
 export function toPlatformPrimary(platform) {
-  return PLATFORM_ENUM.has(platform) ? platform : 'other'
+  return PLATFORM_ENUM.has(platform) ? platform : "other";
 }
 
 /**
  * buildPayload — Schema 1.0 payload from a tokenpull window + enrolled identity.
  * Pure (given opts.now); agent.snapshot_hash is computed last (canonical strips it).
  */
-export function buildPayload(windowKey, pillars, messages, identity, platform, opts = {}) {
-  const windowType = WINDOW_TYPE[windowKey] || windowKey
-  const spanDays = WINDOW_SPAN_DAYS[windowType] || 30
-  const nowMs = opts.now ?? Date.now()
+export function buildPayload(
+  windowKey,
+  pillars,
+  messages,
+  identity,
+  platform,
+  opts = {},
+) {
+  const windowType = WINDOW_TYPE[windowKey] || windowKey;
+  const spanDays = WINDOW_SPAN_DAYS[windowType] || 30;
+  const nowMs = opts.now ?? Date.now();
 
-  const input = Math.max(0, Math.round(pillars?.input || 0))
-  const output = Math.max(0, Math.round(pillars?.output || 0))
-  const cacheCreate = Math.max(0, Math.round(pillars?.cacheCreate || 0))
-  const cacheRead = Math.max(0, Math.round(pillars?.cacheRead || 0))
-  const tokensTotal = input + output + cacheCreate + cacheRead
+  const input = Math.max(0, Math.round(pillars?.input || 0));
+  const output = Math.max(0, Math.round(pillars?.output || 0));
+  const cacheCreate = Math.max(0, Math.round(pillars?.cacheCreate || 0));
+  const cacheRead = Math.max(0, Math.round(pillars?.cacheRead || 0));
+  const tokensTotal = input + output + cacheCreate + cacheRead;
 
   // Proxies — plausibility-clean (see file header).
-  const msgs = Math.max(0, Math.round(messages || 0))
-  const turnsTotal = Math.max(output > 0 ? 1 : 0, msgs)
-  const sessionsCount = tokensTotal > 0 ? clamp(Math.round(msgs / 8) || 1, 1, Math.max(1, turnsTotal)) : 0
-  const spanMinutes = spanDays * 1440
-  const minActive = Math.ceil(output / 19000) + 1 // keep output/active under the 20k/min flag
-  const activeMinutes = clamp(Math.max(msgs, minActive), 1, Math.max(1, spanMinutes - 1))
+  const msgs = Math.max(0, Math.round(messages || 0));
+  const turnsTotal = Math.max(output > 0 ? 1 : 0, msgs);
+  const sessionsCount =
+    tokensTotal > 0
+      ? clamp(Math.round(msgs / 8) || 1, 1, Math.max(1, turnsTotal))
+      : 0;
+  const spanMinutes = spanDays * 1440;
+  const minActive = Math.ceil(output / 19000) + 1; // keep output/active under the 20k/min flag
+  const activeMinutes = clamp(
+    Math.max(msgs, minActive),
+    1,
+    Math.max(1, spanMinutes - 1),
+  );
 
-  const compressionRatio = input + output > 0 ? clamp(output / (input + output), 0, 1) : 0
-  const sessionDepth = sessionsCount > 0 ? turnsTotal / sessionsCount : 0
+  const compressionRatio =
+    input + output > 0 ? clamp(output / (input + output), 0, 1) : 0;
+  const sessionDepth = sessionsCount > 0 ? turnsTotal / sessionsCount : 0;
 
   const payload = {
-    schema_version: '1.0',
+    schema_version: "1.0",
     codename: identity.codename,
     device_id: identity.device_id,
     submitted_at: new Date(nowMs).toISOString(),
@@ -69,7 +93,11 @@ export function buildPayload(windowKey, pillars, messages, identity, platform, o
     core_metrics: {
       compression_ratio: round(compressionRatio, 4),
       prompt_complexity: round(clamp(sessionDepth, 0, 100), 2),
-      cross_thread_score: clamp(Math.round(cacheRead / Math.max(cacheCreate, 1)), 0, 100000),
+      cross_thread_score: clamp(
+        Math.round(cacheRead / Math.max(cacheCreate, 1)),
+        0,
+        100000,
+      ),
       session_depth_avg: round(Math.max(0, sessionDepth), 2),
       // M.05 token_throughput muted 2026-06-26 — word-era metric the web already
       // mutes (RS01 tt→0) + strips. Send null (RPC p_token_throughput is nullable
@@ -79,7 +107,10 @@ export function buildPayload(windowKey, pillars, messages, identity, platform, o
     background_metrics: {
       message_volume: msgs,
       account_age_days: Math.max(1, Math.round(opts.accountAgeDays ?? 365)),
-      total_messages_lifetime: Math.max(msgs, Math.round(opts.totalMessages ?? msgs)),
+      total_messages_lifetime: Math.max(
+        msgs,
+        Math.round(opts.totalMessages ?? msgs),
+      ),
     },
     raw_telemetry: {
       sessions_count: sessionsCount,
@@ -91,16 +122,24 @@ export function buildPayload(windowKey, pillars, messages, identity, platform, o
       tokens_cache_creation: cacheCreate,
       active_minutes_est: activeMinutes,
     },
-    tier: 'free',
+    tier: "free",
     agent: {
       version: identity.agent_version,
       ruleset_version: RULESET_VERSION,
-      snapshot_hash: '',
+      snapshot_hash: "",
       public_key: identity.public_key,
     },
+  };
+
+  // Cascade Report block (Phase 1 — mode detection + badges + health).
+  // Computed locally (pure math), submitted alongside the 4 token pillars.
+  // The server stores it as-is — does NOT recompute modes.
+  // Weekly granularity is the privacy boundary — daily modes never leave the machine.
+  if (opts.report && typeof opts.report === "object") {
+    payload.report = opts.report;
   }
-  payload.agent.snapshot_hash = snapshotHash(payload)
-  return payload
+  payload.agent.snapshot_hash = snapshotHash(payload);
+  return payload;
 }
 
 /**
@@ -108,74 +147,139 @@ export function buildPayload(windowKey, pillars, messages, identity, platform, o
  * Returns a structured result; never throws on a network error. opts: { apiBase,
  * fetchImpl, platform, now } (fetchImpl lets the caller inject a timeout-wrapped fetch).
  */
-export async function submitSignedWindow(windowKey, pillars, messages, identity, opts = {}) {
+export async function submitSignedWindow(
+  windowKey,
+  pillars,
+  messages,
+  identity,
+  opts = {},
+) {
   if (!identity?.codename || !identity?.operator_id) {
-    return { status: 'not_enrolled', reason: 'not_enrolled', detail: 'Run `npx sigrank-mcp enroll` to bind this device first.' }
+    return {
+      status: "not_enrolled",
+      reason: "not_enrolled",
+      detail: "Run `npx sigrank-mcp enroll` to bind this device first.",
+    };
   }
   if (!identity?.private_key_pkcs8_b64) {
-    return { status: 'error', reason: 'no_key', detail: 'No local signing key — re-run `npx sigrank-mcp enroll`.' }
+    return {
+      status: "error",
+      reason: "no_key",
+      detail: "No local signing key — re-run `npx sigrank-mcp enroll`.",
+    };
   }
 
-  const apiBase = opts.apiBase || process.env.SIGRANK_API_BASE || 'https://signalaf.com'
+  const apiBase =
+    opts.apiBase || process.env.SIGRANK_API_BASE || "https://signalaf.com";
   // FIX M: default a 15s AbortController timeout when the caller doesn't inject a
   // fetchImpl. The TUI path already wraps fetch (callTool → doFetch, 10s), but the
   // legacy CLI `watch --submit` + the CLI default-view [S] call submitSignedWindow
   // with no fetchImpl → bare fetch → a hung POST blocks forever. This default fixes
   // it everywhere at once. (15s is generous for a signed POST to /api/v1/snapshots.)
-  const fetchImpl = opts.fetchImpl || ((url, init = {}) => {
-    const ctrl = new AbortController()
-    const timer = setTimeout(() => ctrl.abort(), 15_000)
-    return fetch(url, { ...init, signal: init.signal || ctrl.signal }).finally(() => clearTimeout(timer))
-  })
-  const payload = buildPayload(windowKey, pillars, messages, identity, opts.platform || 'claude', opts)
-  const signature = signPayload(payload, identity.private_key_pkcs8_b64)
+  const fetchImpl =
+    opts.fetchImpl ||
+    ((url, init = {}) => {
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), 15_000);
+      return fetch(url, {
+        ...init,
+        signal: init.signal || ctrl.signal,
+      }).finally(() => clearTimeout(timer));
+    });
+  const payload = buildPayload(
+    windowKey,
+    pillars,
+    messages,
+    identity,
+    opts.platform || "claude",
+    opts,
+  );
+
+  // Preflight: run the same anti-gaming checks the server will run, locally.
+  // If the payload would be rejected or downgraded, warn the operator BEFORE
+  // submitting. The server always runs its own checks — this is a preview.
+  const pre = preflight(payload);
+  if (!pre.pass && !opts.skipPreflight) {
+    if (pre.wouldReject) {
+      return {
+        status: "preflight_rejected",
+        window: WINDOW_TYPE[windowKey] || windowKey,
+        preflight: pre,
+        detail: `Submission would be REJECTED by the server: ${pre.summary}. Fix the issue or re-run with skipPreflight.`,
+      };
+    }
+    // Flags downgrade verified → flagged (not ranked). Warn but don't block
+    // unless the caller explicitly asked for strict mode.
+    if (opts.strictPreflight) {
+      return {
+        status: "preflight_flagged",
+        window: WINDOW_TYPE[windowKey] || windowKey,
+        preflight: pre,
+        detail: `Submission would be DOWNGRADED (not ranked): ${pre.summary}. Fix the issue or re-run with skipPreflight.`,
+      };
+    }
+    // Non-strict: attach the preflight warning to the result but proceed.
+  }
+
+  const signature = signPayload(payload, identity.private_key_pkcs8_b64);
 
   // Dry run: build + sign exactly as a real publish, then STOP before the POST.
   // Returns the exact payload that would be sent — the privacy proof ("token
   // counts only") is inspectable, and nothing touches the network.
   if (opts.dryRun) {
     return {
-      status: 'dry_run',
+      status: "dry_run",
       window: WINDOW_TYPE[windowKey] || windowKey,
       would_post: `${apiBase}/api/v1/snapshots`,
       payload,
       signature,
-      detail: 'Nothing sent. Re-run without dry_run to publish.',
-    }
+      preflight: pre,
+      detail: "Nothing sent. Re-run without dry_run to publish.",
+    };
   }
 
-  let res
-  let ack
+  let res;
+  let ack;
   try {
     res = await fetchImpl(`${apiBase}/api/v1/snapshots`, {
-      method: 'POST',
+      method: "POST",
       headers: {
-        'content-type': 'application/json',
-        accept: 'application/json',
-        'x-agent-signature': signature,
+        "content-type": "application/json",
+        accept: "application/json",
+        "x-agent-signature": signature,
       },
       body: JSON.stringify(payload),
-    })
+    });
     try {
-      ack = await res.json()
+      ack = await res.json();
     } catch {
-      ack = {}
+      ack = {};
     }
   } catch (e) {
-    return { status: 'error', reason: 'network', detail: e.message, window: WINDOW_TYPE[windowKey] || windowKey }
+    return {
+      status: "error",
+      reason: "network",
+      detail: e.message,
+      window: WINDOW_TYPE[windowKey] || windowKey,
+    };
   }
 
   return {
-    status: res.ok ? ack.status || 'received' : 'error',
+    status: res.ok ? ack.status || "received" : "error",
     httpStatus: res.status,
     window: WINDOW_TYPE[windowKey] || windowKey,
     verification_tier: ack.verification_tier ?? null,
     persisted: ack.persisted ?? null,
     // ranked = actually on the board (verified + written), not just "received".
     // An unenrolled/revoked device gets HTTP 202 received but is NEVER ranked.
-    ranked: !!(res.ok && ack.verification_tier === 'verified' && ack.persisted === true),
+    ranked: !!(
+      res.ok &&
+      ack.verification_tier === "verified" &&
+      ack.persisted === true
+    ),
     snapshot_hash: payload.agent.snapshot_hash,
     reason: res.ok ? null : ack.reason || ack.status || `http_${res.status}`,
     detail: ack.detail ?? null,
-  }
+    preflight: pre,
+  };
 }