@perpscope/percolator-adapter 0.6.0 → 0.8.0

package/README.md

@@ -63,6 +63,23 @@ The full field-level contract is documented in `../../docs/field-compatibility-m
 
 `compareCompatibilityReports(previous, current)` returns `perpscope.compatibility-diff` with score delta, status change, new/resolved fields, section drift, and merged alias suggestions.
 
+`buildCompatibilityRealityCheck(report, { input })` returns `perpscope.reality-check` with provenance, required/useful mapped counts, unknown fields, and alias counts. Use it when a terminal needs to show whether a capture is synthetic, real-backed candidate, or externally submitted.
+
+## CLI
+
+```bash
+perpscope compat report capture.json
+perpscope compat diff previous.json current.json
+```
+
+Try it locally with:
+
+```bash
+perpscope compat diff ../../examples/fixture-pack-minimal-terminal.json ../../examples/fixture-pack-drifted-aliases.json
+```
+
+For the real-backed candidate path, try `../../examples/fixture-pack-real-sanitized-rpc-shape.json`.
+
 ## DTO Example
 
 ```js

package/bin/perpscope.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import {
+  buildPercolatorCompatibilityReport,
+  compareCompatibilityReports,
+  exportCompatibilityReport,
+  normalizePercolatorSnapshot,
+  parsePercolatorJson
+} from "../index.js";
+
+const [, , ...args] = process.argv;
+
+function usage() {
+  return [
+    "Usage:",
+    "  perpscope compat report <capture.json>",
+    "  perpscope compat diff <previous.json> <current.json>",
+    "",
+    "Read-only only: the adapter rejects wallet, signer, transaction, instruction, order, private key, seed, mnemonic, and API key fields."
+  ].join("\n");
+}
+
+function readCapture(path) {
+  if (!path) throw new Error("Missing capture path.");
+  return parsePercolatorJson(readFileSync(path, "utf8"));
+}
+
+function buildReport(input) {
+  const snapshot = normalizePercolatorSnapshot(input);
+  return buildPercolatorCompatibilityReport(input, snapshot);
+}
+
+function main() {
+  const [scope, command, ...rest] = args;
+  if (!scope || scope === "--help" || scope === "-h") {
+    console.log(usage());
+    return;
+  }
+  if (scope !== "compat") throw new Error(`Unknown scope: ${scope}`);
+  if (command === "report") {
+    const input = readCapture(rest[0]);
+    console.log(JSON.stringify(exportCompatibilityReport(input), null, 2));
+    return;
+  }
+  if (command === "diff") {
+    const previous = buildReport(readCapture(rest[0]));
+    const current = buildReport(readCapture(rest[1]));
+    console.log(JSON.stringify(compareCompatibilityReports(previous, current), null, 2));
+    return;
+  }
+  throw new Error(`Unknown compat command: ${command || ""}`.trim());
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  console.error("");
+  console.error(usage());
+  process.exitCode = 1;
+}

package/index.js

@@ -1,5 +1,6 @@
 export {
   assertReadOnlySnapshot,
+  buildCompatibilityRealityCheck,
   buildPercolatorCompatibilityReport,
   compareCompatibilityReports,
   detectPercolatorInputShape,

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@perpscope/percolator-adapter",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Read-only Percolator adapter helpers for Solana perps terminals.",
   "main": "./index.js",
+  "bin": {
+    "perpscope": "bin/perpscope.mjs"
+  },
   "exports": {
     ".": "./index.js"
   },

package/src/lib/percolator-adapter.js

@@ -1,6 +1,6 @@
 import { normalizeFundingSkewHistory } from "./funding-history.js";
 
-export const PERPSCOPE_ADAPTER_VERSION = "0.6.0";
+export const PERPSCOPE_ADAPTER_VERSION = "0.8.0";
 
 const KEYPAIR_FIELD_PATTERN = /(^|_)(secret|private|keypair|mnemonic|seed|walletPath|wallet)(_|$)/i;
 const HISTORY_COMMAND_KEYS = new Set([
@@ -231,6 +231,60 @@ export function exportCompatibilityReportFromReport(report, options = {}) {
   };
 }
 
+export function buildCompatibilityRealityCheck(inputOrReport, options = {}) {
+  const hasReportShape = inputOrReport && typeof inputOrReport === "object" && Array.isArray(inputOrReport.recognizedSections);
+  const input = hasReportShape ? options.input : inputOrReport;
+  const report = hasReportShape ? normalizeCompatibilityReport(inputOrReport) : buildPercolatorCompatibilityReport(inputOrReport);
+  const requiredFields = COMPATIBILITY_FIELD_SPECS.filter((field) => field.severity === "danger");
+  const optionalFields = COMPATIBILITY_FIELD_SPECS.filter((field) => field.severity !== "danger");
+  const missingFieldSet = new Set((report.missingFields || []).map((field) => field.field));
+  const mappedRequired = requiredFields.filter((field) => !missingFieldSet.has(field.field));
+  const mappedOptional = optionalFields.filter((field) => !missingFieldSet.has(field.field));
+  const provenance = realityProvenance(input, report);
+  const unknownCount = report.summary?.ignoredCount ?? report.ignoredFields.length;
+  const aliasCount = report.summary?.suggestionCount ?? report.aliasSuggestions.length;
+  const dangerMissing = (report.missingFields || []).filter((field) => field.severity === "danger").length;
+  const warningMissing = (report.missingFields || []).length - dangerMissing;
+  const tone = dangerMissing
+    ? "danger"
+    : warningMissing || unknownCount || provenance.status === "candidate"
+      ? "warning"
+      : "good";
+
+  return {
+    schema: "perpscope.reality-check",
+    version: 1,
+    package: {
+      name: "@perpscope/percolator-adapter",
+      version: options.packageVersion || PERPSCOPE_ADAPTER_VERSION
+    },
+    generatedAt: options.generatedAt || new Date().toISOString(),
+    tone,
+    status: provenance.status,
+    sourceKind: provenance.kind,
+    provenance,
+    mapped: {
+      requiredCount: mappedRequired.length,
+      requiredTotal: requiredFields.length,
+      optionalCount: mappedOptional.length,
+      optionalTotal: optionalFields.length,
+      recognizedCount: report.summary?.recognizedCount ?? report.recognizedSections.length
+    },
+    gaps: {
+      dangerMissing,
+      warningMissing,
+      unknownCount,
+      aliasCount
+    },
+    lanes: [
+      realityLane("required", `${mappedRequired.length}/${requiredFields.length}`, dangerMissing ? "danger" : "good"),
+      realityLane("useful", `${mappedOptional.length}/${optionalFields.length}`, warningMissing ? "warning" : "good"),
+      realityLane("unknown", String(unknownCount), unknownCount ? "warning" : "good"),
+      realityLane("aliases", String(aliasCount), aliasCount ? "good" : "neutral")
+    ]
+  };
+}
+
 const COMPATIBILITY_SECTION_SPECS = [
   {
     id: "safety",
@@ -659,6 +713,30 @@ function compatibilityDiffSummary(report) {
   };
 }
 
+function realityLane(label, value, tone = "neutral") {
+  return { label, value, tone };
+}
+
+function realityProvenance(input, report) {
+  const source = report.source || {};
+  const inputSource = input && typeof input === "object" && !Array.isArray(input) ? input.source || {} : {};
+  const kind = stringOf(input, ["fixtureKind", "sourceKind"], inputSource.kind || source.shape || report.shape || "decoded-capture");
+  const candidate = /candidate|read-only-rpc|real/i.test(kind) || Boolean(inputSource.realBacked);
+  const submitted = Boolean(inputSource.submittedBy) || Boolean(inputSource.externalSubmission);
+  const status = submitted ? "submitted" : candidate ? "candidate" : "synthetic";
+  return {
+    status,
+    kind,
+    label: source.label || stringOf(input, ["label"], "decoded capture"),
+    cluster: source.cluster || stringOf(input, ["cluster"], "unknown"),
+    basis: inputSource.basis || inputSource.capture || "",
+    fixture: stringOf(input, ["fixture"], ""),
+    sanitized: inputSource.sanitized !== false,
+    submittedBy: inputSource.submittedBy || "",
+    note: inputSource.note || (status === "candidate" ? "real-backed candidate; still waiting on third-party decoded shape" : "")
+  };
+}
+
 function differenceByField(left = [], right = []) {
   const rightFields = new Set((right || []).map((entry) => entry.field));
   return (left || []).filter((entry) => !rightFields.has(entry.field));

package/src/lib/read-only-rpc-fetcher.js

@@ -97,6 +97,10 @@ export function buildReadOnlyRpcSnapshot(request) {
   if (decoded.params) commands.push({ command: "slab:params", output: decoded.params });
   if (decoded.engine) commands.push({ command: "slab:engine", output: decoded.engine });
   if (decoded.bestPrice) commands.push({ command: "best-price", output: decoded.bestPrice });
+  if (decoded.receipts || decoded.executionReceipts) commands.push({ command: "execution:receipts", output: decoded.receipts || decoded.executionReceipts });
+  if (decoded.fundingSkew || decoded.fundingHistory || decoded.fundingSkewHistory) {
+    commands.push({ command: "funding-skew-history", output: decoded.fundingSkew || decoded.fundingHistory || decoded.fundingSkewHistory });
+  }
   if (decoded.accounts) commands.push({ command: "slab:accounts", output: decoded.accounts });
   if (decoded.bitmap) commands.push({ command: "slab:bitmap", output: decoded.bitmap });