tamper-signal 1.7.0 → 1.7.1

package/AGENTS.md

@@ -299,6 +299,25 @@ folded into `verdict`, `exit_code`, `caveats`, and `report` (a missing
 anchor turns a green run yellow; a mismatch turns it red), so the payload
 never contradicts itself.
 
+`--json` is also available on `ingest`, `export`, and `doctor` (and `diff`,
+`log`, `anchor`), so an agent can drive the whole flow without scraping text.
+`ingest --json` returns `source`, `evidence_hash`, `semantic_hash`,
+`row_count`, `column_count`, `tolerance`, and `source_manifest`;
+`export --json` returns `output`, `row_count`, `column_count`, `data_hash`,
+and `bundle`; `doctor --json` returns `checks` (each with `name`, `ok`, `fix`),
+`warnings`, and `all_passed`. `log --json` carries the declared `band` and
+`settle_hours` per run entry when that run signed a tolerance. Failures under
+`--json` print a structured `{"ok": false, "error": ...}` object on stdout.
+The Python and Node payloads are key-identical for every shared command; Node
+has no `doctor` command, so `doctor --json` is Python-only.
+
+The human CLI is colored on an interactive terminal: the verdict shows as a
+green/amber/red `●` light that agrees with the exit code, and `diff` deltas are
+colored by direction. Color never appears in `--json` output or when stdout is
+piped or redirected. It honors `NO_COLOR` (force off, wins over everything),
+`FORCE_COLOR` (force on past the TTY check), and a `--no-color` flag. Agents
+parsing stdout get clean, ANSI-free output by default (a pipe is not a TTY).
+
 ### CI: verify the chain on every push
 
 ```yaml

package/node/cli.js

@@ -15,6 +15,7 @@ import { basename, dirname, join } from "node:path";
 import { parseArgs } from "node:util";
 import process from "node:process";
 
+import * as color from "./color.js";
 import { canonicalDocument, canonicalJsonBytes, semanticHash } from "./canonical.js";
 import {
   LOG_GRANULARITIES,
@@ -181,6 +182,12 @@ function archivePriorChain(chainDir) {
   }
 }
 
+// Emit a structured payload on stdout (the established --json convention,
+// shared byte-for-byte with the Python CLI).
+function printJson(payload) {
+  console.log(JSON.stringify(payload, null, 2));
+}
+
 // `ingest --as period`: continue the chain's run history under a trusted signer.
 function cmdIngestPeriod(values, file) {
   // Like replace, compute the unsnapshotted-reset condition and preserve the
@@ -205,19 +212,36 @@ function cmdIngestPeriod(values, file) {
     });
   } catch (err) {
     if (err instanceof UntrustedSignerError) {
-      console.error(`✗ Refusing to append a period: ${err.message}`);
+      if (values.json) printJson({ ok: false, error: `Refusing to append a period: ${err.message}` });
+      else console.error(`✗ Refusing to append a period: ${err.message}`);
       return 1;
     }
-    console.error(err.message);
+    if (values.json) printJson({ ok: false, error: err.message });
+    else console.error(err.message);
     return 1;
   }
   if (unsnapshottedReset) {
     console.error("warning: previous run was never verified; its totals will not enter history");
   }
   const totals = result.manifest.control_totals;
+  if (values.json) {
+    const caveats = result.caveats ?? [];
+    printJson({
+      source: result.manifest.source.filename,
+      evidence_hash: result.manifest.source.evidence_hash,
+      semantic_hash: result.manifest.semantic_hash,
+      row_count: totals.row_count,
+      column_count: totals.column_count,
+      mode: "period",
+      verdict: caveats.length ? "yellow" : "green",
+      caveats,
+      compared: Boolean(result.compared),
+    });
+    return caveats.length ? 2 : 0;
+  }
   console.log(`Imported next period: ${result.manifest.source.filename}`);
-  console.log(`  evidence_hash ${result.manifest.source.evidence_hash}`);
-  console.log(`  semantic_hash ${result.manifest.semantic_hash}`);
+  console.log(`  evidence_hash ${color.dim(result.manifest.source.evidence_hash)}`);
+  console.log(`  semantic_hash ${color.dim(result.manifest.semantic_hash)}`);
   console.log(`  rows ${totals.row_count}, columns ${totals.column_count}`);
   const grouped = groupedNumericColumns(result.records);
   if (grouped.length) {
@@ -255,6 +279,7 @@ function cmdIngest(args) {
       "bucket-column": { type: "string" },
       as: { type: "string", default: "replace" },
       pub: { type: "string", multiple: true, default: [] },
+      json: { type: "boolean", default: false },
     },
   });
   const file = positionals[0];
@@ -290,16 +315,29 @@ function cmdIngest(args) {
       bucketColumn: values["bucket-column"] ?? null,
     }));
   } catch (err) {
-    console.error(err.message);
+    if (values.json) printJson({ ok: false, error: err.message });
+    else console.error(err.message);
     return 1;
   }
   if (unsnapshottedReset) {
     console.error("warning: previous run was never verified; its totals will not enter history");
   }
   const totals = manifest.control_totals;
+  if (values.json) {
+    printJson({
+      source: manifest.source.filename,
+      evidence_hash: manifest.source.evidence_hash,
+      semantic_hash: manifest.semantic_hash,
+      row_count: totals.row_count,
+      column_count: totals.column_count,
+      tolerance: manifest.tolerance ?? null,
+      source_manifest: `${values.out.replace(/\/?$/, "/")}${SOURCE_RECEIPT_NAME}`,
+    });
+    return 0;
+  }
   console.log(`Ingested ${basename(file)}`);
-  console.log(`  evidence_hash ${manifest.source.evidence_hash}`);
-  console.log(`  semantic_hash ${manifest.semantic_hash}`);
+  console.log(`  evidence_hash ${color.dim(manifest.source.evidence_hash)}`);
+  console.log(`  semantic_hash ${color.dim(manifest.semantic_hash)}`);
   console.log(`  rows ${totals.row_count}, columns ${totals.column_count}`);
   if (manifest.tolerance) {
     const t = manifest.tolerance;
@@ -422,6 +460,9 @@ function cmdVerify(args) {
     };
     console.log(JSON.stringify(payload, null, 2));
   } else {
+    if (color.shouldColor()) {
+      console.log(`${color.light(result.verdict)} ${color.colorize(result.verdict.toUpperCase(), result.verdict)}`);
+    }
     for (const line of result.lines) console.log(line);
   }
   // Archive the run snapshot AFTER the final exit code settled: a red run
@@ -602,14 +643,14 @@ function renderStageDelta(delta) {
   for (const key of ["row_count", "column_count"]) {
     const entry = delta[key];
     if (entry) {
-      const suffix = "delta" in entry ? ` (${signedInt(entry.delta)})` : "";
+      const suffix = "delta" in entry ? ` (${color.signed(signedInt(entry.delta))})` : "";
       lines.push(`${key} ${entry.before} -> ${entry.after}${suffix}`);
     }
   }
   for (const [column, entry] of Object.entries(delta.numeric_sums ?? {})) {
     const before = entry.before !== null ? entry.before : "(added)";
     const after = entry.after !== null ? entry.after : "(removed)";
-    const suffix = "delta" in entry ? ` (${entry.delta})` : "";
+    const suffix = "delta" in entry ? ` (${color.signed(entry.delta)})` : "";
     lines.push(`${column} ${before} -> ${after}${suffix}`);
   }
   for (const [column, entry] of Object.entries(delta.null_counts ?? {})) {
@@ -1014,19 +1055,36 @@ function cmdLog(args) {
   const { rows, collapsed } = buildLogPeriods(items, granularity, metrics);
 
   if (values.json) {
-    const payload = {
-      granularity,
-      // Total runs collapsed away by the granularity. Ordered chronological
-      // (oldest first), matching the Python CLI byte-for-byte.
-      collapsed,
-      runs: rows.map((row, index) => ({
+    // The signed tolerance declaration is per-snapshot, display-only; surface
+    // it per run entry (omitted when that run declared none), matching Python.
+    const tolByTail = new Map();
+    for (const snapshot of snapshots) {
+      if (snapshot.tolerance && typeof snapshot.tolerance === "object") {
+        tolByTail.set(snapshot.chain_tail_hash, snapshot.tolerance);
+      }
+    }
+    const runEntry = (row, index) => {
+      const entry = {
         period: row.period,
         created_at: row.created_at,
         tail: row.tail ? row.tail.slice(0, 8) : null,
         unsigned: row.unsigned,
         metrics: logJsonMetrics(rows, index, metrics),
         breached: metrics.filter((m) => row.breached.has(m)).sort(),
-      })),
+      };
+      const tolerance = tolByTail.get(row.tail);
+      if (tolerance && typeof tolerance === "object") {
+        if (tolerance.band != null) entry.band = tolerance.band;
+        if (tolerance.settle_hours != null) entry.settle_hours = tolerance.settle_hours;
+      }
+      return entry;
+    };
+    const payload = {
+      granularity,
+      // Total runs collapsed away by the granularity. Ordered chronological
+      // (oldest first), matching the Python CLI byte-for-byte.
+      collapsed,
+      runs: rows.map(runEntry),
     };
     console.log(JSON.stringify(payload, null, 2));
     return 0;
@@ -1045,6 +1103,7 @@ function cmdExport(args) {
       data: { type: "string" },
       out: { type: "string" },
       bundle: { type: "boolean" },
+      json: { type: "boolean", default: false },
     },
   });
   const chainPath = positionals[0];
@@ -1062,11 +1121,13 @@ function cmdExport(args) {
   try {
     receipts = (chain.receipts ?? []).map((name) => readReceipt(chainDir, name));
   } catch (err) {
-    console.error(`Cannot load chain: ${err.message}`);
+    if (values.json) printJson({ ok: false, error: `Cannot load chain: ${err.message}` });
+    else console.error(`Cannot load chain: ${err.message}`);
     return 1;
   }
   if (!receipts.length) {
-    console.error("Chain is empty; nothing to export against.");
+    if (values.json) printJson({ ok: false, error: "Chain is empty; nothing to export against." });
+    else console.error("Chain is empty; nothing to export against.");
     return 1;
   }
 
@@ -1080,10 +1141,19 @@ function cmdExport(args) {
   const dataHash = createHash("sha256").update(canonicalJsonBytes(document)).digest("hex");
   const expected = outputHashOf(receipts[receipts.length - 1]);
   if (dataHash !== expected) {
-    console.error("✗ Refusing to export: the data does not match the final receipt.");
-    console.error(`  expected output hash ${expected}`);
-    console.error(`  found    data hash   ${dataHash}`);
-    console.error("  The Data tab only shows attested data. Re-run the pipeline or fix --data.");
+    if (values.json) {
+      printJson({
+        ok: false,
+        error: "the data does not match the final receipt",
+        expected_output_hash: expected,
+        data_hash: dataHash,
+      });
+    } else {
+      console.error("✗ Refusing to export: the data does not match the final receipt.");
+      console.error(`  expected output hash ${expected}`);
+      console.error(`  found    data hash   ${dataHash}`);
+      console.error("  The Data tab only shows attested data. Re-run the pipeline or fix --data.");
+    }
     return 1;
   }
 
@@ -1103,22 +1173,46 @@ function cmdExport(args) {
     const stem = dataName.replace(/\.[^.]+$/, "");
     const bundlePath = values.out || join(chainDir, `${stem}-verified.zip`);
     writeFileSync(bundlePath, makeStoredZip(entries));
+    if (values.json) {
+      printJson({
+        output: bundlePath,
+        data: dataName,
+        receipts: receiptNames.length,
+        data_hash: dataHash,
+        bundle: true,
+      });
+      return 0;
+    }
     console.log(`Exported verified bundle: ${bundlePath}`);
     console.log(`  data ${dataName}, ${receiptNames.length} receipts + ${CHAIN_FILENAME}`);
-    console.log(`  semantic_hash ${dataHash} (matches final receipt)`);
+    console.log(`  semantic_hash ${color.dim(dataHash)} (matches final receipt)`);
     console.log(`  recipient: unzip, then \`tamper-signal verify ${CHAIN_FILENAME}\``);
     return 0;
   }
 
   const outPath = values.out || join(chainDir, "table.json");
   writeFileSync(outPath, JSON.stringify(document, null, 2) + "\n");
+  if (values.json) {
+    printJson({
+      output: outPath,
+      row_count: document.rows.length,
+      column_count: document.headers.length,
+      data_hash: dataHash,
+      bundle: false,
+    });
+    return 0;
+  }
   console.log(`Exported verified table: ${outPath}`);
   console.log(`  rows ${document.rows.length}, columns ${document.headers.length}`);
-  console.log(`  semantic_hash ${dataHash} (matches final receipt)`);
+  console.log(`  semantic_hash ${color.dim(dataHash)} (matches final receipt)`);
   return 0;
 }
 
-const [, , command, ...rest] = process.argv;
+const [, , command, ...rawRest] = process.argv;
+// --no-color is global: honor it at any position and strip it so each command's
+// strict parser does not reject it. NO_COLOR / FORCE_COLOR env are honored too.
+if (rawRest.includes("--no-color")) color.setNoColor(true);
+const rest = rawRest.filter((arg) => arg !== "--no-color");
 const commands = { keygen: cmdKeygen, ingest: cmdIngest, verify: cmdVerify, diff: cmdDiff, log: cmdLog, export: cmdExport };
 if (!command || !(command in commands)) {
   console.error(USAGE);

package/node/color.js

@@ -0,0 +1,78 @@
+// Terminal color for the human-facing CLI: the Node port of tamper_signal/color.py.
+// Presentation layer only. Color is emitted to stdout only when it is an
+// interactive terminal and no override turns it off; every primitive returns
+// plain text when color is off, so the word and glyph survive without ANSI.
+//
+// Gating precedence (highest first):
+//   1. --no-color flag (setNoColor)               -> off
+//   2. NO_COLOR env present (any value)           -> off
+//   3. FORCE_COLOR env present                    -> on
+//   4. otherwise                                  -> stream.isTTY
+// NO_COLOR wins over FORCE_COLOR. shouldColor is only evaluated against stdout;
+// stderr (notices) and --json output are always plain.
+
+// SGR codes. Kept identical to tamper_signal/color.py so the two CLIs match.
+export const RESET = "\x1b[0m";
+export const DIM = "\x1b[2m";
+export const BOLD = "\x1b[1m";
+export const GREEN = "\x1b[32m";
+export const YELLOW = "\x1b[33m";
+export const RED = "\x1b[31m";
+
+// "amber" names the color; the verdict value stays "yellow".
+const VERDICT_COLOR = { green: GREEN, yellow: YELLOW, red: RED };
+
+// Set by the CLI when --no-color is passed. Always wins over the environment.
+let noColor = false;
+
+export function setNoColor(value) {
+  noColor = Boolean(value);
+}
+
+export function shouldColor(stream = process.stdout) {
+  if (noColor) return false;
+  if (process.env.NO_COLOR !== undefined) return false;
+  if (process.env.FORCE_COLOR !== undefined) return true;
+  return Boolean(stream && stream.isTTY);
+}
+
+function paint(text, code, stream) {
+  return shouldColor(stream) ? `${code}${text}${RESET}` : text;
+}
+
+// Dim secondary detail (hashes, counts) when color is on.
+export function dim(text, stream = process.stdout) {
+  return paint(text, DIM, stream);
+}
+
+export function bold(text, stream = process.stdout) {
+  return paint(text, BOLD, stream);
+}
+
+// The colored traffic-light glyph for a verdict ("green"/"yellow"/"red").
+// The caller prints the verdict word alongside it, so meaning survives color-off.
+export function light(verdict, stream = process.stdout) {
+  return paint("●", VERDICT_COLOR[verdict] ?? "", stream);
+}
+
+// Paint text in a verdict's color ("green"/"yellow"/"red").
+export function colorize(text, verdict, stream = process.stdout) {
+  return paint(text, VERDICT_COLOR[verdict] ?? "", stream);
+}
+
+// Color a pre-formatted signed token by its sign (+green, -red).
+export function signed(token, stream = process.stdout) {
+  const text = String(token);
+  if (text.startsWith("+")) return paint(text, GREEN, stream);
+  if (text.startsWith("-")) return paint(text, RED, stream);
+  return text;
+}
+
+// A signed movement value, colored by direction (increase green, decrease red).
+// The sign is always printed, so direction reads without color and for
+// colorblind users. Direction is a neutral cue, not a verdict.
+export function delta(value, stream = process.stdout) {
+  if (value > 0) return paint(`+${value}`, GREEN, stream);
+  if (value < 0) return paint(`${value}`, RED, stream);
+  return "0";
+}

package/node/test/cli_color.test.js

@@ -0,0 +1,87 @@
+// Node CLI color application and gating (U6): the colored verdict headline and
+// the NO_COLOR / FORCE_COLOR / --no-color gate, mirroring tests/test_cli_color.py.
+// Color is gated to a TTY, so these force it on with FORCE_COLOR (the pipe from
+// execFileSync is not a TTY) and assert plain output when it is off.
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { GREEN, RESET } from "../color.js";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const cli = join(repoRoot, "node", "cli.js");
+
+function run(cwd, args, env = {}) {
+  // Start from a clean slate: NO_COLOR / FORCE_COLOR only present when a test
+  // sets them (a key set to undefined would stringify to "undefined").
+  const base = { ...process.env, TAMPER_SIGNAL_KEY: "" };
+  delete base.NO_COLOR;
+  delete base.FORCE_COLOR;
+  return execFileSync(process.execPath, [cli, ...args], { cwd, env: { ...base, ...env }, encoding: "utf-8" });
+}
+
+function seedChain() {
+  const dir = mkdtempSync(join(tmpdir(), "tamper-signal-color-"));
+  run(dir, ["keygen", "--out", "keys"]);
+  writeFileSync(join(dir, "d.csv"), "day,amount\n2026-05-01,10\n");
+  run(dir, ["ingest", "d.csv"]);
+  return dir;
+}
+
+test("verify headline is a colored light under FORCE_COLOR", () => {
+  const dir = seedChain();
+  const out = run(dir, ["verify", "receipts/chain.json"], { FORCE_COLOR: "1" });
+  assert.ok(out.includes(`${GREEN}●${RESET}`));
+  assert.ok(out.includes(`${GREEN}GREEN${RESET}`));
+  assert.ok(out.includes("CHAIN INTACT"));
+});
+
+test("verify piped is plain text with no ANSI", () => {
+  const dir = seedChain();
+  const out = run(dir, ["verify", "receipts/chain.json"]);
+  assert.ok(!out.includes("\x1b"));
+  assert.ok(out.includes("CHAIN INTACT"));
+});
+
+test("--no-color beats FORCE_COLOR", () => {
+  const dir = seedChain();
+  const out = run(dir, ["verify", "receipts/chain.json", "--no-color"], { FORCE_COLOR: "1" });
+  assert.ok(!out.includes("\x1b"));
+});
+
+test("NO_COLOR beats FORCE_COLOR", () => {
+  const dir = seedChain();
+  const out = run(dir, ["verify", "receipts/chain.json"], { FORCE_COLOR: "1", NO_COLOR: "1" });
+  assert.ok(!out.includes("\x1b"));
+});
+
+// The acceptance gate (R16): ANSI must never leak into --json, even with color
+// forced on. Mirrors tests/test_cli_json_gate.py (node has no doctor command).
+test("no ANSI leaks into --json even under FORCE_COLOR", () => {
+  const dir = mkdtempSync(join(tmpdir(), "tamper-signal-gate-"));
+  run(dir, ["keygen", "--out", "keys"]);
+  writeFileSync(join(dir, "d.csv"), "day,amount\n2026-05-01,10\n");
+  run(dir, ["ingest", "d.csv"]);
+  run(dir, ["verify", "receipts/chain.json"]);
+  writeFileSync(join(dir, "d.csv"), "day,amount\n2026-05-01,10\n2026-05-02,20\n");
+  run(dir, ["ingest", "d.csv"]);
+  run(dir, ["verify", "receipts/chain.json"]);
+
+  const commands = [
+    ["verify", "receipts/chain.json", "--json"],
+    ["log", "--chain", "receipts/", "--json"],
+    ["diff", "--json"],
+    ["export", "receipts/chain.json", "--data", "d.csv", "--json"],
+    ["ingest", "d.csv", "--json"],
+  ];
+  for (const args of commands) {
+    const out = run(dir, args, { FORCE_COLOR: "1" });
+    assert.ok(!out.includes("\x1b"), `ANSI leaked into --json of ${args[0]}`);
+    JSON.parse(out);
+  }
+});

package/node/test/color.test.js

@@ -0,0 +1,90 @@
+// Mirrors tests/test_color.py: the gating matrix plus verdict/delta conventions.
+// Also asserts the SGR palette matches the Python helper byte for byte (pins R15).
+
+import { test, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+
+import { setNoColor, shouldColor, light, delta, dim, bold, GREEN, YELLOW, RED, DIM, BOLD, RESET } from "../color.js";
+
+const TTY = { isTTY: true };
+const PIPE = { isTTY: false };
+
+beforeEach(() => {
+  delete process.env.NO_COLOR;
+  delete process.env.FORCE_COLOR;
+  setNoColor(false);
+});
+
+test("shouldColor: true on a TTY with no overrides", () => {
+  assert.equal(shouldColor(TTY), true);
+});
+
+test("shouldColor: false when not a TTY", () => {
+  assert.equal(shouldColor(PIPE), false);
+});
+
+test("shouldColor: NO_COLOR wins even on a TTY (any value)", () => {
+  process.env.NO_COLOR = "1";
+  assert.equal(shouldColor(TTY), false);
+  process.env.NO_COLOR = "";
+  assert.equal(shouldColor(TTY), false);
+});
+
+test("shouldColor: --no-color flag wins even on a TTY", () => {
+  setNoColor(true);
+  assert.equal(shouldColor(TTY), false);
+});
+
+test("shouldColor: FORCE_COLOR turns on even when piped", () => {
+  process.env.FORCE_COLOR = "1";
+  assert.equal(shouldColor(PIPE), true);
+});
+
+test("shouldColor: NO_COLOR beats FORCE_COLOR", () => {
+  process.env.NO_COLOR = "1";
+  process.env.FORCE_COLOR = "1";
+  assert.equal(shouldColor(TTY), false);
+});
+
+test("light: colors each verdict when on", () => {
+  process.env.FORCE_COLOR = "1";
+  assert.equal(light("green", PIPE), `${GREEN}●${RESET}`);
+  assert.equal(light("yellow", PIPE), `${YELLOW}●${RESET}`);
+  assert.equal(light("red", PIPE), `${RED}●${RESET}`);
+});
+
+test("light: plain glyph when off", () => {
+  assert.equal(light("green", PIPE), "●");
+  assert.ok(!light("red", PIPE).includes("\x1b"));
+});
+
+test("delta: signs and colors direction when on", () => {
+  process.env.FORCE_COLOR = "1";
+  assert.equal(delta(12, PIPE), `${GREEN}+12${RESET}`);
+  assert.equal(delta(-5, PIPE), `${RED}-5${RESET}`);
+  assert.equal(delta(0, PIPE), "0");
+});
+
+test("delta: keeps sign when color off", () => {
+  assert.equal(delta(12, PIPE), "+12");
+  assert.equal(delta(-5, PIPE), "-5");
+  assert.ok(!delta(12, PIPE).includes("\x1b"));
+});
+
+test("dim/bold wrap only when on", () => {
+  assert.equal(dim("abc", PIPE), "abc");
+  assert.equal(bold("abc", PIPE), "abc");
+  process.env.FORCE_COLOR = "1";
+  assert.equal(dim("abc", PIPE), `${DIM}abc${RESET}`);
+  assert.equal(bold("abc", PIPE), `${BOLD}abc${RESET}`);
+});
+
+// Cross-stack palette parity: these MUST equal tamper_signal/color.py's codes.
+test("palette parity: SGR codes match the Python helper", () => {
+  assert.equal(GREEN, "\x1b[32m");
+  assert.equal(YELLOW, "\x1b[33m");
+  assert.equal(RED, "\x1b[31m");
+  assert.equal(DIM, "\x1b[2m");
+  assert.equal(BOLD, "\x1b[1m");
+  assert.equal(RESET, "\x1b[0m");
+});

package/node/test/json_surface.test.js

@@ -0,0 +1,87 @@
+// `tamper-signal ingest --json` and `export --json` (U4): the machine surface
+// added in 1.7.1. Mirrors the Python tests in tests/test_cli_agent_ergonomics.py;
+// payload keys must match the Python CLI byte for byte (R5). Driven through the
+// real CLI via execFileSync so the captured stdout is exactly what ships.
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const cli = join(repoRoot, "node", "cli.js");
+
+function runCli(cwd, args, { expectFail = false } = {}) {
+  const env = { ...process.env, TAMPER_SIGNAL_KEY: "" };
+  try {
+    return { stdout: execFileSync(process.execPath, [cli, ...args], { cwd, env, encoding: "utf-8" }), stderr: "", status: 0 };
+  } catch (err) {
+    if (!expectFail) throw err;
+    return { stdout: err.stdout ?? "", stderr: err.stderr ?? "", status: err.status ?? 1 };
+  }
+}
+
+function seedChain() {
+  const dir = mkdtempSync(join(tmpdir(), "tamper-signal-json-"));
+  runCli(dir, ["keygen", "--out", "keys"]);
+  writeFileSync(join(dir, "data.csv"), "day,amount\n2026-05-01,10\n2026-05-02,20\n");
+  return dir;
+}
+
+test("ingest --json emits a structured result", () => {
+  const dir = seedChain();
+  const payload = JSON.parse(runCli(dir, ["ingest", "data.csv", "--json"]).stdout);
+  assert.equal(payload.source, "data.csv");
+  assert.equal(payload.row_count, 2);
+  assert.equal(payload.column_count, 2);
+  assert.equal(payload.tolerance, null);
+  assert.ok(payload.semantic_hash);
+  assert.ok(payload.source_manifest.endsWith("000_source.json"));
+  // Pinned key set: must equal the Python ingest --json payload (R5).
+  assert.deepEqual(
+    Object.keys(payload).sort(),
+    ["column_count", "evidence_hash", "row_count", "semantic_hash", "source", "source_manifest", "tolerance"],
+  );
+});
+
+test("ingest --json includes a declared tolerance", () => {
+  const dir = seedChain();
+  const payload = JSON.parse(runCli(dir, ["ingest", "data.csv", "--band", "5%", "--settle", "72h", "--json"]).stdout);
+  assert.equal(payload.tolerance.band, "0.05");
+  assert.equal(payload.tolerance.settle_hours, 72);
+});
+
+test("export --json writes a table result", () => {
+  const dir = seedChain();
+  runCli(dir, ["ingest", "data.csv"]);
+  const payload = JSON.parse(runCli(dir, ["export", "receipts/chain.json", "--data", "data.csv", "--json"]).stdout);
+  assert.equal(payload.bundle, false);
+  assert.ok(payload.output.endsWith("table.json"));
+  assert.ok(payload.data_hash);
+  assert.equal(payload.row_count, 2);
+  // Pinned key set: must equal the Python export --json payload (R5).
+  assert.deepEqual(Object.keys(payload).sort(), ["bundle", "column_count", "data_hash", "output", "row_count"]);
+});
+
+test("export --bundle --json reports the bundle", () => {
+  const dir = seedChain();
+  runCli(dir, ["ingest", "data.csv"]);
+  const payload = JSON.parse(runCli(dir, ["export", "receipts/chain.json", "--data", "data.csv", "--bundle", "--json"]).stdout);
+  assert.equal(payload.bundle, true);
+  assert.ok(payload.receipts >= 1);
+  assert.ok(payload.output.endsWith("-verified.zip"));
+});
+
+test("export --json gives a structured error on mismatch (clean stdout)", () => {
+  const dir = seedChain();
+  runCli(dir, ["ingest", "data.csv"]);
+  writeFileSync(join(dir, "wrong.csv"), "x\n1\n");
+  const res = runCli(dir, ["export", "receipts/chain.json", "--data", "wrong.csv", "--json"], { expectFail: true });
+  assert.equal(res.status, 1);
+  const payload = JSON.parse(res.stdout);
+  assert.equal(payload.ok, false);
+  assert.match(payload.error, /match/);
+});

package/node/test/log.test.js

@@ -233,3 +233,15 @@ test("log renders a real built history end to end", () => {
   assert.ok(payload.runs.length >= 1);
   assert.ok(payload.runs.every((r) => r.unsigned === false));
 });
+
+test("log --json surfaces band/settle per run, only where declared", () => {
+  const s0 = snapshot({ createdAt: "2026-05-01T00:00:00Z", rowCount: 100, tail: "aa".repeat(32) });
+  const s1 = snapshot({ createdAt: "2026-05-02T00:00:00Z", rowCount: 110, tail: "bb".repeat(32) });
+  s1.tolerance = { band: "0.05", settle_hours: 72, bucket_column: "day" };
+  const receipts = writeHistory([s0, s1]);
+
+  const runs = JSON.parse(runLog(receipts, ["--json"]).stdout).runs; // oldest first
+  assert.ok(!("band" in runs[0]) && !("settle_hours" in runs[0]));
+  assert.equal(runs[1].band, "0.05");
+  assert.equal(runs[1].settle_hours, 72);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamper-signal",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Signed receipts for vibe-coded data pipelines. Proves nobody changed your data, and shows the exact link if they did.",
   "type": "module",
   "license": "MIT",
@@ -64,7 +64,7 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "test": "node --test node/test/badge.test.js node/test/canonical.test.js node/test/chain.test.js node/test/interop.test.js node/test/express.test.js node/test/totals.test.js node/test/pipeline.test.js node/test/history.test.js node/test/diff.test.js node/test/log.test.js node/test/judgment.test.js node/test/theme.test.js node/test/zip.test.js node/test/append_period.test.js"
+    "test": "node --test node/test/badge.test.js node/test/canonical.test.js node/test/chain.test.js node/test/interop.test.js node/test/express.test.js node/test/totals.test.js node/test/pipeline.test.js node/test/history.test.js node/test/diff.test.js node/test/log.test.js node/test/judgment.test.js node/test/theme.test.js node/test/zip.test.js node/test/append_period.test.js node/test/color.test.js node/test/json_surface.test.js node/test/cli_color.test.js"
   },
   "engines": {
     "node": ">=18.17"