sigrank 1.0.3 → 1.0.5

package/bin/sigrank.mjs

@@ -69,9 +69,13 @@ async function exportStandardRecord() {
   const platform = flag("platform", "claude");
   const window = flag("window", "30d");
 
-  const explicit = ["input", "output", "cache-write", "cache-read"].every(
-    (name) => flag(name) !== undefined,
-  );
+  const explicitFlags = ["input", "output", "cache-write", "cache-read"];
+  const hasExplicit = explicitFlags.some((name) => flag(name) !== undefined);
+  const explicit = ["input", "output"].every((name) => flag(name) !== undefined);
+
+  if (hasExplicit && !explicit) {
+    throw new Error("Explicit Standard export requires both --input and --output.");
+  }
 
   let pillars;
   let sourcePlatform = platform;
@@ -80,8 +84,8 @@ async function exportStandardRecord() {
     pillars = {
       input: Number(flag("input")),
       output: Number(flag("output")),
-      cache_write: Number(flag("cache-write")),
-      cache_read: Number(flag("cache-read")),
+      cache_write: flag("cache-write") === undefined ? null : Number(flag("cache-write")),
+      cache_read: flag("cache-read") === undefined ? null : Number(flag("cache-read")),
     };
   } else {
     const pulled = await callTool("tokenpull", { platform });
@@ -97,14 +101,14 @@ async function exportStandardRecord() {
     pillars = {
       input: selected.pillars.input,
       output: selected.pillars.output,
-      cache_write: selected.pillars.cacheCreate,
-      cache_read: selected.pillars.cacheRead,
+      cache_write: selected.pillars.cacheCreate ?? null,
+      cache_read: selected.pillars.cacheRead ?? null,
     };
   }
 
   for (const [key, value] of Object.entries(pillars)) {
-    if (!Number.isFinite(value) || value < 0) {
-      throw new Error(`${key} must be a non-negative finite number.`);
+    if (value !== null && (!Number.isFinite(value) || !Number.isInteger(value) || value < 0)) {
+      throw new Error(`${key} must be a non-negative integer token count or null.`);
     }
   }
 

package/manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
   "manifest_version": "0.4",
   "name": "sigrank",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Ranks AI coding operators by token cascade efficiency (Yield = cache_read \u00d7 output / input\u00b2). 25 tools including SigRank Standard record, yield calculation, local token usage pulls, signed submission, and tokscale-powered analytics (market share, developer profiles, model trends, cost analysis, device profiles, MCP usage, competitive intelligence). Privacy-first: runs locally, only four token counts leave the machine.",
   "author": {
     "name": "SunrisesIllNeverSee",

package/omp-cache.mjs

@@ -0,0 +1,477 @@
+/**
+ * omp-cache.mjs — Privacy-safe incremental SQLite cache for omp session scans.
+ *
+ * Stage 2 of the OMP Loading Optimization Plan. Wraps the Stage 1 bounded-concurrency
+ * scanner with a persistent index at ~/.sigrank-mcp/omp-index.sqlite that stores:
+ *   - File fingerprints (path, size, mtime_ms)
+ *   - Usage events (session_id, message_id, timestamp, 4 token pillars)
+ *   - No transcript text, ever.
+ *
+ * On a warm run with no changed files, the cache avoids all transcript reads and
+ * serves usage records directly from SQLite — turning a ~35s scan into a metadata
+ * walk + indexed aggregation.
+ *
+ * Activation:
+ *   SIGRANK_OMP_CACHE=1      — use cache, fall back to uncached on error
+ *   SIGRANK_OMP_CACHE=parity — use cache AND run uncached scan, fail on drift
+ *   (unset)                  — uncached (Stage 1 behavior, the default)
+ *
+ * SQLite access: shells out to the `sqlite3` CLI (same as the devin adapter).
+ * No native npm dependency. Works on Node 18+ (the project's minimum).
+ *
+ * Concurrency: SQLite WAL mode + busy timeout. If the write lock can't be
+ * obtained, falls back to uncached scan without damaging the cache.
+ */
+
+import { execFile as execFileCb } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdir, stat, unlink } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+const execFileP = promisify(execFileCb);
+
+const CACHE_SCHEMA_VERSION = "1";
+const CACHE_PARSER_VERSION = "omp-stage1-v1";
+const BUSY_TIMEOUT_MS = 5_000;
+const SQLITE_MAX_BUFFER = 256 * 1024 * 1024; // 256MB
+
+/** Default cache location. */
+export function defaultCachePath() {
+  return join(homedir(), ".sigrank-mcp", "omp-index.sqlite");
+}
+
+/** Run a SQLite command, return parsed JSON rows or [] on error. */
+async function sqliteJson(dbPath, sql, timeoutMs = 10_000) {
+  try {
+    const { stdout } = await execFileP("sqlite3", ["-json", dbPath, sql], {
+      timeout: timeoutMs,
+      maxBuffer: SQLITE_MAX_BUFFER,
+    });
+    return JSON.parse(stdout || "[]");
+  } catch {
+    return [];
+  }
+}
+
+/** Run a SQLite command that doesn't return rows (DDL/DML). Returns success boolean. */
+async function sqliteExec(dbPath, sql, timeoutMs = 30_000) {
+  try {
+    await execFileP("sqlite3", [dbPath, sql], {
+      timeout: timeoutMs,
+      maxBuffer: SQLITE_MAX_BUFFER,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run multiple SQL statements in a single sqlite3 call (semicolon-separated). */
+async function sqliteExecBatch(dbPath, sql, timeoutMs = 60_000) {
+  return sqliteExec(dbPath, sql, timeoutMs);
+}
+
+/** Check if the cache database exists and has a compatible schema. */
+async function cacheIsHealthy(dbPath) {
+  const rows = await sqliteJson(
+    dbPath,
+    `SELECT key, value FROM metadata WHERE key IN ('schema_version','parser_version');`,
+    2_000,
+  );
+  if (!rows || rows.length < 2) return false;
+  const meta = Object.fromEntries(rows.map((r) => [r.key, r.value]));
+  return (
+    meta.schema_version === CACHE_SCHEMA_VERSION &&
+    meta.parser_version === CACHE_PARSER_VERSION
+  );
+}
+
+/** Initialize the cache database with the schema. */
+async function initCacheDb(dbPath) {
+  // Ensure the directory exists with 0700 permissions
+  await mkdir(dirname(dbPath), { recursive: true, mode: 0o700 });
+
+  const sql = `
+    PRAGMA journal_mode=WAL;
+    PRAGMA busy_timeout=${BUSY_TIMEOUT_MS};
+    PRAGMA synchronous=NORMAL;
+
+    CREATE TABLE IF NOT EXISTS metadata (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS roots (
+      root TEXT PRIMARY KEY,
+      last_seen_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS files (
+      path TEXT PRIMARY KEY,
+      root TEXT NOT NULL,
+      size INTEGER NOT NULL,
+      mtime_ms INTEGER NOT NULL,
+      scanned_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS usage_events (
+      file_path TEXT NOT NULL,
+      session_id TEXT,
+      message_id TEXT,
+      event_ts TEXT,
+      input INTEGER NOT NULL,
+      output INTEGER NOT NULL,
+      cache_create INTEGER NOT NULL,
+      cache_read INTEGER NOT NULL,
+      ordinal INTEGER NOT NULL,
+      PRIMARY KEY (file_path, ordinal)
+    );
+
+    CREATE INDEX IF NOT EXISTS usage_events_dedup
+      ON usage_events(session_id, message_id);
+
+    CREATE INDEX IF NOT EXISTS usage_events_timestamp
+      ON usage_events(event_ts);
+
+    DELETE FROM metadata WHERE key IN ('schema_version', 'parser_version');
+    INSERT INTO metadata VALUES ('schema_version', '${CACHE_SCHEMA_VERSION}');
+    INSERT INTO metadata VALUES ('parser_version', '${CACHE_PARSER_VERSION}');
+  `;
+  return sqliteExecBatch(dbPath, sql);
+}
+
+/** Delete the cache file (corruption recovery). */
+async function deleteCache(dbPath) {
+  try {
+    await unlink(dbPath);
+  } catch {
+    // already gone
+  }
+  // Also clean up WAL and SHM files
+  for (const suffix of ["-wal", "-shm"]) {
+    try {
+      await unlink(dbPath + suffix);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+/** Collect file metadata (path, size, mtime_ms) for all jsonl files under a root. */
+async function collectFileMeta(rootDir, walkFiles, isJsonl, maxFiles) {
+  const metas = [];
+  for await (const path of walkFiles(rootDir, isJsonl, { n: 0 }, maxFiles)) {
+    try {
+      const st = await stat(path);
+      metas.push({
+        path,
+        root: rootDir,
+        size: st.size,
+        mtime_ms: Math.floor(st.mtimeMs),
+      });
+    } catch {
+      // file vanished between walk and stat — skip
+    }
+  }
+  return metas;
+}
+
+/** Get cached file fingerprints from the database. */
+async function getCachedFiles(dbPath, rootDir) {
+  return sqliteJson(
+    dbPath,
+    `SELECT path, root, size, mtime_ms FROM files WHERE root = '${rootDir.replace(/'/g, "''")}';`,
+    5_000,
+  );
+}
+
+/** Compare current file metadata against cached fingerprints.
+ *  Returns { newFiles, changedFiles, deletedFiles, unchangedFiles }. */
+function diffFiles(currentMetas, cachedRows) {
+  const cachedMap = new Map(cachedRows.map((r) => [r.path, r]));
+  const currentPaths = new Set(currentMetas.map((m) => m.path));
+
+  const newFiles = [];
+  const changedFiles = [];
+  const unchangedFiles = [];
+
+  for (const m of currentMetas) {
+    const cached = cachedMap.get(m.path);
+    if (!cached) {
+      newFiles.push(m);
+    } else if (cached.size !== m.size || cached.mtime_ms !== m.mtime_ms) {
+      changedFiles.push(m);
+    } else {
+      unchangedFiles.push(m);
+    }
+  }
+
+  const deletedFiles = cachedRows
+    .filter((r) => !currentPaths.has(r.path))
+    .map((r) => r.path);
+
+  return { newFiles, changedFiles, unchangedFiles, deletedFiles };
+}
+
+/** Escape a string for SQL single-quoted context. */
+function sqlEscape(s) {
+  return String(s ?? "").replace(/'/g, "''");
+}
+
+/** Format a value for SQL (null for null/undefined, quoted string otherwise). */
+function sqlVal(v) {
+  if (v == null) return "NULL";
+  return `'${sqlEscape(v)}'`;
+}
+
+/** Update the cache for a set of files: parse them, insert usage events.
+ *  Uses the Stage 1 parseOmpFile function passed in. */
+async function updateFilesInCache(dbPath, fileMetas, parseOmpFile, readUtf8) {
+  for (const meta of fileMetas) {
+    const text = await readUtf8(meta.path);
+    const records = [...parseOmpFile(text, meta.path)];
+
+    if (process.env.SIGRANK_OMP_DEBUG) {
+      console.error(`[omp-cache] updating ${meta.path}: ${records.length} records, size=${meta.size}, mtime=${meta.mtime_ms}`);
+    }
+
+    // Build SQL: delete old rows for this file, insert new ones, update fingerprint
+    let sql = `
+      BEGIN TRANSACTION;
+      DELETE FROM usage_events WHERE file_path = '${sqlEscape(meta.path)}';
+      DELETE FROM files WHERE path = '${sqlEscape(meta.path)}';
+    `;
+
+    if (records.length > 0) {
+      const values = records
+        .map((r, i) => {
+          return `('${sqlEscape(meta.path)}', ${sqlVal(r.sid)}, ${sqlVal(r.id)}, ${sqlVal(r.ts)}, ${r.input}, ${r.output}, ${r.cacheCreate}, ${r.cacheRead}, ${i})`;
+        })
+        .join(",\n");
+      sql += `INSERT INTO usage_events (file_path, session_id, message_id, event_ts, input, output, cache_create, cache_read, ordinal) VALUES ${values};\n`;
+    }
+
+    sql += `INSERT INTO files (path, root, size, mtime_ms, scanned_at) VALUES ('${sqlEscape(meta.path)}', '${sqlEscape(meta.root)}', ${meta.size}, ${meta.mtime_ms}, ${Date.now()});\n`;
+    sql += `COMMIT;`;
+
+    const ok = await sqliteExecBatch(dbPath, sql, 10_000);
+    if (!ok && process.env.SIGRANK_OMP_DEBUG) {
+      console.error(`[omp-cache] SQL FAILED for ${meta.path}`);
+      console.error(`[omp-cache] SQL: ${sql.substring(0, 300)}`);
+    }
+  }
+}
+
+/** Remove cached data for deleted files. */
+async function removeDeletedFiles(dbPath, deletedPaths) {
+  if (deletedPaths.length === 0) return;
+  const pathList = deletedPaths.map((p) => `'${sqlEscape(p)}'`).join(",");
+  await sqliteExecBatch(
+    dbPath,
+    `
+    BEGIN TRANSACTION;
+    DELETE FROM usage_events WHERE file_path IN (${pathList});
+    DELETE FROM files WHERE path IN (${pathList});
+    COMMIT;
+    `,
+    10_000,
+  );
+}
+
+/** Update the roots table to mark this root as seen. */
+async function touchRoot(dbPath, rootDir) {
+  await sqliteExecBatch(
+    dbPath,
+    `INSERT OR REPLACE INTO roots (root, last_seen_at) VALUES ('${sqlEscape(rootDir)}', ${Date.now()});`,
+    2_000,
+  );
+}
+
+/** Read all usage events from the cache as records (same shape as ompAdapter.messages). */
+async function* readCachedRecords(dbPath) {
+  const rows = await sqliteJson(
+    dbPath,
+    `SELECT file_path, session_id, message_id, event_ts, input, output, cache_create, cache_read
+     FROM usage_events ORDER BY file_path, ordinal;`,
+    30_000,
+  );
+
+  for (const row of rows) {
+    yield {
+      id: row.message_id || null,
+      sid: row.session_id || null,
+      ts: row.event_ts || null,
+      input: row.input,
+      output: row.output,
+      cacheCreate: row.cache_create,
+      cacheRead: row.cache_read,
+      file: row.file_path,
+    };
+  }
+}
+
+/**
+ * Run a cached omp scan. If the cache is healthy, does an incremental update
+ * (only reparse new/changed files) and yields records from the cache.
+ * Falls back to uncached scan on any error.
+ *
+ * @param {string} rootDir - the omp sessions directory
+ * @param {Function} uncachedScan - async generator that yields records (Stage 1)
+ * @param {Function} parseOmpFile - Stage 1 parser function
+ * @param {Function} readUtf8 - file reader
+ * @param {Function} walkFiles - file walker
+ * @param {Function} isJsonl - file predicate
+ * @param {number} maxFiles - file cap
+ * @param {string} cachePath - override cache db path (for tests)
+ * @returns {AsyncGenerator} - yields usage records
+ */
+export async function* cachedOmpScan({
+  rootDir,
+  uncachedScan,
+  parseOmpFile,
+  readUtf8,
+  walkFiles,
+  isJsonl,
+  maxFiles,
+  cachePath,
+}) {
+  const dbPath = cachePath || defaultCachePath();
+  const parity = process.env.SIGRANK_OMP_CACHE === "parity";
+
+  // Try to use the cache
+  let healthy = await cacheIsHealthy(dbPath);
+  if (process.env.SIGRANK_OMP_DEBUG) {
+    console.error(`[omp-cache] initial healthy=${healthy} db=${dbPath}`);
+  }
+  if (!healthy) {
+    // If the db file exists but is corrupt/incompatible, delete it first
+    // (initCacheDb can't write to a non-SQLite file)
+    try {
+      const st = await stat(dbPath);
+      if (st.isFile() && st.size > 0) {
+        if (process.env.SIGRANK_OMP_DEBUG) {
+          console.error(`[omp-cache] deleting existing file (size=${st.size})`);
+        }
+        await deleteCache(dbPath);
+      }
+    } catch {
+      // file doesn't exist — fine
+    }
+    // Try to initialize
+    const ok = await initCacheDb(dbPath);
+    if (process.env.SIGRANK_OMP_DEBUG) {
+      console.error(`[omp-cache] initCacheDb ok=${ok}`);
+    }
+    if (!ok) {
+      // Can't create cache — fall back to uncached
+      yield* uncachedScan();
+      return;
+    }
+    healthy = await cacheIsHealthy(dbPath);
+    if (process.env.SIGRANK_OMP_DEBUG) {
+      console.error(`[omp-cache] post-init healthy=${healthy}`);
+    }
+    if (!healthy) {
+      yield* uncachedScan();
+      return;
+    }
+  }
+
+  try {
+    // Collect current file metadata
+    const currentMetas = await collectFileMeta(rootDir, walkFiles, isJsonl, maxFiles);
+
+    // Get cached fingerprints
+    const cachedRows = await getCachedFiles(dbPath, rootDir);
+
+    // Diff
+    const { newFiles, changedFiles, unchangedFiles, deletedFiles } = diffFiles(
+      currentMetas,
+      cachedRows,
+    );
+
+    // Update cache for new and changed files
+    const toUpdate = [...newFiles, ...changedFiles];
+    if (toUpdate.length > 0) {
+      await updateFilesInCache(dbPath, toUpdate, parseOmpFile, readUtf8);
+    }
+
+    // Remove deleted files
+    if (deletedFiles.length > 0) {
+      await removeDeletedFiles(dbPath, deletedFiles);
+    }
+
+    // Mark root as seen
+    await touchRoot(dbPath, rootDir);
+
+    // Yield records from cache
+    yield* readCachedRecords(dbPath);
+
+    // Parity mode: also run uncached and compare
+    if (parity) {
+      const cachedRecords = [...readCachedRecords(dbPath)];
+      const uncachedRecords = [];
+      for await (const r of uncachedScan()) {
+        uncachedRecords.push(r);
+      }
+      // Compare totals (dedup happens downstream in tokenpull, so we compare
+      // the raw record sums — they should match since the cache stores all
+      // records from all files)
+      const sumFields = (records, field) =>
+        records.reduce((s, r) => s + (r[field] || 0), 0);
+
+      for (const field of ["input", "output", "cacheCreate", "cacheRead"]) {
+        const cachedSum = sumFields(cachedRecords, field);
+        const uncachedSum = sumFields(uncachedRecords, field);
+        if (cachedSum !== uncachedSum) {
+          console.error(
+            `[omp-cache] PARITY DRIFT: ${field} cached=${cachedSum} uncached=${uncachedSum} (diff=${cachedSum - uncachedSum})`,
+          );
+        }
+      }
+    }
+  } catch (err) {
+    // Any error during cache operations — fall back to uncached
+    // Don't delete the cache; it may be partially valid and recoverable
+    if (process.env.SIGRANK_OMP_DEBUG) {
+      console.error(`[omp-cache] fallback to uncached: ${err.message}`);
+    }
+    yield* uncachedScan();
+    return;
+  }
+}
+
+/** Check if the omp cache is enabled via environment variable. */
+export function ompCacheEnabled() {
+  const v = process.env.SIGRANK_OMP_CACHE;
+  return v === "1" || v === "parity";
+}
+
+/** Rebuild the omp cache from scratch (deletes existing cache, forces full scan). */
+export async function rebuildOmpCache(cachePath) {
+  const dbPath = cachePath || defaultCachePath();
+  await deleteCache(dbPath);
+  // The next scan will rebuild it
+}
+
+/** Get cache statistics for diagnostics. */
+export async function getCacheStats(cachePath) {
+  const dbPath = cachePath || defaultCachePath();
+  const healthy = await cacheIsHealthy(dbPath);
+  if (!healthy) return { healthy: false, files: 0, events: 0 };
+
+  const fileRows = await sqliteJson(dbPath, `SELECT COUNT(*) as n FROM files;`, 2_000);
+  const eventRows = await sqliteJson(
+    dbPath,
+    `SELECT COUNT(*) as n FROM usage_events;`,
+    5_000,
+  );
+
+  return {
+    healthy: true,
+    files: fileRows[0]?.n || 0,
+    events: eventRows[0]?.n || 0,
+    path: dbPath,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigrank",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "author": "SunrisesIllNeverSee (https://github.com/SunrisesIllNeverSee)",
   "description": "SigRank MCP server — AI operator evaluation and token cascade efficiency tools. The yield cascade + live leaderboard as MCP tools any agent can call.",
   "mcpName": "io.github.SunrisesIllNeverSee/sigrank-mcp",
@@ -25,6 +25,7 @@
   "scripts": {
     "start": "node index.mjs",
     "test": "node test.mjs && node __tests__/sign.test.mjs && node --test __tests__/cascade.test.mjs __tests__/badges.test.mjs __tests__/tui-input.test.mjs __tests__/standard-record.test.mjs __tests__/standard-cli.test.mjs",
+    "test:packaged": "node scripts/packed-artifact-smoke.mjs",
     "sync:platforms": "node scripts/sync-platforms.mjs",
     "sync:spine": "node scripts/sync-spine.mjs",
     "spine:check": "node scripts/sync-spine.mjs --check",
@@ -51,6 +52,7 @@
     "connect.mjs",
     "submit.mjs",
     "preflight.mjs",
+    "omp-cache.mjs",
     "adapters.mjs",
     "tokenpull.mjs",
     "tui.mjs",

package/tools/standard-record.mjs

@@ -6,7 +6,7 @@ export const SIGRANK_STANDARD_VERSION = "sigrank/0.1-draft";
 export const TOOL_DEF = {
   name: "get_sigrank_standard_record",
   description:
-    "Build a SigRank Standard v0.1-draft portable operator record from four token pillars. Computes the canonical cascade locally through @sigrank/cascade and returns versioned telemetry plus the normative core metrics: Yield, Leverage, Velocity, SNR, and 10xDEV. No data is submitted or persisted. The core record contains token telemetry only and does not require prompt text, code, or response content.",
+    "Build a SigRank Standard v0.1-draft portable operator record from available token telemetry. Input and output are required; unavailable cache telemetry remains null. Computes the canonical cascade locally through @sigrank/cascade and returns the normative core metrics: Yield, Leverage, Velocity, SNR, and 10xDEV. No data is submitted or persisted.",
   annotations: {
     title: "Export SigRank standard record",
     ...ANNOTATIONS.readOnlyHint,
@@ -17,26 +17,29 @@ export const TOOL_DEF = {
   inputSchema: {
     type: "object",
     additionalProperties: false,
-    required: ["input", "output", "cache_write", "cache_read"],
+    required: ["input", "output"],
     properties: {
-      input: { type: "number", minimum: 0, description: "Fresh input tokens." },
-      output: { type: "number", minimum: 0, description: "Output tokens." },
-      cache_write: { type: "number", minimum: 0, description: "Cache-write / cache-creation tokens." },
-      cache_read: { type: "number", minimum: 0, description: "Cache-read tokens." },
+      input: { type: "integer", minimum: 0, description: "Fresh input tokens." },
+      output: { type: "integer", minimum: 0, description: "Output tokens." },
+      cache_write: { type: ["integer", "null"], minimum: 0, description: "Cache-write / cache-creation tokens, or null when unavailable." },
+      cache_read: { type: ["integer", "null"], minimum: 0, description: "Cache-read tokens, or null when unavailable." },
       provider: { type: "string", description: "Optional provider identifier." },
       model: { type: "string", description: "Optional model identifier." },
       tool: { type: "string", description: "Optional tool/client identifier." },
-      timestamp: { type: "string", description: "Optional ISO-8601 timestamp. Defaults to the current time." }
+      timestamp: { type: "string", format: "date-time", description: "Optional ISO-8601 timestamp. Defaults to the current time." }
     }
   },
   outputSchema: {
     type: "object",
-    required: ["spec", "timestamp", "source", "telemetry", "metrics"],
+    additionalProperties: false,
+    required: ["spec", "timestamp", "source", "telemetry", "metrics", "warnings"],
     properties: {
-      spec: { type: "string", description: "SigRank specification version." },
-      timestamp: { type: "string", description: "ISO-8601 record timestamp." },
+      spec: { const: SIGRANK_STANDARD_VERSION, description: "SigRank specification version." },
+      timestamp: { type: "string", format: "date-time", description: "ISO-8601 record timestamp." },
       source: {
         type: "object",
+        additionalProperties: false,
+        required: ["provider", "model", "tool"],
         properties: {
           provider: { type: "string" },
           model: { type: "string" },
@@ -45,15 +48,19 @@ export const TOOL_DEF = {
       },
       telemetry: {
         type: "object",
+        additionalProperties: false,
+        required: ["input", "output", "cache_write", "cache_read"],
         properties: {
-          input: { type: "number" },
-          output: { type: "number" },
-          cache_write: { type: "number" },
-          cache_read: { type: "number" }
+          input: { type: "integer", minimum: 0 },
+          output: { type: "integer", minimum: 0 },
+          cache_write: { type: ["integer", "null"], minimum: 0 },
+          cache_read: { type: ["integer", "null"], minimum: 0 }
         }
       },
       metrics: {
         type: "object",
+        additionalProperties: false,
+        required: ["yield", "leverage", "velocity", "snr", "dev10x"],
         properties: {
           yield: { type: ["number", "null"] },
           leverage: { type: ["number", "null"] },
@@ -67,24 +74,48 @@ export const TOOL_DEF = {
   }
 };
 
-export async function handleGetSigRankStandardRecord(args) {
-  const input = Number(args?.input);
-  const output = Number(args?.output);
-  const cacheWrite = Number(args?.cache_write);
-  const cacheRead = Number(args?.cache_read);
+const ISO_DATE_TIME =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
 
-  if (![input, output, cacheWrite, cacheRead].every(Number.isFinite)) {
-    throw new Error("get_sigrank_standard_record requires four finite numeric token pillars.");
+function tokenCount(value, name, required) {
+  if (value === null || value === undefined) {
+    if (required) throw new Error(`${name} is required.`);
+    return null;
   }
-  if ([input, output, cacheWrite, cacheRead].some((v) => v < 0)) {
-    throw new Error("get_sigrank_standard_record requires non-negative token pillars.");
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value)) {
+    throw new Error(`${name} must be a non-negative integer token count.`);
+  }
+  if (value < 0) throw new Error(`${name} must be a non-negative integer token count.`);
+  return value;
+}
+
+function recordTimestamp(value) {
+  if (value === undefined) return new Date().toISOString();
+  if (typeof value !== "string" || !ISO_DATE_TIME.test(value) || !Number.isFinite(Date.parse(value))) {
+    throw new Error("timestamp must be a valid ISO-8601 date-time.");
   }
+  return value;
+}
+
+export async function handleGetSigRankStandardRecord(args) {
+  const input = tokenCount(args?.input, "input", true);
+  const output = tokenCount(args?.output, "output", true);
+  const cacheWrite = tokenCount(args?.cache_write, "cache_write", false);
+  const cacheRead = tokenCount(args?.cache_read, "cache_read", false);
 
-  const c = cascade({ input, output, cacheCreate: cacheWrite, cacheRead });
+  const c = cascade({
+    input,
+    output,
+    cacheCreate: cacheWrite ?? 0,
+    cacheRead: cacheRead ?? 0,
+  });
+  const warnings = [...(c.warnings || [])];
+  if (cacheWrite === null) warnings.push("cache_write is unavailable; 10xDEV is undefined.");
+  if (cacheRead === null) warnings.push("cache_read is unavailable; Yield, Leverage, and 10xDEV are undefined.");
 
   return {
     spec: SIGRANK_STANDARD_VERSION,
-    timestamp: args?.timestamp || new Date().toISOString(),
+    timestamp: recordTimestamp(args?.timestamp),
     source: {
       provider: args?.provider || "unknown",
       model: args?.model || "unknown",
@@ -97,12 +128,12 @@ export async function handleGetSigRankStandardRecord(args) {
       cache_read: cacheRead,
     },
     metrics: {
-      yield: c.yield,
-      leverage: c.leverage,
+      yield: cacheRead === null ? null : c.yield,
+      leverage: cacheRead === null ? null : c.leverage,
       velocity: c.velocity,
       snr: c.snr,
-      dev10x: c.dev10x,
+      dev10x: cacheWrite === null || cacheRead === null ? null : c.dev10x,
     },
-    warnings: c.warnings || [],
+    warnings,
   };
 }