sigrank 0.19.0 → 1.0.1

package/resources/privacy-model.md

@@ -0,0 +1,44 @@
+# SigRank Privacy Model
+
+## What leaves your machine
+
+**Every submission path sends only four numbers:**
+- Input tokens
+- Output tokens
+- Cache create tokens
+- Cache read tokens
+
+That's the entire payload — no prompts, no code, no file contents, no conversation text. The MCP parses your input locally and sends only the four token counts to the server, which re-parses and re-scores them authoritatively.
+
+The optional `sigrank proxy` is a local transport path to Anthropic/OpenAI, not a
+submission path to SigRank. When explicitly enabled, it necessarily receives and
+forwards provider-bound API keys, prompts, tool calls, and responses in memory.
+It does not persist that content or send it to the SigRank service; it appends
+only provider-reported token counts, model/backend metadata, and timestamps to
+`~/.sigrank-mcp/proxy-sessions.jsonl`.
+
+- **Signed path** (`submit_verified`, `watch_tokenpull` with `submit:true`): the four numbers travel with the device's public key, codename, window, and an ed25519 signature. The board verifies the signature without seeing your data.
+- **Paste path** (`submit_paste`, `tokenpull_submit`): the MCP parses your pasted token counts locally, then sends only the four canonical numbers to the server's web-paste endpoint. Even if you paste mixed text (prose + numbers), only the extracted token counts are transmitted — the raw text never leaves your machine.
+
+## How it works
+
+1. **Local-first:** All token pulling happens on your machine. SigRank reads session logs from ~/.claude, ~/.codex, ~/.local/share/amp, etc. The optional proxy also runs only on loopback and only when manually started.
+2. **Token-only persistence:** Local-log adapters extract integer counts from log metadata without reading conversation content. The optional proxy forwards request/response bytes transiently but persists only usage metadata. On the paste path, the MCP parses the paste locally and sends only the four extracted numbers — the raw paste text stays on your machine.
+3. **Signed submission:** Ranked submissions (`submit_verified`, `watch_tokenpull` with `submit:true`) are ed25519-signed with a device-bound key generated locally at enrollment. The board verifies the signature without seeing your data. Paste submissions (`submit_paste`, `tokenpull_submit`) are unsigned and go through the web-paste endpoint with a codename only — but still send only the four token counts, not the raw paste.
+4. **Read tools need no auth:** No API keys, no OAuth, no account needed to read the leaderboard or operator profiles. **Enrollment requires a connect code** from signalaf.com → Settings → New key (the code binds your device's public key to your operator server-side); a codename alone is not enough for the signed/ranked path.
+
+## What the SigRank service can NOT see
+
+- Your prompts or messages
+- Your code or file contents
+- Your tool calls or their results
+- Which AI platform you use (beyond token counts)
+- Your identity (only your chosen codename)
+
+The local proxy process is different from the SigRank service: if you opt in, it
+handles your provider traffic in memory solely to forward it to Anthropic or
+OpenAI. That content is never stored in the proxy JSONL file.
+
+## Verification
+
+The submit_verified tool uses ed25519 signing. The board's source_attestations table records the signature for audit. You can verify your own submissions via get_operator.

package/resources/scoring-formula.md

@@ -0,0 +1,24 @@
+# SigRank Scoring Formula
+
+## Yield (Υ) — the headline metric
+
+```
+Υ = Cache Reads × Output / Input²
+```
+
+Yield rewards operators who maximize output while minimizing input — and who build cache to amortize that input across sessions. A high yield means you're getting more done with less, efficiently.
+
+## Derived Metrics
+
+| Metric | Formula | Meaning |
+|--------|---------|---------|
+| **SNR** | Output / (Input + CacheCreate) | Signal-to-noise: how much of your token spend is productive output vs. overhead |
+| **Leverage** | Cache Reads / Input | How well you reuse cached context — higher = better cache utilization |
+| **Velocity** | Output / Input | Raw output efficiency — how much output you generate per token of input |
+| **10xDEV** | Composite score | Weighted blend of yield, leverage, and velocity for cross-platform comparison |
+
+## Class Tiers
+
+Class tiers are based on **total tokens accumulated**, not yield ranges. The 8-tier experience ladder (descending: ARCH+, ARCH, POWER, BASE, SEEKER, REFINER, BEARER, IGNITER) measures operator progression. TRANSMITTER is a separate peak badge (K.00), not a ladder tier. See `class-tiers.md` for the full ladder and thresholds.
+
+The formula is deterministic and computed locally. No network calls needed for scoring.

package/review.mjs

@@ -0,0 +1,263 @@
+/**
+ * review.mjs — `sigrank review` subcommand.
+ *
+ * Runs an operator's numbers through all three reference operating ratios
+ * (AA avg, HCM, Codex PU) and validates results to identify correct placement.
+ *
+ * Usage:
+ *   npx sigrank review <handle>                    # pull from raw data (if available)
+ *   npx sigrank review --output N --cache-read N --combined-input N
+ *
+ * The cache_write convergence test:
+ *   When we split combined_input into input + cache_write using each ratio's
+ *   velocity, the cache_write values should converge. If one ratio produces
+ *   a cache_write far below the others, that ratio is broken for this operator.
+ *
+ * Transcribed by Devin from owner (djm) analysis and direction.
+ */
+
+import { cascade, classify, round } from "./cascade.mjs";
+
+// Reference operating ratios (cache_read : input : output, input=1)
+const RATIOS = {
+  "AA avg": {
+    cache: 3.5,
+    velocity: 0.5,
+    label: "3.5:1:0.5",
+    description: "all-users average",
+  },
+  HCM: {
+    cache: 20,
+    velocity: 0.1,
+    label: "20:1:0.1",
+    description: "human center of mass",
+  },
+  "Codex PU": {
+    cache: 243,
+    velocity: 1.03,
+    label: "243:1:1.03",
+    description: "Codex power-user",
+  },
+};
+
+function fmtTokens(n) {
+  if (n >= 1e12) return `${(n / 1e12).toFixed(2)}T`;
+  if (n >= 1e9) return `${(n / 1e9).toFixed(2)}B`;
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return String(n);
+}
+
+function runRatios(output, cacheRead, combinedInput) {
+  const results = {};
+
+  for (const [name, r] of Object.entries(RATIOS)) {
+    const v = r.velocity;
+    const cRef = r.cache;
+
+    const inputEst = Math.round(output / v);
+    const cacheWriteEst = combinedInput - inputEst;
+
+    const leverage = cacheRead / inputEst;
+    const velocity = v;
+    const yieldVal = leverage * velocity;
+
+    results[name] = {
+      label: r.label,
+      description: r.description,
+      refCache: cRef,
+      refVelocity: v,
+      input: inputEst,
+      output,
+      cacheWrite: cacheWriteEst,
+      cacheRead,
+      leverage,
+      velocity,
+      yield: yieldVal,
+      levMatch: leverage / cRef,
+      cwValid: cacheWriteEst > 0,
+    };
+  }
+
+  // Convergence test
+  const cwValues = Object.values(results)
+    .filter((r) => r.cwValid)
+    .map((r) => r.cacheWrite);
+
+  for (const [name, r] of Object.entries(results)) {
+    if (!r.cwValid) {
+      r.cwStatus = "INVALID (negative)";
+      r.cwConverges = false;
+      continue;
+    }
+    const others = Object.entries(results)
+      .filter(([n]) => n !== name && results[n].cwValid)
+      .map(([, v]) => v.cacheWrite);
+    if (others.length > 0) {
+      const otherMedian = [...others].sort((a, b) => a - b)[
+        Math.floor(others.length / 2)
+      ];
+      if (r.cacheWrite < otherMedian * 0.5) {
+        r.cwStatus = `OUTLIER (cache_write ${fmtTokens(r.cacheWrite)} is >50% below peers)`;
+        r.cwConverges = false;
+      } else if (r.cacheWrite < otherMedian * 0.7) {
+        r.cwStatus = `LOW (cache_write ${fmtTokens(r.cacheWrite)} is below peers)`;
+        r.cwConverges = false;
+      } else {
+        r.cwStatus = "VALID (converges with peers)";
+        r.cwConverges = true;
+      }
+    } else {
+      r.cwStatus = "VALID";
+      r.cwConverges = true;
+    }
+  }
+
+  return results;
+}
+
+function classifyYield(y) {
+  if (y >= 100) return "POWER";
+  if (y >= 10) return "SEEKER";
+  if (y >= 1) return "IGNITER";
+  if (y > 0) return "BURNER";
+  return "BASE";
+}
+
+// ANSI colors
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+
+export async function runReview(opts) {
+  const { handle, output, cacheRead, combinedInput } = opts;
+
+  if (!output || !cacheRead || !combinedInput) {
+    console.error(
+      red(
+        "\n  Missing required values. Usage:\n" +
+          "    npx sigrank review --output N --cache-read N --combined-input N\n",
+      ),
+    );
+    process.exit(1);
+  }
+
+  const results = runRatios(output, cacheRead, combinedInput);
+
+  console.log();
+  console.log(`  ${"=".repeat(80)}`);
+  console.log(`  RATIO REVIEW${handle ? `: ${handle}` : " (custom)"}`);
+  console.log(`  ${"=".repeat(80)}`);
+  console.log();
+
+  // Real telemetry
+  console.log(`  ${bold("REAL TELEMETRY (constants):")}`);
+  console.log(`    Output:          ${output.toLocaleString()}  (${fmtTokens(output)})`);
+  console.log(`    Cache read:      ${cacheRead.toLocaleString()}  (${fmtTokens(cacheRead)})`);
+  console.log(`    Combined input:  ${combinedInput.toLocaleString()}  (${fmtTokens(combinedInput)})`);
+  console.log();
+  console.log(`  ${bold("REFERENCE RATIOS (cache_read : input : output, input=1):")}`);
+  for (const [name, r] of Object.entries(RATIOS)) {
+    console.log(`    ${name.padEnd(10)}  ${r.label.padEnd(12)}  (${r.description})`);
+  }
+  console.log();
+
+  // Side-by-side table
+  const names = ["AA avg", "HCM", "Codex PU"];
+  const headerRow = `  ${"".padEnd(14)}  ${"AA avg".padStart(14)}  ${"HCM".padStart(14)}  ${"Codex PU".padStart(14)}`;
+  const subHeaderRow = `  ${"".padEnd(14)}  ${"3.5:1:0.5".padStart(14)}  ${"20:1:0.1".padStart(14)}  ${"243:1:1.03".padStart(14)}`;
+  const divider = `  ${"-".repeat(14)}  ${"-".repeat(14)}  ${"-".repeat(14)}  ${"-".repeat(14)}`;
+
+  console.log(headerRow);
+  console.log(subHeaderRow);
+  console.log(divider);
+
+  const dataRows = [
+    ["Input", "input", "int"],
+    ["Output", "output", "int"],
+    ["Cache write", "cacheWrite", "int"],
+    ["Cache read", "cacheRead", "int"],
+    ["Velocity", "velocity", "float"],
+    ["Leverage", "leverage", "lev"],
+    ["Yield", "yield", "float"],
+  ];
+
+  for (const [label, key, type] of dataRows) {
+    const vals = names.map((n) => {
+      const v = results[n][key];
+      if (type === "float") return v.toFixed(2).padStart(14);
+      if (type === "lev") return `${v.toFixed(1)}:1`.padStart(14);
+      return v.toLocaleString().padStart(14);
+    });
+    console.log(`  ${label.padEnd(14)}  ${vals[0]}  ${vals[1]}  ${vals[2]}`);
+  }
+
+  console.log(divider);
+  const classes = names.map((n) => classifyYield(results[n].yield).padStart(14));
+  console.log(`  ${"Class".padEnd(14)}  ${classes[0]}  ${classes[1]}  ${classes[2]}`);
+  console.log();
+
+  // Cache write validation
+  console.log(`  ${bold("CACHE WRITE VALIDATION:")}`);
+  console.log();
+  for (const name of names) {
+    const r = results[name];
+    const marker = r.cwConverges ? green("PASS") : red("FAIL");
+    console.log(`    ${name.padEnd(10)}  cache_write = ${fmtTokens(r.cacheWrite).padStart(10)}  [${marker}] ${r.cwStatus}`);
+  }
+  console.log();
+
+  // Leverage match
+  console.log(`  ${bold("LEVERAGE MATCH (actual cache_read/input vs reference cache term):")}`);
+  console.log();
+  for (const name of names) {
+    const r = results[name];
+    let matchStatus;
+    if (r.levMatch < 0.5) matchStatus = "POOR (ratio does not fit this operator)";
+    else if (r.levMatch < 0.8 || r.levMatch > 2.0) matchStatus = "WEAK (leverage far from reference)";
+    else if (r.levMatch >= 0.8 && r.levMatch <= 1.3) matchStatus = "STRONG (leverage matches reference)";
+    else matchStatus = "MODERATE";
+    console.log(
+      `    ${name.padEnd(10)}  actual ${r.leverage.toFixed(1)}:1  vs  ref ${r.refCache.toFixed(1)}:1  =  ${r.levMatch.toFixed(2)}x  [${matchStatus}]`,
+    );
+  }
+  console.log();
+
+  // Recommendation
+  const valid = Object.entries(results).filter(([, r]) => r.cwConverges);
+  const validNames = valid.map(([n]) => n);
+
+  console.log(`  ${bold("RECOMMENDATION:")}`);
+  console.log();
+
+  if (valid.length === 0) {
+    console.log(`    ${red("No ratio passes cache_write validation. Manual review needed.")}`);
+  } else if (valid.length === 1) {
+    const [name, r] = valid[0];
+    console.log(`    ${green(name)} (${r.label}) is the only ratio that passes cache_write validation.`);
+    console.log(`    Yield: ${r.yield.toFixed(2)}    Class: ${classifyYield(r.yield)}`);
+  } else {
+    const eliminated = names.filter((n) => !validNames.includes(n));
+    if (eliminated.length > 0) {
+      console.log(`    ${dim("Eliminated:")} ${eliminated.join(", ")} (cache_write outlier)`);
+    }
+    console.log(`    ${dim("Candidates:")} ${validNames.join(", ")}`);
+    console.log();
+
+    // Best leverage match
+    const [bestName, best] = valid.reduce((best, cur) =>
+      Math.abs(cur[1].levMatch - 1.0) < Math.abs(best[1].levMatch - 1.0) ? cur : best
+    );
+
+    console.log(`    ${green("Best fit:")} ${bestName} (${best.label})`);
+    console.log(`      Leverage match: ${best.levMatch.toFixed(2)}x (actual ${best.leverage.toFixed(1)}:1 vs ref ${best.refCache.toFixed(1)}:1)`);
+    console.log(`      Yield: ${best.yield.toFixed(2)}    Class: ${classifyYield(best.yield)}`);
+  }
+
+  console.log();
+  console.log(`  Run ${cyan("`npx sigrank`")} to get a real signed snapshot with proper cache_write.`);
+  console.log();
+}

package/sign.mjs

@@ -1,106 +1 @@
-// 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;
-  }
-}
+export * from './identity/sign.mjs';