sigrank 0.0.178 → 0.0.179

package/prompts/check-my-efficiency.md

@@ -0,0 +1 @@
+Pull my local token usage with tokenpull, compute my yield, and then fetch the leaderboard so I can see where I rank. Show me my class tier and my key metrics (Yield, Leverage, Velocity).

package/prompts/compare-with-leader.md

@@ -0,0 +1 @@
+Fetch the SigRank leaderboard with get_leaderboard, then pull my local token usage with tokenpull. Compare my yield, leverage, and velocity against the top operator. What's the gap and what would I need to change to close it?

package/prompts/simulate-improvement.md

@@ -0,0 +1 @@
+First pull my local token usage with tokenpull to get my current pillars. Then use simulate_change to answer: "what if I {{change}}?" Show me the yield delta and whether my class tier would change.

package/resources/class-tiers.md

@@ -0,0 +1,23 @@
+# SigRank Class Tiers
+
+Every operator is classified into one of three tiers based on their Yield (Υ = Cache Reads × Output / Input²).
+
+## Burner (Υ < 1.0)
+- **Profile:** Raw volume operators. High input tokens, low cache reuse.
+- **Behavior:** Brute-force — lots of context fed in, relatively little output back.
+- **Typical:** New AI users, verbose prompters, no session continuity.
+- **Fix:** Build cache across sessions. Stop re-explaining context. Use --continue.
+
+## Builder (1.0 ≤ Υ < 10.0)
+- **Profile:** Balanced operators. Moderate cache, decent output efficiency.
+- **Behavior:** Productive — reasonable input-to-output ratio, some cache leverage.
+- **Typical:** Experienced AI coders who use CLAUDE.md, project context, and session continuity.
+- **Fix:** Increase cache reads by reusing sessions. Reduce input by trimming unnecessary context.
+
+## 10xer (Υ ≥ 10.0)
+- **Profile:** Cascade-optimized operators. High cache reads, minimal input, efficient output.
+- **Behavior:** Surgical — minimal new input, maximum cache reuse, high-yield output.
+- **Typical:** Power users with long-running sessions, tight context windows, and aggressive cache strategies.
+- **Maintain:** Keep cache hit rate high. Avoid context bloat. Monitor with watch_tokenpull.
+
+Tiers are recalculated on every submission. Your tier can change between windows (7d, 30d, 90d, all-time).

package/resources/data-policy.md

@@ -0,0 +1,27 @@
+# SigRank Data Policy
+
+SigRank is a public AI-operator leaderboard. This policy summarizes what data we collect, how we use it, and how you can delete it.
+
+## What we collect
+
+- **Token telemetry** from your local agent: token counts, content lengths, model identifiers, and platform/source tags. We use these to compute your score on the leaderboard.
+- **Account identifiers** when you sign in (email from your OAuth provider) so we can link your operator profile to your login.
+- **Optional profile fields** you choose to add: display name, handle, bio, location, links, avatar.
+
+## What we never collect
+
+We do **not** read or transmit the content of your prompts or AI conversations. The local agent extracts only numeric token counts and metadata; transcripts never leave your device.
+
+## Consent
+
+Before you connect a device, you must agree to the current Terms of Service and Privacy Policy. We record the timestamp and version of your consent.
+
+## Your choices
+
+- **Pause data collection** at any time from [signalaf.com/settings](https://signalaf.com/settings). While paused, your agent submissions are rejected and no new telemetry is stored.
+- **Delete your data** from Settings to erase all snapshots, scored metrics, ranks, devices, and enrollment codes while keeping your account and profile.
+- **Delete your account** from Settings to fully sever your identity. This runs Delete your data first, then anonymizes your board row (kept as aggregate history), removes your login, and cancels billing.
+
+## Contact
+
+Questions: hello@signalaf.com

package/resources/install-guide.md

@@ -0,0 +1,59 @@
+# SigRank Quick Start
+
+## Install
+
+```bash
+npx sigrank
+```
+
+No global install needed. The MCP server starts automatically when an AI client (Claude, Cursor, Cline) connects.
+
+## First Submission
+
+1. **Enroll** — register your operator codename:
+   ```bash
+   npx sigrank enroll
+   ```
+
+2. **Pull + Submit** — scan your local AI session logs and publish:
+   ```bash
+   npx sigrank submit
+   ```
+
+3. **Dry Run** — see exactly what would be sent before publishing:
+   ```bash
+   npx sigrank submit --dry-run
+   ```
+
+## Token Pull Sources
+
+SigRank bundles two token readers as npm dependencies:
+- **ccusage** — Claude Code session logs
+- **tokscale** — multi-platform token telemetry
+
+A third source, **token-dashboard**, is read from `~/.claude/token-dashboard.db` (SQLite).
+That DB is created by [Nate's token-dashboard](https://github.com/nateherkai/token-dashboard) (Python):
+```bash
+git clone https://github.com/nateherkai/token-dashboard.git
+cd token-dashboard
+python3 cli.py dashboard
+```
+Run the scan once to create the DB; SigRank reads it directly via sqlite3 after that.
+
+## MCP Client Setup
+
+Add to your MCP client config:
+```json
+{
+  "mcpServers": {
+    "sigrank": {
+      "command": "npx",
+      "args": ["sigrank"]
+    }
+  }
+}
+```
+
+## Live Board
+
+Visit https://signalaf.com to see the global leaderboard.

package/resources/privacy-model.md

@@ -0,0 +1,30 @@
+# SigRank Privacy Model
+
+## What leaves your machine
+
+**Only four numbers per submission:**
+- Input tokens
+- Output tokens
+- Cache create tokens
+- Cache read tokens
+
+**That's it.** No prompts, no code, no file contents, no conversation text.
+
+## How it works
+
+1. **Local-first:** All token pulling happens on your machine. SigRank reads session logs from ~/.claude, ~/.codex, ~/.local/share/amp, etc.
+2. **Token counts only:** The MCP tools extract integer counts from log metadata. The actual content of your conversations is never read, parsed, or transmitted.
+3. **Signed submission:** Submissions are ed25519-signed. The board verifies authenticity without seeing your data.
+4. **No auth required:** No API keys, no OAuth, no account needed to read the leaderboard. Enrollment only requires a codename.
+
+## What SigRank 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)
+
+## 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,28 @@
+# 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 Tier Thresholds
+
+| Tier | Yield Range | Profile |
+|------|-------------|---------|
+| **Burner** | Υ < 1.0 | Raw volume — high input, low cache reuse, brute-force output |
+| **Builder** | 1.0 ≤ Υ < 10.0 | Balanced — moderate cache, decent output efficiency |
+| **10xer** | Υ ≥ 10.0 | Cascade-optimized — high cache reads, minimal input, efficient output |
+
+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';