sigrank 0.19.0 → 1.0.2

package/submit/index.mjs

@@ -0,0 +1,297 @@
+// submit.mjs — build + ed25519-sign a Schema 1.0 snapshot payload and POST it to the
+// VERIFIED ingest endpoint (D7 §5). Requires an enrolled identity (keystore.codename +
+// operator_id + private key). The server re-derives the ranked Υ from the 4 raw pillars,
+// so the core/background metrics here are schema-valid, plausibility-clean DISPLAY inputs.
+//
+// raw_telemetry sessions/turns/active are conservative PROXIES: tokenpull yields the 4
+// pillars + a message count, not session structure. They are chosen to pass the
+// plausibility gate WITHOUT flagging (a flag downgrades verified→flagged → not ranked).
+// 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 "../identity/sign.mjs";
+import { preflight } from "./preflight.mjs";
+import { pkgVersion } from "../lib/pkg-version.mjs";
+import {
+  TERMS_VERSION,
+  PRIVACY_VERSION,
+  isRankedAck,
+} from "../lib/constants.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",
+  "omp",
+  "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 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;
+};
+
+/** 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";
+}
+
+/**
+ * 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();
+
+  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 compressionRatio =
+    input + output > 0 ? clamp(output / (input + output), 0, 1) : 0;
+  const sessionDepth = sessionsCount > 0 ? turnsTotal / sessionsCount : 0;
+
+  const payload = {
+    schema_version: "1.0",
+    codename: identity.codename,
+    device_id: identity.device_id,
+    submitted_at: new Date(nowMs).toISOString(),
+    consent_acknowledged: true,
+    terms_version: TERMS_VERSION,
+    privacy_version: PRIVACY_VERSION,
+    window: {
+      type: windowType,
+      start: new Date(nowMs - spanDays * DAY_MS).toISOString(),
+      end: new Date(nowMs).toISOString(),
+    },
+    platform: { primary: toPlatformPrimary(platform), models: [] },
+    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,
+      ),
+      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
+      // DEFAULT NULL). raw_telemetry.tokens_total still carries the raw count.
+      token_throughput: null,
+    },
+    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),
+      ),
+    },
+    raw_telemetry: {
+      sessions_count: sessionsCount,
+      turns_total: turnsTotal,
+      tokens_total: tokensTotal,
+      tokens_input_fresh: input,
+      tokens_output: output,
+      tokens_cache_read: cacheRead,
+      tokens_cache_creation: cacheCreate,
+      active_minutes_est: activeMinutes,
+    },
+    tier: "free",
+    agent: {
+      version: identity.agent_version,
+      ruleset_version: RULESET_VERSION,
+      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;
+}
+
+/**
+ * submitSignedWindow — build + sign + POST one window to /api/v1/snapshots.
+ * 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 = {},
+) {
+  if (!identity?.codename || !identity?.operator_id) {
+    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`.",
+    };
+  }
+
+  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);
+      const headers = {
+        "user-agent": `node/${process.version} sigrank-mcp/${pkgVersion()}`,
+        ...(init.headers || {}),
+      };
+      return fetch(url, {
+        ...init,
+        headers,
+        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 are internal signals on the server — they no longer block ranking.
+    // Warn the operator but don't block unless strict mode is explicitly set.
+    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",
+      window: WINDOW_TYPE[windowKey] || windowKey,
+      would_post: `${apiBase}/api/v1/snapshots`,
+      payload,
+      signature,
+      preflight: pre,
+      detail:
+        "By submitting, you agree to the SignalAF Terms of Service and Privacy Policy. Nothing sent. Re-run without dry_run to publish.",
+    };
+  }
+
+  let res;
+  let ack;
+  try {
+    res = await fetchImpl(`${apiBase}/api/v1/snapshots`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json",
+        "x-agent-signature": signature,
+      },
+      body: JSON.stringify(payload),
+    });
+    try {
+      ack = await res.json();
+    } catch {
+      ack = {};
+    }
+  } catch (e) {
+    return {
+      status: "error",
+      reason: "network",
+      detail: e.message,
+      window: WINDOW_TYPE[windowKey] || windowKey,
+    };
+  }
+
+  return {
+    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: isRankedAck(res, ack),
+    snapshot_hash: payload.agent.snapshot_hash,
+    reason: res.ok ? null : ack.reason || ack.status || `http_${res.status}`,
+    detail: ack.detail ?? null,
+    preflight: pre,
+  };
+}

package/submit/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)",
+  };
+}