sigrank 0.0.175

package/narrate.mjs

@@ -0,0 +1,77 @@
+/**
+ * narrate.mjs — deterministic prose "card" for a cascade result.
+ *
+ * Port of _template() from ~/Desktop/moses-sigrank/narrate.py. The model path
+ * (MiniCPM4-0.5B) is intentionally SKIPPED: the template is the trustworthy,
+ * instant, auditable fallback — same numbers in → same card out, and it can never
+ * emit a metric the cascade didn't produce. A model hook can layer behind this same
+ * narrate() interface later without a rewrite.
+ *
+ * Token-only. No network, no randomness.
+ */
+
+// Safe formatters: never emit NaN/Infinity/undefined into the card.
+const safeNum = (n) => (Number.isFinite(Number(n)) ? Number(n) : null);
+const comma = (n, dec) => {
+  const v = safeNum(n);
+  return v !== null
+    ? v.toLocaleString("en-US", {
+        minimumFractionDigits: dec,
+        maximumFractionDigits: dec,
+      })
+    : "—";
+};
+const plain = (n, dec) => {
+  const v = safeNum(n);
+  return v !== null ? v.toFixed(dec) : "—";
+};
+
+/**
+ * Given a cascade result ({ velocity, leverage, dev10x, pillars, class }) and an
+ * optional subject name, return "**CLASS.** <one or two sentences>". Deterministic.
+ */
+export function narrate(cascade, name = "This operator") {
+  const klass = cascade.class || cascade.klass || "UNCLASSED";
+  const v = safeNum(cascade.velocity);
+  const l = safeNum(cascade.leverage);
+
+  // "non-compounding" = a stateless pipe: no cache commits, so the cascade can't
+  // form. cascade.mjs leaves dev10x null when cacheCreate is 0 (the cw/o term
+  // collapses), which is exactly metrics.py's non_compounding flag.
+  // Also catches zero-input sessions where velocity/leverage are null.
+  const cw = cascade.pillars ? Number(cascade.pillars.cacheCreate) : NaN;
+  const nonCompounding =
+    cascade.dev10x == null || !(cw > 0) || v === null || l === null;
+
+  let body;
+  if (nonCompounding) {
+    const leverageStr =
+      l !== null
+        ? `Leverage ${comma(l, 1)}x comes from reuse alone.`
+        : "Leverage is undefined (no fresh input recorded).";
+    const dev10xNote =
+      cascade.dev10x == null
+        ? " 10xDEV is undefined — the compounding loop has not formed yet."
+        : "";
+    body =
+      `${name} runs a stateless pipe — no cache commits, so the cascade can't form. ` +
+      `High read volume, but nothing is being built forward. ${leverageStr}${dev10xNote}`;
+  } else if (v >= 1 && l >= 100) {
+    body =
+      `${name} holds both axes at once: ${plain(v, 1)}x generation AND ${comma(l, 0)}x memory leverage. ` +
+      `A closed kinetic loop — the rare operator the leverage/generation tradeoff says shouldn't exist.`;
+  } else if (l >= 10 && v < 1) {
+    body =
+      `${name} is an archival sponge — ${comma(l, 0)}x reuse but only ${plain(v, 2)}x generation. ` +
+      `Holds context beautifully, executes little with it. The reuse number is inflated by a weak commitment stage.`;
+  } else if (v >= 0.8 && l < 2) {
+    body =
+      `${name} is a volatile ingestor — ${plain(v, 2)}x generation but ${plain(l, 1)}x leverage. ` +
+      `Fast on single shots, resets between turns. Memory doesn't persist into a compounding loop.`;
+  } else {
+    body =
+      `${name} sits low on both axes: ${plain(v, 2)}x generation, ${plain(l, 1)}x leverage. ` +
+      `A transient profile — neither building state nor converting input to output efficiently.`;
+  }
+  return `**${klass}.** ${body}`;
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "sigrank",
+  "version": "0.0.175",
+  "author": "SunrisesIllNeverSee (https://github.com/SunrisesIllNeverSee)",
+  "description": "SigRank MCP server — the yield cascade + live leaderboard as MCP tools any agent can call",
+  "mcpName": "io.github.SunrisesIllNeverSee/sigrank-mcp",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SunrisesIllNeverSee/sigrank-mcp.git"
+  },
+  "homepage": "https://signalaf.com",
+  "bugs": {
+    "url": "https://github.com/SunrisesIllNeverSee/sigrank-mcp/issues"
+  },
+  "bin": {
+    "sigrank": "index.mjs",
+    "sigrank-mcp": "index.mjs"
+  },
+  "main": "index.mjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.mjs",
+    "test": "node test.mjs && node sign.test.mjs && node --test __tests__/cascade.test.mjs __tests__/badges.test.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "cli.mjs",
+    "tui.mjs",
+    "tools.mjs",
+    "cascade.mjs",
+    "narrate.mjs",
+    "tokenpull.mjs",
+    "adapters.mjs",
+    "sign.mjs",
+    "keystore.mjs",
+    "submit.mjs",
+    "connect.mjs",
+    "badges.mjs",
+    "preflight.mjs",
+    "banner.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "claude",
+    "anthropic",
+    "llm",
+    "token-telemetry",
+    "token-usage",
+    "leaderboard",
+    "cli",
+    "tui",
+    "yield-cascade",
+    "sigrank",
+    "agent-tools",
+    "on-device"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@zhangferry-dev/tokendash": "^1.7.5",
+    "ccusage": "^20.0.14",
+    "tokscale": "^4.0.4"
+  }
+}

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

@@ -0,0 +1,106 @@
+// sign.mjs — canonical JSON + ed25519 signing for SigRank signed snapshot submit.
+//
+// BYTE-COMPATIBLE PORT of sigrank-app lib/ingest/signature.ts. This is the highest-
+// risk file in the client: the server VERIFIES the signature over ITS recomputation
+// of these exact canonical bytes, so a single divergent byte hard-rejects (422) every
+// verified submission. Keep this a line-for-line mirror of the server canonicalizer:
+//   canonical JSON = recursively sorted keys, compact separators, UTF-8, with the
+//   derived agent.signature + agent.snapshot_hash stripped before serialization.
+//   snapshot_hash = "sha256:" + hex(sha256(canonical_bytes)).
+//   public key    = "ed25519:<base64 of the 32 raw verify-key bytes>".
+//   signature     = base64 of the 64-byte ed25519 signature over canonical_bytes.
+// 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";
+
+/** Agent fields excluded from the canonical (signed/hashed) body — they derive from it. */
+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;
+  }
+  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];
+  }
+  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");
+}
+
+/** "sha256:<hex>" over the canonical bytes (matches the server snapshotHash). */
+export function snapshotHash(payload) {
+  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");
+
+/** 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",
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Sign the payload's canonical bytes with the PKCS8-DER-base64 private key → base64 sig.
+ * 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");
+}
+
+/**
+ * Local verify (parity with the server's verifySignature) — used by the self-test
+ * 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;
+  try {
+    return edVerify(
+      null,
+      canonicalBytes(payload),
+      key,
+      Buffer.from(signatureB64, "base64"),
+    );
+  } catch {
+    return false;
+  }
+}