cli.js

#!/usr/bin/env node

/**
 * @veritasacta/verify: unified verifier CLI (v0.5.4)
 *
 * Verifies Ed25519 signed receipts, VOPRF anonymous-credential tokens,
 * Knowledge Unit bundles, and selective-disclosure receipts, all offline,
 * all under one binary with one Sigil commitment.
 *
 * Architecture is modular: this file is the entry point + dispatcher.
 * Cryptographic verification lives in src/engines/*.js. Output formatting
 * lives in src/output/*.js.
 *
 * Usage:
 *   npx @veritasacta/verify receipt.json
 *   npx @veritasacta/verify receipt.json --key <hex>
 *   npx @veritasacta/verify receipt.json --jwks <url>
 *   npx @veritasacta/verify bundle.json --bundle --key <hex>
 *   npx @veritasacta/verify ku.json --mode ku
 *   npx @veritasacta/verify receipt.json --disclose field1,field2:salt:value
 *   npx @veritasacta/verify receipt.json --require-context sensor:temp<18
 *   npx @veritasacta/verify --self-check
 *   npx @veritasacta/verify --self-test
 *   npx @veritasacta/verify --capabilities
 *
 * Exit codes:
 *   0 = signature valid (proven authentic)
 *   1 = signature invalid (proven tampered)
 *   2 = verifier error (malformed input, missing key, unsupported algorithm)
 *
 * References:
 *   - draft-farley-acta-signed-receipts-03
 *   - draft-farley-acta-knowledge-units-00
 *   - AIP-0001, AIP-0002, AIP-0003
 *   - Provisional patents #1-5
 *
 * @license Apache-2.0
 */

import { readFileSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { detectFormat } from './src/detect.js';
import { parseReceiptJson, parseJsonStrict } from './src/util/strict-json.js';
import { verifyReceipt, verifyBundle, combineChecks } from './src/engines/ed25519-receipt.js';
import { verifyGateTuple, verifyGateBundle } from './src/engines/gate-receipt.js';
import { verifyMacroTrackRecord } from './src/engines/macro-snapshot.js';
import { verifyLegateGovernedReceipt } from './src/engines/legate-governed-receipt.js';
import { verifyLegateProofPack } from './src/engines/legate-proof-pack.js';
import { verifyRepositoryArtifact } from './src/engines/repository-evidence.js';
import { verifyLegateStandard } from './src/engines/legate-standard.js';
import { verifyTrustedContextPack } from './src/engines/trusted-context-pack.js';
import {
  CLAIMS_V211_TYPES,
  parseClaimsJsonV211Independent,
  verifyClaimsArtifactV211,
} from './src/engines/claims-v211.js';
import { verifyVoprfToken } from './src/engines/voprf-token.js';
import { verifyKnowledgeUnit } from './src/engines/knowledge-unit.js';
import {
  verifySelectiveDisclosure,
  listRedactedFields,
  signedLegacyCommitments,
} from './src/engines/selective-disclosure.js';
import {
  verifyCommittedReceipt,
  loadDisclosuresFromText,
  signedCommitment,
} from './src/engines/commitment-mode.js';
import { selfCheck, evaluateLiveContext } from './src/engines/sigil.js';
import {
  buildCanonicalAttestation,
  buildVerificationReceipt,
} from './src/engines/attestation.js';
import { replayChain, checkPreviousLink, COMPATIBILITY_NOTE } from './src/engines/bulk.js';
import { diffReceipts } from './src/engines/diff.js';
import { runInit, buildNextSteps } from './src/engines/init.js';
import { runProxy } from './src/engines/proxy.js';
import { runDaemon } from './src/engines/daemon.js';
import { verifyPrompt } from './src/engines/prompt.js';
import { exploreChain, renderChainTree } from './src/engines/chain-explore.js';
import { exportCompliance, renderComplianceHTML } from './src/engines/compliance-export.js';
import { startDashboard } from './src/engines/dashboard.js';
import { verifyDelegationChain } from './src/engines/delegation.js';
import { verifyCosignatures } from './src/engines/cosign.js';
import { parseContextArgs } from './src/context/live-context.js';
import { detectTier } from './src/conformance.js';
import { resolveFromJwks, loadJwksResolver } from './src/util/jwks.js';
import { checkKeyWindow, receiptIssuedAt, keyWindowCheck } from './src/util/key-window.js';
import { loadKnownIssuers, labelFor } from './src/util/known-issuers.js';
import { appendAuditEntry, lastChainHash } from './src/util/audit-log.js';
import { fipsStatus, verifiedAlgorithms } from './src/util/fips.js';
import { renderHtmlReport } from './src/output/html-report.js';
import { getError, exitCodeFor } from './src/errors.js';
import { readSigilMonitoredSource } from './src/sigil-policy.js';

import {
  formatReceiptResult,
  formatBundleResult,
  formatGateTupleResult,
  formatGateBundleResult,
  formatMacroTrackRecordResult,
  formatGovernedReceiptResult,
  formatTrustedContextPackResult, formatRunManifestResult,
  formatKuResult,
  formatSelfCheckResult,
  green,
  red,
  yellow,
  dim,
  bold,
  teal,
  renderTerminalSigil,
  replayHeadline,
} from './src/output/terminal.js';
import { formatAsJson } from './src/output/json.js';

const __dirname = dirname(fileURLToPath(import.meta.url));
const PKG = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));

/** What parseArgs, enforcePinSigil and dispatch return when they refuse the run, having said why on stderr: exit 2. */
const REFUSED = Symbol('refused');

/**
 * Exits with `code` once stdout and stderr have taken everything written to them. Every other run ends by returning
 * its exit status, and the process then ends by itself once its output is written. Up to 0.11.0 each run ended with
 * process.exit(), which ends the process at once, while Node can still be writing stdout to a pipe: a reader such as
 * `| jq` got the first 64 KiB of a larger report, and the exit status of a complete one. The proxy exits here because
 * its relay goes on reading stdin after the child has exited, which would keep the process alive.
 */
function exitWhenWritten(code) {
  process.exitCode = code;
  process.stdout.write('', () => process.stderr.write('', () => process.exit(code)));
}

/** Exit 0 means the answer is the good one: valid, and, when companion files were given, bound to all of them. A run manifest that verifies alone is exit 0 and says unbound; one that fails to bind to what was supplied is exit 1, however valid its own signature. */
function exitOk(result) {
  if (!result || !result.valid) return false;
  if (typeof result.binding === 'string') return result.binding === 'bound' || result.binding === 'manifest_only';
  return true;
}

/** The mode line names the Legate artifact that was checked, not the list of what could have been. */
function legateModeLabel(r) {
  const t = r && r.artifact_type;
  if (t === 'scopeblind.run_manifest.v1') return 'Legate verified run (run manifest), checked offline';
  if (t === 'scopeblind.proof_request.v1') return 'Legate signed standard (proof request), checked offline';
  if (t === 'scopeblind.admission_decision.v1') return 'Legate recipient decision, checked offline';
  if (t === 'scopeblind.action_assurance_bundle.v1') return 'Legate action assurance bundle, checked offline';
  if (t === 'scopeblind.run_regrade.v1') return 'Legate second grading (run regrade), checked offline';
  return MODE_LABELS['legate-standard'];
}

/** The single-receipt modes, the only ones --previous applies to. */
const RECEIPT_MODES = ['ed25519-browser-legacy', 'ed25519-receipt-v1', 'ed25519-receipt-v2', 'ed25519-passport'];

/** What a result accepted with --allow-carried-key says, in the JSON and the terminal. */
const CARRIED_KEY_NOTICE = 'Checked only against the key the file carries (--allow-carried-key): the signature shows the file matches that key, and proves nothing about who signed it.';

/**
 * A key the file carries is never a trust anchor (draft §9.5), so a result that rests only on one is undecidable
 * (embedded_key_rejected, exit 2), never valid. `carried` names what was checked only against a key in the file, or
 * is null when a key from outside it was applied. --allow-carried-key accepts such a result (exit 0) and marks it
 * carriedKeyOnly, with CARRIED_KEY_NOTICE; --strict refuses it even then. Before, these formats exited 0 on the key
 * they carry by default and under --strict, so a Gate record signed by any fresh key passed.
 */
function refuseCarriedKey(result, opts, carried) {
  // A check that ran and failed stays the outcome (-04 §5.3): only a result that would otherwise pass is refused.
  if (!exitOk(result) || !carried) return result;
  if (opts.allowCarriedKey && !opts.strict) {
    return { ...result, carriedKeyOnly: true, warning: [result.warning, CARRIED_KEY_NOTICE].filter(Boolean).join(' ') };
  }
  return {
    ...result,
    valid: false,
    error: 'embedded_key_rejected',
    carriedKeyOnly: true,
    detail: opts.strict
      ? `--strict: ${carried} was checked only against a key it carries, which is not a trust anchor; --strict refuses it even with --allow-carried-key. Pin the key with --key.`
      : `${carried} was checked only against a key it carries, which is not a trust anchor. Pin the key with --key; --allow-carried-key accepts it, proving nothing about who signed.`,
    ...(typeof result.title === 'string' ? { title: 'Not checked: no key from outside the file was given' } : {}),
  };
}

const MODE_LABELS = {
  'ed25519-browser-legacy': 'Historical browser receipt 1.0 (not draft-03)',
  'ed25519-receipt-v1': 'Ed25519 receipt v1 (RFC 8032)',
  'ed25519-receipt-v2': 'Ed25519 receipt v2 (RFC 8032 + draft-farley-acta-signed-receipts)',
  'ed25519-passport': 'Ed25519 Passport envelope (RFC 8032)',
  'ed25519-bundle': 'Ed25519 audit bundle',
  'voprf-token': 'VOPRF token (RFC 9497)',
  'knowledge-unit': 'Knowledge Unit bundle (draft-farley-acta-knowledge-units)',
  'gate-receipt-tuple': 'ScopeBlind Gate receipt tuple (Ed25519 over SHA-256 payload digest)',
  'gate-evidence-bundle': 'ScopeBlind Gate evidence bundle (receipt tuples + chain links)',
  'macro-track-record': 'ScopeBlind macro-engine track-record bundle (signed snapshots + completeness manifest)',
  'legate-governed-receipt': 'Legate governed receipt (Ed25519 over canonical action payload)',
  'repository-evidence': 'Exact repository review, receiver readback and recipient acceptance',
  'legate-proof-pack': 'Legate adherence / restraint proof pack (Ed25519 over canonical bytes, position-blind)',
  'trusted-context-pack': 'ScopeBlind Trusted Context Pack (signed parsed-context attestation)',
  'scopeblind-claims-v2.1.1': 'ScopeBlind Verifiable Claims v2.1.1 point-in-time artifact',
  'legate-standard': 'Legate signed standard, recipient decision, action assurance bundle, or run manifest (the site\'s own verification core, offline)',
};

// ──────────────────────────────────────────────────────────────────
// CLI argument parsing
// ──────────────────────────────────────────────────────────────────

function parseArgs() {
  const args = process.argv.slice(2);
  const opts = {
    file: null,
    publicKey: null,
    platformKeys: {},
    jwksUrl: null,
    requireKeyWindow: false,
    trustAnchor: null,
    stdin: false,
    mode: 'auto',
    bundle: false,
    json: false,
    help: false,
    version: false,
    verbose: false,
    selfTest: false,
    selfCheck: false,
    capabilities: false,
    allowEmbeddedKey: false,
    allowCarriedKey: false,
    allowLegacyCanonicalization: false,
    allowPayloadOnlyLinks: false,
    trustBundleKeys: false,
    previousFile: null,
    requireContext: [],
    disclose: [],
    disclosureFile: null,
    tier: null,
    strict: false,
    noSigil: false,
    attest: false,
    attestOrg: null,
    attestKey: null,
    pinSigil: null,
    auditLog: null,
    replayChain: null,
    emitEat: null,
    diff: null,
    auditReport: false,
    output: null,
    emitVerificationReceipt: false,
    fips: false,
    subcommand: null,
    force: false,
    proxyTarget: null,
    proxyReceiptsDir: null,
    daemonSocket: null,
    frameworkOverride: null,
    historyHead: null,
    anchorHead: null,
  };

  // A verifier that silently discards inputs is not correct, it is quiet.
  // Every subcommand takes at most one file; --diff carries a second one as a
  // flag. Any further positional is an error, never dropped.
  const setFile = (a) => {
    if (opts.file == null || opts.file === '') opts.file = a;
    else (opts.extraPositionals ??= []).push(a);
  };
  for (let i = 0; i < args.length; i++) {
    const arg = args[i];
    const next = () => args[++i];
    switch (arg) {
      case '--help':
      case '-h': opts.help = true; break;
      case '--version':
      case '-V': opts.version = true; break;
      case '--key':
      case '-k': opts.publicKey = next(); break;
      case '--platform-key': {
        const v = next() || '';
        const eq = v.indexOf('=');
        if (eq < 1 || eq === v.length - 1) { console.error('--platform-key expects <kid>=<hex public key>'); return REFUSED; }
        opts.platformKeys[v.slice(0, eq)] = v.slice(eq + 1);
        break;
      }
      case '--known-issuers': opts.knownIssuers = next(); break;
      case '--jwks': opts.jwksUrl = next(); break;
      case '--require-key-window': opts.requireKeyWindow = true; break;
      case '--trust-anchor': opts.trustAnchor = next() ?? ''; break;
      case '--history-head': opts.historyHead = next(); break;
      case '--anchor-head': opts.anchorHead = next(); break;
      case '--stdin': opts.stdin = true; break;
      case '--mode': opts.mode = next(); break;
      case '--bundle': opts.bundle = true; break;
      case '--standard': opts.standardFile = next(); break;
      case '--receipts': opts.receiptsFile = next(); break;
      case '--calls': opts.callsFile = next(); break;
      case '--regrade': (opts.regradeFiles ??= []).push(next()); break;
      case '--maintainer-key': opts.maintainerKey = next(); break;
      case '--provenance': (opts.provenanceFiles ??= []).push(next()); break;
      case '--model-calls': opts.modelCallsFile = next(); break;
      case '--model-attestation': opts.modelAttestationFile = next(); break;
      case '--json': opts.json = true; break;
      case '--verbose':
      case '-v': opts.verbose = true; break;
      case '--self-test': opts.selfTest = true; break;
      case '--self-check': opts.selfCheck = true; break;
      case '--capabilities': opts.capabilities = true; break;
      case '--allow-legacy-canonicalization': opts.allowLegacyCanonicalization = true; break;
      case '--allow-payload-only-links': opts.allowPayloadOnlyLinks = true; break;
      case '--previous': opts.previousFile = next() ?? ''; break;
      case '--allow-embedded-key': opts.allowEmbeddedKey = true; break;
      case '--allow-carried-key': opts.allowCarriedKey = true; break;
      case '--trust-bundle-keys': opts.trustBundleKeys = true; break;
      case '--require-context': opts.requireContext.push(next()); break;
      case '--disclose': opts.disclose.push(next()); break;
      case '--disclosure-file': opts.disclosureFile = next() ?? ''; break;
      case '--tier': opts.tier = Number(next()); break;
      case '--strict': opts.strict = true; break;
      case '--no-sigil': opts.noSigil = true; break;
      case '--attest': opts.attest = true; break;
      case '--attest-org': opts.attestOrg = next(); break;
      case '--attest-key': opts.attestKey = next(); break;
      case '--pin-sigil': opts.pinSigil = next(); break;
      case '--audit-log': opts.auditLog = next(); break;
      case '--replay-chain': opts.replayChain = next(); break;
      case '--emit-eat': opts.emitEat = 'json'; break;
      case '--emit-eat-cbor': opts.emitEat = 'cbor'; break;
      case '--diff': opts.diff = next(); break;
      case '--audit-report': opts.auditReport = true; break;
      case '--output': opts.output = next(); break;
      case '--emit-verification-receipt': opts.emitVerificationReceipt = true; break;
      case '--fips': opts.fips = true; break;
      case '--allow-partial-voprf': opts.allowPartialVoprf = true; break;
      case '--force': opts.force = true; break;
      case '--target': opts.proxyTarget = next(); break;
      case '--framework': opts.frameworkOverride = next(); break;
      case '--receipts-dir': opts.proxyReceiptsDir = next(); break;
      case '--socket': opts.daemonSocket = next(); break;
      case '--prompt-receipt': opts.promptReceipt = next(); break;
      case '--sigstore-bundle': opts.sigstoreBundle = next(); break;
      case '--expected-hash': opts.expectedHash = next(); break;
      case '--search-dir': opts.chainSearchDir = next(); break;
      case '--max-depth': opts.chainMaxDepth = Number(next()); break;
      case '--profile': opts.profile = next(); break;
      case '--start-date': opts.startDate = next(); break;
      case '--end-date': opts.endDate = next(); break;
      case '--org': opts.organization = next(); break;
      case '--port': opts.dashboardPort = Number(next()); break;
      case '--bind': opts.dashboardBind = next(); break;
      case '--bilateral': opts.proxyBilateral = true; break;
      case '--server-key': opts.serverKey = next(); break;
      case '--scrub-secrets': opts.scrubSecrets = true; break;
      case '--trace-id': opts.traceId = next(); break;
      case '--group-by-trace': opts.groupByTrace = true; break;
      case 'init':
      case 'proxy':
      case 'daemon':
      case 'prompt':
      case 'chain':
      case 'compliance':
      case 'dashboard':
        if (!opts.subcommand) opts.subcommand = arg;
        else if (!arg.startsWith('-')) setFile(arg);
        break;
      case 'explore':
        // `verify chain explore <file>` → subcommand stays "chain",
        // sub-subcommand captured below
        if (opts.subcommand === 'chain') opts.chainVerb = arg;
        else if (!arg.startsWith('-')) setFile(arg);
        break;
      default:
        if (!arg.startsWith('-')) setFile(arg);
        // unknown flags silently ignored (forward-compat)
    }
  }
  if (opts.extraPositionals) {
    const all = [opts.file, ...opts.extraPositionals];
    console.error(
      `verify: expected one <file.json>, got ${all.length}: ${all.join(', ')}\n` +
      `  Each receipt is verified by its own invocation. Earlier releases verified only\n` +
      `  the last file given and silently discarded the rest (exit 2, nothing verified).`
    );
    return REFUSED;
  }
  return opts;
}

function printHelp() {
  console.log(`
${bold('@veritasacta/verify')} ${PKG.version}: unified verifier for signed receipts, VOPRF tokens, and Knowledge Units

${bold('Usage:')}
  npx @veritasacta/verify <file.json>                        Auto-detect format, verify
  (exactly one file per invocation; extra positionals exit 2 rather than being ignored)
  npx @veritasacta/verify <file.json> --key <hex>            Provide verification key
  npx @veritasacta/verify <file.json> --jwks <url>           Fetch key from JWKS
  npx @veritasacta/verify <file.json> --previous <prev.json> Also check it follows the receipt before it
  npx @veritasacta/verify <file.json> --mode receipt|claims|voprf|ku|gate|gate-bundle
  npx @veritasacta/verify <bundle.json> --bundle --key <hex> Verify audit bundle
  cat receipt.json | npx @veritasacta/verify --stdin         Read from stdin
  npx @veritasacta/verify <file.json> --json                 Machine-readable output

${bold('Selective disclosure (AIP-0002 legacy):')}
  --disclose field:salt:value                               Reveal a field and verify its commitment in the _commitments
                                                            map the signature covers (an envelope's payload); one that
                                                            cannot be applied is undecidable (exit 2)

${bold('Commitment-mode disclosure (draft-farley-acta-signed-receipts-01):')}
  --disclosure-file <path.json>                             Verify Merkle inclusion proofs against committed_fields_root,
                                                            read from the signed bytes (an envelope's payload); a file
                                                            that cannot be applied is undecidable (exit 2)

${bold('Live-context verification (Sigil claim 2):')}
  --require-context clock:±5s
  --require-context geofence:inside:<polygon>
  --require-context sensor:temp<18

${bold('Subcommands:')}
  init                      Zero-config onboarding wizard (detects framework, generates keys)
  proxy --target "<cmd>"    Wrap an MCP server; sign every tools/call transparently
  daemon                    Sidecar daemon: sign receipts over a unix socket (any language)
  prompt <path>             Verify a prompt/skill/system-instruction file's provenance
                              [--prompt-receipt <r.json> | --sigstore-bundle <b.json> | --expected-hash <hex>]
  chain explore <r.json>    Walk a receipt chain to its root; verify every hash link
                              [--search-dir <dir>] [--max-depth N] [--json]
                              [--allow-payload-only-links]
  compliance                SOC 2 / ISO 42001 / EU AI Act evidence bundle from a receipt directory
                              --receipts-dir <dir> [--framework soc2|iso42001|eu-ai-act|all]
                              [--start-date ISO] [--end-date ISO] [--org "<name>"] [--output audit.html|bundle.json]
  dashboard                 Start local audit dashboard server (loopback only, no telemetry)
                              [--port 3847] [--bind 127.0.0.1] [--receipts-dir <dir>]
  proxy --target "<cmd>"    Already-present wrap-and-sign proxy. New flags:
                              [--bilateral --server-key <file>]  Cosign every receipt with a second key
                              [--scrub-secrets]  Redact api_key/token/etc in outgoing args and flag on receipt
                              [--trace-id <id>]  Stamp a workflow trace_id on every receipt

${bold('Options:')}
  --key, -k <hex>          Ed25519 public key (64 hex chars); for a VOPRF token, the issuer's
                           compressed P-256 key in base64url
  --platform-key <kid>=<hex>  Platform key for a connector context (repeatable)
  --jwks <url|file>        JWKS endpoint or file to take the signing key from, by kid
  --previous <file>        The receipt this one follows. Fails with chain_break (exit 1)
                           unless previousReceiptHash is that receipt's draft §6.7 link;
                           an absent or null link fails too. Checked beside the signature
                           and the key window, with --key or --jwks
  --require-key-window     Fail unless the key source gives the key a valid_from /
                           valid_until window (applied to the signed issued_at either way:
                           an envelope's payload.issued_at, a flat receipt's issued_at)
  --trust-anchor <file>    Not implemented, so refused (exit 2): no key was ever read
                           from the file. Pin the key with --key or --jwks <url|file>
  --history-head <hex>     Pin the expected macro track-record history head
  --anchor-head <hex>      Pin the expected signed macro anchor digest
  --mode <m>               Force mode: receipt|claims|voprf|ku|auto (default: auto)
  --bundle                 Verify as audit bundle
  --standard <file>        Legate run manifest: the signed standard to check the pins and policy against
  --receipts <file>        Legate run manifest: the gateway's receipt log (JSONL or array) to check the chain against
  --calls <file>           Legate run manifest: the calls log (JSONL), one call per receipt, to open the input digests
  --maintainer-key <hex|file>  Run manifest with --standard: pin the maintainer key that must have signed the standard (a hex key, or a maintainer-key.json); a trust root from outside the files. Refused without --standard (exit 2)
  --regrade <file>         Legate run manifest: a second grading (scopeblind.run_regrade.v1) to reconcile with the manifest; repeatable: the first is the run's own, any further one a grading made elsewhere
  --provenance <path>      Legate run manifest: Sigstore provenance bundle(s) (.sigstore.jsonl, or a directory of them), verified here against the pinned trust root; repeatable
  --model-calls <file>     Legate run manifest: the model-calls log (model-calls.jsonl), each call signed inside the model's TEE
  --model-attestation <f>  Legate run manifest: the attestation report(s) (model-attestation.json) whose Intel TDX quotes bind the signing keys; verified offline
  --stdin                  Read input from stdin
  --json                   Output JSON
  --verbose, -v            Detailed verification info
  --tier N                 Require minimum conformance tier (1-5)
  --pin-sigil <hex>        Require installed Sigil fingerprint to match
  --strict                 Disable all deprecated fallbacks. A result that rests only on a key
                           the file carries is undecidable (embedded_key_rejected, exit 2), even
                           with --allow-carried-key
  --fips                   Enforce FIPS-approved algorithms only
  --audit-log <file>       Append verification event to a local JSONL audit log
  --self-test              Verify bundled sample artifacts
  --self-check             Compare monitored verifier source with bundled commitment
  --capabilities           List supported modes/algorithms/tiers
  --allow-legacy-canonicalization  Read historical non-JCS receipts, explicitly labelled.
  --allow-payload-only-links  Read a chain link over the previous receipt's payload
                           alone as a legacy link, counted and warned: a
                           compatibility mode for chains verify 0.9.3 and earlier
                           wrote, not conformant to draft §6.7. --strict disables it
  --allow-embedded-key     DEPRECATED. Accept keys embedded in payloads.
                           Removed in v0.6.0.
  --allow-carried-key      Accept a result that rests only on a key the file carries: a Gate
                           tuple or bundle, a macro snapshot or track record, a governed receipt,
                           a proof or context pack, repository evidence, a standard file or a
                           run manifest checked without --key. Without it such a result is
                           undecidable (embedded_key_rejected, exit 2); with it, exit 0, and the
                           output says the signature proves nothing about who signed.
                           --strict refuses it
  --trust-bundle-keys      Check an audit bundle's receipts with the keys in its own
                           verification.signing_keys, reported as keySource "bundle".
                           Those keys arrive in the file being verified, so they are
                           not a trust anchor: without this flag, --key or --jwks the
                           receipts are not checked (no_public_key, exit 2). --strict
                           disables it
  --allow-partial-voprf    Treat a partial (structural-only) VOPRF result
                           as valid. Default fails closed (exit 2).
                           Full DLEQ verification lands in v0.6.0.
  --no-sigil               Suppress Sigil art in terminal output
  --help, -h
  --version, -V

${bold('Bulk / replay / diff:')}
  --replay-chain <file>    Verify every receipt in a JSONL chain file and the links
                           between them; a later receipt with no link starts a new chain.
                           Keys come from --key, or from --jwks by each receipt's kid.
                           Exits 1 if a line fails or a link breaks, else 2 if a line
                           could not be checked, else 0
  --emit-eat               Re-emit the verified receipt as an RFC 9711 EAT claims-set (JSON)
  --emit-eat-cbor          Same, as CBOR with integer claim keys
  --diff <other-file>      Show structural diff between two receipts

${bold('Attestation and audit:')}
  --attest                 Emit a signed local-verifier attestation
  --attest-org <name>      Include this org name in the attestation
  --attest-key <file>      Override attester key location
                           (default: ~/.veritasacta-verify/attester.json)
  --emit-verification-receipt
                           Emit a signed verification receipt for the subject
  --audit-report           Render an HTML audit report
  --output <file>          Write output to a file (HTML reports, attestations)

${bold('Supported formats:')}
  v1 artifacts, v2 artifacts, Passport envelopes, audit bundles,
  VOPRF tokens, Knowledge Unit bundles, selective-disclosure receipts,
  ScopeBlind Gate receipt tuples and evidence bundles (chain-link checks).

${bold('Exit codes:')}
  0  Valid: proven authentic
  1  Invalid: proven tampered
  2  Undecidable: malformed input, missing key, unsupported algorithm,
                  or --tier requirement not achieved
  A check that ran and failed makes the result invalid (1) even when another
  could not run; it is undecidable (2) only when nothing failed, as §5.3 of
  the -04 editor's copy (VeritasActa/drafts) has it.

${bold('Standards:')}
  RFC 8032 (Ed25519), RFC 8785 (JCS), RFC 9497 (VOPRF),
  RFC 7517/7638 (JWK / thumbprint),
  draft-farley-acta-signed-receipts-03,
  draft-farley-acta-knowledge-units-00,
  AIP-0001, AIP-0002, AIP-0003.

${bold('Protocol:')}  https://veritasacta.com (open, Apache-2.0)
${bold('Managed:')}   https://scopeblind.com (optional, commercial)
`);
}

function printCapabilities() {
  console.log(JSON.stringify({
    package: PKG.name,
    version: PKG.version,
    modes: Object.keys(MODE_LABELS),
    algorithms: ['ed25519', 'EdDSA', 'voprf-p256-sha256'],
    unsupported_but_recognized: ['ed25519+ml-dsa-65', 'ed25519+dilithium3'],
    tiers: [1, 2, 3, 4],
    max_tier_v0_5_0: 4,
    features: [
      'ed25519-receipt-verification',
      'voprf-token-structural-verification',
      'knowledge-unit-bundle-verification',
      'selective-disclosure-aip-0002',
      'sigil-self-check-claim-1',
      'sigil-live-context-claim-2',
      'conformance-tier-detection',
      'embedded-key-rejection',
      'key-validity-window-draft-9.2',
      'scopeblind-gate-tuple-verification',
      'scopeblind-gate-evidence-bundle-chain-checks',
      'scopeblind-claims-v2.1.1-point-in-time-artifact-verification',
    ],
    specs: [
      'RFC 8032', 'RFC 8785', 'RFC 9497', 'RFC 7517', 'RFC 7638',
      'draft-farley-acta-signed-receipts-03',
      'draft-farley-acta-knowledge-units-00',
      'AIP-0001', 'AIP-0002', 'AIP-0003',
    ],
    wayfinding: {
      protocol: 'https://veritasacta.com',
      managed: 'https://scopeblind.com',
    },
  }, null, 2));
}

// ──────────────────────────────────────────────────────────────────
// Self-check: compare installed bytes with the bundled public commitment
// ──────────────────────────────────────────────────────────────────

async function runSelfCheck() {
  const sigilPath = join(__dirname, 'sigil.json');
  let sigil;
  try {
    sigil = JSON.parse(readFileSync(sigilPath, 'utf-8'));
  } catch {
    console.log(`\n  ${red('✗')} No sigil.json found: this verifier has no Sigil commitment.`);
    console.log(`    This may be a development build or a fork.\n`);
    return 2;
  }

  let installedSourceBytes;
  try {
    installedSourceBytes = readSigilMonitoredSource(__dirname);
  } catch (error) {
    console.log(bold('@veritasacta/verify self-check'));
    console.log(`\n  ${red('✗')} ${error.message}`);
    console.log('    Refusing to compare a reduced verifier surface.\n');
    return 1;
  }

  const r = selfCheck({ sigil, installedSourceBytes });
  r.projectPublicKey = sigil.project_public_key;
  console.log(bold('@veritasacta/verify self-check'));
  console.log(formatSelfCheckResult(r));
  return r.canonical ? 0 : 1;
}

// ──────────────────────────────────────────────────────────────────
// Self-test: verify bundled samples
// ──────────────────────────────────────────────────────────────────

async function runSelfTest(opts) {
  const samplesDir = join(__dirname, 'samples');
  const testKey = 'd75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a';
  let allPassed = true;

  console.log(`\n${bold('@veritasacta/verify self-test')}\n`);
  if (!process.env.CI && !process.env.NO_COLOR) {
    console.log(renderTerminalSigil(testKey));
    console.log('');
  }

  try {
    const receipt = JSON.parse(readFileSync(join(samplesDir, 'sample-receipt.json'), 'utf-8'));
    const detected = detectFormat(receipt);
    const r = await verifyReceipt(receipt, detected.mode, { publicKey: testKey });
    if (r.valid) {
      console.log(`  ${green('✓')} Sample receipt: ${green('VALID')}  (${r.type}, kid: ${r.kid || 'n/a'})`);
    } else {
      console.log(`  ${red('✗')} Sample receipt: ${red('INVALID')}  (${r.error})`);
      allPassed = false;
    }
  } catch (e) {
    console.log(`  ${red('✗')} Sample receipt: ${red(e.message)}`);
    allPassed = false;
  }

  try {
    const bundle = JSON.parse(readFileSync(join(samplesDir, 'sample-bundle.json'), 'utf-8'));
    const r = await verifyBundle(bundle, { publicKey: testKey });
    if (r.valid) {
      console.log(`  ${green('✓')} Sample bundle:  ${green('VALID')}  (${r.passed}/${r.total} receipts)`);
    } else {
      console.log(`  ${red('✗')} Sample bundle:  ${red('INVALID')}  (${r.failed} failed)`);
      allPassed = false;
    }
  } catch (e) {
    console.log(`  ${red('✗')} Sample bundle: ${red(e.message)}`);
    allPassed = false;
  }

  console.log('');
  if (allPassed) {
    console.log(`  ${green('All self-tests passed.')} The verifier is working correctly.`);
    console.log(`  ${dim('No ScopeBlind servers were contacted. No accounts required.')}`);
  } else {
    console.log(`  ${red('Some self-tests failed.')} Check the output above.`);
  }
  console.log('');
  return allPassed ? 0 : 1;
}

// ──────────────────────────────────────────────────────────────────
// Dispatch
// ──────────────────────────────────────────────────────────────────

async function readInput(opts) {
  if (opts.stdin) {
    const chunks = [];
    for await (const chunk of process.stdin) chunks.push(chunk);
    return Buffer.concat(chunks).toString('utf-8');
  }
  if (opts.file) return readFileSync(opts.file, 'utf-8');
  return null;
}

async function dispatch(input, opts) {
  // Forced-mode overrides
  let detected = detectFormat(input);
  if (opts.mode && opts.mode !== 'auto') {
    const forced = opts.mode.toLowerCase();
    if (forced === 'receipt') detected.mode = 'ed25519-passport';
    else if (forced === 'voprf') detected.mode = 'voprf-token';
    else if (forced === 'ku') detected.mode = 'knowledge-unit';
    else if (forced === 'bundle') detected.mode = 'ed25519-bundle';
    else if (forced === 'gate') detected.mode = 'gate-receipt-tuple';
    else if (forced === 'gate-bundle') detected.mode = 'gate-evidence-bundle';
    else if (forced === 'macro' || forced === 'macro-track-record') detected.mode = 'macro-track-record';
    else if (forced === 'governed') detected.mode = 'legate-governed-receipt';
    else if (forced === 'context' || forced === 'context-pack') detected.mode = 'trusted-context-pack';
    else if (forced === 'claims' || forced === 'claims-v2.1.1') detected.mode = 'scopeblind-claims-v2.1.1';
    else if (forced === 'legate' || forced === 'standard') detected.mode = 'legate-standard';
  }
  if (opts.bundle) detected.mode = 'ed25519-bundle';

  // --previous asserts that one receipt follows another: it applies to a single receipt, never silently to anything else.
  if (opts.previousReceipt && !RECEIPT_MODES.includes(detected.mode)) {
    console.error(red(`verify: --previous checks the link of one Ed25519 receipt. This file reads as ${MODE_LABELS[detected.mode] || 'no format this verifier knows'}, so it does not apply.`));
    console.error('  Nothing was verified (exit 2).');
    return REFUSED;
  }

  // --disclosure-file and --disclose are checked against one receipt's commitments: never silently dropped elsewhere.
  if ((opts.disclosureFile !== null || opts.disclose.length > 0) && !RECEIPT_MODES.includes(detected.mode)) {
    console.error(red(`verify: ${opts.disclosureFile !== null ? '--disclosure-file' : '--disclose'} checks disclosures against one receipt's commitments. This file reads as ${MODE_LABELS[detected.mode] || 'no format this verifier knows'}, so it does not apply.`));
    console.error('  Nothing was verified (exit 2).');
    return REFUSED;
  }

  // --maintainer-key pins the key that signed the standard a run manifest is checked against, so it applies only with
  // --standard. Elsewhere it was dropped, and a run manifest or a standard verified as if the pin had held.
  if (opts.maintainerKey && !(detected.mode === 'legate-standard' && input?.type === 'scopeblind.run_manifest.v1' && opts.standardFile)) {
    console.error(red('verify: --maintainer-key pins the key that signed the standard, and applies to a run manifest checked with --standard <file>. Here it would not be applied.'));
    console.error('  To pin the key that signed a standard, a decision or a manifest itself, use --key. Nothing was verified (exit 2).');
    return REFUSED;
  }

  // --trust-bundle-keys names the keys an audit bundle carries: it applies to one, never silently to anything else.
  if (opts.trustBundleKeys && detected.mode !== 'ed25519-bundle') {
    console.error(red(`verify: --trust-bundle-keys checks an audit bundle with the keys in its verification.signing_keys. This file reads as ${MODE_LABELS[detected.mode] || 'no format this verifier knows'}, so it does not apply.`));
    console.error('  Nothing was verified (exit 2).');
    return REFUSED;
  }

  // An audit bundle takes its keys from --jwks receipt by receipt: the key set is read once, and each receipt gets the
  // key its own kid names (0.10.27; the bundle used to get the set's first key for every receipt).
  if (detected.mode === 'ed25519-bundle' && !opts.publicKey && opts.jwksUrl) {
    const loaded = await loadJwksResolver(opts.jwksUrl);
    if (loaded.error) return { valid: false, outcome: 'undecidable', error: 'jwks_fetch_failed', format: detected.mode, detail: loaded.error };
    return await verifyBundle(input, { ...opts, keyResolver: loaded.resolve });
  }

  // Resolve JWKS if needed
  let publicKey = opts.publicKey;
  let keySource = publicKey ? 'provided' : null;
  let keyWindow = null;
  let jwksFailure = null;
  if (!publicKey && opts.jwksUrl) {
    const kid = input.kid || input.signature?.kid;
    const resolved = await resolveFromJwks(opts.jwksUrl, kid);
    if (resolved.key) {
      publicKey = resolved.key;
      keySource = 'jwks';
      keyWindow = resolved.window || null;
    } else if (RECEIPT_MODES.includes(detected.mode)) {
      // A single receipt still has the checks that need no key run on it, with the key undecidable (§5.3 of the -04
      // editor's copy, VeritasActa/drafts).
      jwksFailure = resolved.error;
    } else {
      const result = {
        valid: false,
        error: 'jwks_fetch_failed',
        format: detected.mode,
        detail: resolved.error,
      };
      return result;
    }
  }

  const subOpts = { ...opts, publicKey, ...(publicKey ? { keySource } : {}), ...(jwksFailure ? { allowEmbeddedKey: false } : {}) };

  // Route to engine
  switch (detected.mode) {
    case 'ed25519-bundle': {
      return await verifyBundle(input, subOpts);
    }
    // A key given with --key (or --jwks) is pinned by each of these engines: a record signed with another is
    // key_mismatch. Without one, each verifies against the key the file carries, which is refused unless
    // --allow-carried-key accepts it.
    case 'gate-evidence-bundle': {
      const r = verifyGateBundle(input, subOpts);
      return refuseCarriedKey({ ...r, modeLabel: MODE_LABELS['gate-evidence-bundle'] }, opts, publicKey ? null : 'the bundle');
    }
    case 'macro-track-record': {
      const r = verifyMacroTrackRecord(input, subOpts);
      return refuseCarriedKey({ ...r, modeLabel: MODE_LABELS['macro-track-record'] }, opts, publicKey ? null : 'the track record');
    }
    case 'gate-receipt-tuple': {
      const r = verifyGateTuple(input, subOpts);
      return refuseCarriedKey({ ...r, modeLabel: MODE_LABELS['gate-receipt-tuple'] }, opts, publicKey ? null : 'the tuple');
    }
    case 'legate-governed-receipt': {
      const r = verifyLegateGovernedReceipt(input, subOpts);
      return refuseCarriedKey({ ...r, modeLabel: MODE_LABELS['legate-governed-receipt'] }, opts, publicKey ? null : 'the receipt');
    }
    case 'repository-evidence': {
      const r = await verifyRepositoryArtifact(input, subOpts);
      return refuseCarriedKey({ ...r, modeLabel: MODE_LABELS['repository-evidence'] }, opts, publicKey ? null : 'the evidence');
    }
    case 'legate-proof-pack': {
      const r = verifyLegateProofPack(input, subOpts);
      return refuseCarriedKey({ ...r, modeLabel: MODE_LABELS['legate-proof-pack'] }, opts, publicKey ? null : 'the pack');
    }
    case 'legate-standard': {
      // A run manifest binds to a standard and a receipt log; both are optional files beside it.
      if (input?.type === 'scopeblind.run_manifest.v1') {
        const { readFileSync } = await import('node:fs');
        // The files beside a manifest are read as the main input is: a duplicate member is refused, never resolved.
        if (opts.standardFile) subOpts.standard = parseJsonStrict(readFileSync(opts.standardFile, 'utf8'));
        if (opts.receiptsFile) {
          const text = readFileSync(opts.receiptsFile, 'utf8').trim();
          subOpts.receipts = text.startsWith('[') ? parseJsonStrict(text) : text.split('\n').filter(Boolean).map((l) => parseJsonStrict(l));
        }
        if (opts.callsFile) {
          const text = readFileSync(opts.callsFile, 'utf8').trim();
          subOpts.calls = (text.startsWith('[') ? parseJsonStrict(text) : text.split('\n').filter(Boolean).map((l) => parseJsonStrict(l))).map((c) => ({ tool: c.tool, input: c.input }));
        }
        if (opts.regradeFiles?.length) { subOpts.regrade = parseJsonStrict(readFileSync(opts.regradeFiles[0], 'utf8')); subOpts.regrades = opts.regradeFiles.slice(1).map((f) => ({ regrade: parseJsonStrict(readFileSync(f, 'utf8')), bytes: readFileSync(f) })); }
        // Provenance bundles name exact bytes, so the files as given on the command line are read again as bytes.
        if (opts.provenanceFiles?.length) {
          const { readdirSync, statSync } = await import('node:fs');
          const { join } = await import('node:path');
          const paths = opts.provenanceFiles.flatMap((p) => (statSync(p).isDirectory() ? readdirSync(p).filter((f) => /\.sigstore\.jsonl?$/.test(f)).sort().map((f) => join(p, f)) : [p]));
          const bundles = paths.flatMap((p) => readFileSync(p, 'utf8').split('\n').filter((l) => l.trim()).map((l) => parseJsonStrict(l)));
          const bytes = {};
          if (opts.file) bytes.manifest = readFileSync(opts.file);
          if (opts.standardFile) bytes.standard = readFileSync(opts.standardFile);
          if (opts.receiptsFile) bytes.receipts = readFileSync(opts.receiptsFile);
          if (opts.regradeFiles?.[0]) bytes.regrade = readFileSync(opts.regradeFiles[0]);
          subOpts.provenance = { bundles, bytes };
          if (Array.isArray(subOpts.regrades)) for (const r of subOpts.regrades) r.bundles = bundles;
        }
        if (opts.modelCallsFile) subOpts.modelCalls = readFileSync(opts.modelCallsFile, 'utf8');
        if (opts.modelAttestationFile) { const v = parseJsonStrict(readFileSync(opts.modelAttestationFile, 'utf8')); subOpts.modelAttestations = Array.isArray(v) ? v : [v]; }
        // The manifest digests the receipt log and the calls log as files, so the files given are handed over as bytes as well as records.
        const fileBytes = {};
        if (opts.receiptsFile) fileBytes.receipts = readFileSync(opts.receiptsFile);
        if (opts.callsFile) fileBytes.calls = readFileSync(opts.callsFile);
        subOpts.bytes = fileBytes;
        if (opts.maintainerKey) {
          const { existsSync } = await import('node:fs');
          let pin = opts.maintainerKey.trim();
          if (existsSync(pin)) { const raw = readFileSync(pin, 'utf8').trim(); try { const j = parseJsonStrict(raw); pin = String(j.public_key ?? j.verification_key ?? ''); } catch { pin = raw; } }
          if (!/^[0-9a-f]{64}$/i.test(pin)) { console.error('--maintainer-key: expected a 64-hex Ed25519 public key or a maintainer-key.json carrying public_key'); return REFUSED; }
          subOpts.pins = { maintainer_key: pin };
        }
      }
      const r = await verifyLegateStandard(input, subOpts);
      // A run manifest also rests on a key from outside the files when its harness key is one the standard accepts
      // and the standard is signed by the maintainer key pinned with --maintainer-key.
      const passed = (id) => Array.isArray(r.checks) && r.checks.some((c) => c.id === id && c.ok);
      const pinnedElsewhere = r.artifact_type === 'scopeblind.run_manifest.v1' && passed('maintainer_pin') && passed('harness_key');
      return refuseCarriedKey({ ...r, modeLabel: legateModeLabel(r) }, opts, publicKey || pinnedElsewhere ? null : 'the file');
    }
    case 'trusted-context-pack': {
      const r = verifyTrustedContextPack(input, subOpts);
      return refuseCarriedKey({ ...r, modeLabel: MODE_LABELS['trusted-context-pack'] }, opts, publicKey ? null : 'the pack');
    }
    case 'scopeblind-claims-v2.1.1': {
      const r = verifyClaimsArtifactV211(input, subOpts);
      return { ...r, modeLabel: MODE_LABELS['scopeblind-claims-v2.1.1'] };
    }
    case 'knowledge-unit': {
      const r = await verifyKnowledgeUnit(input, subOpts);
      const tier = detectTier({ mode: 'knowledge-unit', payloadFields: {}, valid: r.valid === true });
      return { ...r, tier };
    }
    case 'voprf-token': {
      // The engine takes the issuer key as issuerPublicKey; it was handed --key as publicKey, which it never read.
      const r = await verifyVoprfToken(input, { ...subOpts, issuerPublicKey: publicKey || undefined });
      const tier = detectTier({
        mode: 'voprf-token',
        valid: r.valid === true,
        payloadFields: {
          transport_hint: r.transport_hint,
        },
        voprfVerified: r.valid,
      });
      return { ...r, tier, modeLabel: MODE_LABELS['voprf-token'] };
    }
    case 'ed25519-browser-legacy':
    case 'ed25519-receipt-v1':
    case 'ed25519-receipt-v2':
    case 'ed25519-passport': {
      const r = await verifyReceipt(input, detected.mode, subOpts);
      // Each check's detail as the engine gave it (a malformed encoding, a carried key, the issuer), the JWKS failure in
      // place of the signature's when there was one, and below the key window's and the link's.
      const details = { ...(r.checkDetails || {}), ...(jwksFailure ? { signature: jwksFailure } : {}) };
      if (jwksFailure) r.checks.signature = { result: 'undecidable', code: 'jwks_fetch_failed' };

      // Key validity window (-04 §5.5, -03 §9.2): applied whenever the key source carries one, whatever the signature's
      // result, and reported either way, so an unchecked window is never read as a valid key.
      const kw = checkKeyWindow({ window: keyWindow, issuedAt: receiptIssuedAt(input), keySource: jwksFailure ? null : keySource || r.keySource, require: opts.requireKeyWindow });
      r.keyStatus = kw.report;
      r.checks.key_window = keyWindowCheck(kw);
      details.key_window = kw.detail;

      // --previous (-04 §6.7.1): the caller asserts this receipt follows the one supplied, so its link must be that
      // receipt's hash. The result says what the link was, whatever the other checks found.
      if (opts.previousReceipt) {
        let p;
        try {
          p = checkPreviousLink(input, opts.previousReceipt, { allowPayloadOnlyLinks: opts.allowPayloadOnlyLinks });
        } catch (e) {
          console.error(red(`verify: --previous ${opts.previousFile}: the receipt does not canonicalize (${e.message}), so it has no draft §6.7 link.`));
          console.error('  Nothing was verified (exit 2).');
          return REFUSED;
        }
        r.previous = { file: opts.previousFile, ...p };
        r.checks.previous = !p.error ? { result: 'pass' } : { result: exitCodeFor(p.error) === 1 ? 'fail' : 'undecidable', code: p.error };
        details.previous = p.detail;
        if (p.warning) r.warning = [r.warning, p.warning].filter(Boolean).join(' ');
        if (p.result === 'legacy-payload') r.conformant = false;
      }

      // -04 §5.3: invalid if any check ran and failed, undecidable if none failed and one could not run.
      const combined = combineChecks(r.checks);
      r.valid = combined.valid;
      r.outcome = combined.outcome;
      r.error = combined.error;
      if (combined.check && details[combined.check]) r.detail = details[combined.check];

      // Selective disclosure: attach if commitments present.
      // Two formats supported:
      //   - Legacy AIP-0002 (_commitments map + --disclose field:salt:value)
      //   - commitment mode, draft §6 (committed_fields_root + --disclosure-file path)
      // The committed_fields_root and the _commitments map are read from the signed bytes: an envelope's payload, where
      // draft §2.2 puts the root, or the top level of a flat receipt. A disclosure that cannot be applied (a file that
      // cannot be read or holds no disclosure, a --disclose value that does not parse, or signed bytes that carry
      // nothing to check it against) leaves the receipt undecidable, never valid with the disclosure unread (0.10.27).
      // Before, an envelope's root was not found, so a file given with it was never read, and a root or map beside an
      // envelope's payload, outside the signature, was checked against instead.
      let disclosureResult = null;
      const commitment = signedCommitment(input);
      // The AIP-0002 _commitments map is read from the signed bytes the same way (0.10.27).
      const legacy = signedLegacyCommitments(input);

      let disclosures = [];
      let notApplied = null;
      if (opts.disclosureFile !== null) {
        if (!commitment) {
          notApplied = 'the receipt\'s signed bytes carry no committed_fields_root (an envelope carries it in its payload), so there is nothing to check a disclosure against';
        } else {
          try {
            disclosures = loadDisclosuresFromText(readFileSync(opts.disclosureFile, 'utf8'));
            if (disclosures.length === 0) notApplied = 'the file holds no disclosure';
          } catch (err) {
            notApplied = `the file cannot be read as disclosures (${err?.message ?? 'unknown'})`;
          }
        }
      }
      if (notApplied) notApplied = `--disclosure-file ${opts.disclosureFile || '(no path given)'}: ${notApplied}`;
      // --disclose (AIP-0002) applies to a _commitments map in the signed bytes, and every value given must parse.
      const legacyDisclosures = parseDisclosures(opts.disclose);
      if (!notApplied && opts.disclose.length > 0) {
        if (!legacy) {
          notApplied = '--disclose: the receipt\'s signed bytes carry no _commitments map (an envelope carries it in its payload), so there is nothing to check a disclosure against';
        } else if (legacyDisclosures.length !== opts.disclose.length) {
          notApplied = '--disclose: a value is not field:salt:value, so it names no disclosure';
        }
      }
      if (commitment) {
        r.committedFieldsRoot = commitment.root;
        r.committedFieldNames = commitment.carrier.committed_field_names;
        if (r.valid !== false && !notApplied) {
          disclosureResult = verifyCommittedReceipt(commitment.carrier, disclosures);
          r.disclosedFields = disclosures.map((d) => d.name);
          if (!disclosureResult.valid) {
            r.valid = false;
            r.error = disclosureResult.error || 'commitment_mismatch';
          }
        }
      }
      if (legacy) {
        // Legacy AIP-0002 path, against the map the signature covers.
        r.redactedFields = listRedactedFields(legacy.carrier);
        if (r.valid !== false && !notApplied) {
          const legacyResult = verifySelectiveDisclosure(legacy.carrier, legacyDisclosures);
          disclosureResult = disclosureResult
            ? { ...legacyResult, valid: disclosureResult.valid && legacyResult.valid, disclosuresVerified: (disclosureResult.disclosuresVerified || 0) + legacyResult.disclosuresVerified }
            : legacyResult;
          r.disclosedFields = [...(r.disclosedFields || []), ...legacyDisclosures.map((d) => d.field)];
          if (!legacyResult.valid) {
            r.valid = false;
            r.error = r.error || 'commitment_mismatch';
          }
        }
      }
      // A failure already counted stays the outcome (-04 §5.3); otherwise a disclosure that could not be applied leaves
      // the receipt undecidable.
      if (notApplied && r.valid) {
        r.valid = false;
        r.error = 'disclosure_not_applied';
        r.detail = `${notApplied}. Nothing in it was verified.`;
      }

      // Live-context predicates
      if (opts.requireContext.length > 0) {
        const preds = parseContextArgs(opts.requireContext);
        const ctx = await evaluateLiveContext(preds);
        r.contextChecks = ctx.checks;
        if (!ctx.allSatisfied) {
          r.valid = false;
          r.error = r.error || 'context_requirement_unmet';
        }
      }

      // Surface attestation_mode as dedicated output field
      if (r.payloadFields?.attestation_mode) {
        r.attestationMode = r.payloadFields.attestation_mode;
      }
      if (r.payloadFields?.scope) r.scope = r.payloadFields.scope;
      if (r.payloadFields?.nullifier) r.nullifier = r.payloadFields.nullifier;
      if (r.payloadFields?.transport_hint) r.transport_hint = r.payloadFields.transport_hint;

      const tier = detectTier({
        mode: detected.mode,
        valid: r.valid === true,
        signatureVerified: r.valid === true,
        jcsVerified: r.valid === true && r.canonicalization === 'jcs',
        // A link is verified only against a receipt the caller supplied with --previous; otherwise it is declared.
        chainVerified: r.valid === true && r.previous?.result === 'linked',
        payloadFields: r.payloadFields,
        disclosuresVerified: disclosureResult?.disclosuresVerified || 0,
      });
      r.tier = tier;
      r.modeLabel = MODE_LABELS[detected.mode];
      r.specVersion = 'draft-farley-acta-signed-receipts-03';
      return r;
    }
    default:
      return {
        valid: false,
        error: 'unknown_format',
        format: 'unknown',
        detail: `Could not detect format. Signals: ${detected.signals.join(', ') || 'none'}`,
      };
  }
}

/**
 * Parse --disclose arguments into disclosure packages.
 * Format: "field.path:salt_hex:json_value" (value is JSON-parsed)
 */
function parseDisclosures(args) {
  const packages = [];
  for (const a of args) {
    // A value that is missing or not field:salt:value names no disclosure; the caller counts it as not applied.
    if (typeof a !== 'string') continue;
    const firstColon = a.indexOf(':');
    const secondColon = a.indexOf(':', firstColon + 1);
    if (firstColon < 0 || secondColon < 0) continue;
    const field = a.slice(0, firstColon);
    const salt = a.slice(firstColon + 1, secondColon);
    const raw = a.slice(secondColon + 1);
    let value;
    try { value = JSON.parse(raw); } catch { value = raw; }
    packages.push({ field, salt, value });
  }
  return packages;
}

// ──────────────────────────────────────────────────────────────────
// Main
// ──────────────────────────────────────────────────────────────────

function applyTierGate(result, minTier) {
  if (!minTier || result.valid !== true) return result;
  const achieved = result.valid === true ? (result.tier?.tier ?? 0) : 0;
  if (achieved < minTier) {
    return {
      ...result,
      valid: false,
      error: 'tier_not_achieved',
      detail: `Required tier T${minTier}, achieved T${achieved}`,
    };
  }
  return result;
}

/**
 * Load and parse the Sigil commitment from disk.
 * Used by attestation and report generators.
 */
function loadSigil() {
  try {
    return JSON.parse(readFileSync(join(__dirname, 'sigil.json'), 'utf-8'));
  } catch {
    return null;
  }
}

/**
 * --pin-sigil: require the installed Sigil fingerprint to match a
 * specified value. Fails early if mismatch.
 */
function enforcePinSigil(expected) {
  const sigil = loadSigil();
  if (!sigil) {
    console.error(red('--pin-sigil requires a sigil.json; none found.'));
    return REFUSED;
  }
  if (sigil.fingerprint !== expected) {
    console.error(red(`--pin-sigil: mismatch (expected ${expected}, got ${sigil.fingerprint})`));
    console.error(yellow(`Installed verifier is "${sigil.name}" (${sigil.fingerprint}); expected fingerprint ${expected}.`));
    console.error(dim(`Ensure you have installed the expected release: npm install @veritasacta/verify@<version>`));
    return REFUSED;
  }
}

/**
 * --replay-chain FILE: verify an entire JSONL chain.
 */
async function runReplayChain(opts) {
  const sigil = loadSigil();
  // Keys from --jwks: the key set is read once, and each receipt's key is the one its kid names, with its window.
  let keyResolver = null;
  if (!opts.publicKey && opts.jwksUrl) {
    const loaded = await loadJwksResolver(opts.jwksUrl);
    if (loaded.error) {
      console.error(red(`verify: --jwks ${opts.jwksUrl}: ${loaded.error}`));
      console.error('  Nothing was verified (exit 2).');
      return 2;
    }
    keyResolver = loaded.resolve;
  }
  const result = await replayChain(opts.replayChain, { ...opts, keyResolver });
  // -04 §5.3: exit 1 if any line is invalid or any link breaks, else 2 if any line could not be checked, else 0.
  const replayExit = result.outcome === 'valid' ? 0 : result.outcome === 'invalid' ? 1 : 2;

  if (opts.auditReport) {
    let attestation = null;
    if (opts.attest) {
      const r = selfCheckResult(sigil);
      attestation = buildCanonicalAttestation({
        sigil, canonical: r.canonical, org: opts.attestOrg, keyPath: opts.attestKey,
      });
    }
    const html = renderHtmlReport({ result, sigil, attestation, title: 'Veritas Acta chain-replay audit report' });
    if (opts.output) {
      writeFileSync(opts.output, html);
      console.log(dim(`wrote ${opts.output}`));
    } else {
      console.log(html);
    }
    return replayExit;
  }

  if (opts.json) {
    console.log(JSON.stringify(result, null, 2));
  } else {
    console.log(`\n${replayHeadline(result)}`);
    console.log(`\n${bold('Chain replay result')}`);
    console.log(`  Outcome:     ${result.outcome === 'valid' ? green('valid') : result.outcome === 'invalid' ? red('invalid') : yellow('not checked (undecidable)')} (exit ${replayExit})`);
    console.log(`  Total:       ${result.total}`);
    console.log(`  Verified:    ${green(String(result.verified))}`);
    console.log(`  Failed:      ${result.failed > 0 ? red(String(result.failed)) : '0'}`);
    console.log(`  Not checked: ${result.undecidable > 0 ? yellow(String(result.undecidable)) : '0'}`);
    console.log(`  Chain breaks: ${result.chainBreaks > 0 ? red(String(result.chainBreaks)) : '0'}`);
    console.log(`  Chains:      ${result.chains}`);
    if (result.legacyLinks > 0) console.log(`  Legacy links: ${yellow(String(result.legacyLinks))} (payload-only, read because --allow-payload-only-links was given: ${COMPATIBILITY_NOTE})`);
    if (result.errors.length > 0) {
      console.log(`\n  ${red('Errors:')}`);
      for (const e of result.errors.slice(0, 20)) console.log(`    ${red('•')} ${e}`);
      if (result.errors.length > 20) console.log(`    ${dim(`... ${result.errors.length - 20} more`)}`);
    }
    if (result.warnings.length > 0) {
      console.log(`\n  ${yellow('Warnings:')}`);
      for (const w of result.warnings.slice(0, 20)) console.log(`    ${yellow('•')} ${w}`);
      if (result.warnings.length > 20) console.log(`    ${dim(`... ${result.warnings.length - 20} more`)}`);
    }
    console.log('');
  }
  return replayExit;
}

/**
 * --diff A B: show structural differences between two receipts.
 */
async function runDiff(opts) {
  const a = parseJsonStrict(await readInput(opts) || '{}');
  const b = parseJsonStrict(readFileSync(opts.diff, 'utf-8'));
  const d = diffReceipts(a, b);
  if (opts.json) {
    console.log(JSON.stringify(d, null, 2));
  } else {
    console.log(`\n${bold('Receipt diff')}`);
    console.log(`  Canonical hash A: ${dim(d.canonical_hash_a)}`);
    console.log(`  Canonical hash B: ${dim(d.canonical_hash_b)}`);
    console.log(`  Payload identical: ${d.hash_equal ? green('yes') : red('no')}`);
    console.log(`  Signature identical: ${d.signature_equal ? green('yes') : red('no')}`);
    if (d.added.length > 0) console.log(`\n  ${green('Added:')}     ${d.added.join(', ')}`);
    if (d.removed.length > 0) console.log(`  ${red('Removed:')}   ${d.removed.join(', ')}`);
    if (d.changed.length > 0) {
      console.log(`  ${yellow('Changed:')}`);
      for (const c of d.changed) {
        console.log(`    ${c.field}: ${dim(JSON.stringify(c.before))} -> ${dim(JSON.stringify(c.after))}`);
      }
    }
    console.log('');
  }
  return d.hash_equal && d.signature_equal ? 0 : 1;
}

/**
 * verify prompt <file> [--prompt-receipt <r> | --sigstore-bundle <b> | --expected-hash <h>]
 *
 * Verify the provenance of a prompt / instruction file against one of
 * three sources. Closes the CLAUDE.md / SKILLS.md supply-chain gap.
 */
async function runPromptVerify(opts) {
  if (!opts.file) {
    console.error(red('  verify prompt requires a file path to the prompt'));
    console.error(dim('  usage: verify prompt <path> [--prompt-receipt <receipt.json> | --sigstore-bundle <bundle.json> | --expected-hash <hex>]'));
    return 2;
  }
  const result = await verifyPrompt({
    promptPath: opts.file,
    receiptPath: opts.promptReceipt,
    sigstoreBundle: opts.sigstoreBundle,
    expectedHash: opts.expectedHash,
  });

  if (opts.json) {
    console.log(JSON.stringify(result, null, 2));
  } else {
    console.log('');
    console.log(`${bold('Prompt verification')}`);
    console.log(`  File:      ${result.prompt_path}`);
    console.log(`  Hash:      ${dim(result.prompt_hash)}`);
    if (result.source) console.log(`  Source:    ${result.source}`);
    if (result.expected_hash) {
      const eq = result.expected_hash === result.prompt_hash;
      console.log(`  Expected:  ${dim(result.expected_hash)} ${eq ? green('match') : red('MISMATCH')}`);
    }
    if (result.receipt_summary) {
      console.log(`  Receipt:   ${dim(JSON.stringify(result.receipt_summary))}`);
    }
    if (result.bundle_summary) {
      console.log(`  Bundle:    ${dim(JSON.stringify(result.bundle_summary))}`);
    }
    if (result.valid) {
      console.log(`  ${green('\u2713')} prompt matches the asserted provenance`);
    } else if (result.outcome === 'undecidable') {
      console.log(`  ${yellow('?')} not checked (${result.error}): ${result.detail || 'the signature was not checked'}`);
    } else {
      console.log(`  ${red('\u2717')} ${result.error || 'verification failed'}`);
    }
    console.log('');
  }
  // A hash matched in a receipt or a bundle whose signature was not checked is undecidable (exit 2), never valid.
  return exitOk(result) ? 0 : result.outcome === 'undecidable' ? 2 : 1;
}

/**
 * verify chain explore <file> [--search-dir <dir>] [--max-depth N]
 *
 * Walk the causal ancestry of a receipt via previousReceiptHash and
 * validate every hash link along the way. Surfaces cryptographic
 * causal integrity as a concrete operation.
 */
async function runChainExplore(opts) {
  if (opts.chainVerb !== 'explore') {
    console.error(red(`  unknown chain subcommand: ${opts.chainVerb || '(none)'}`));
    console.error(dim('  usage: verify chain explore <receipt.json> [--search-dir <dir>] [--max-depth N]'));
    return 2;
  }
  if (!opts.file) {
    console.error(red('  verify chain explore requires a receipt file path'));
    return 2;
  }
  const result = await exploreChain({
    receiptPath: opts.file,
    searchDir: opts.chainSearchDir,
    maxDepth: opts.chainMaxDepth,
    allowPayloadOnlyLinks: opts.allowPayloadOnlyLinks,
  });

  if (opts.json) {
    console.log(JSON.stringify(result, null, 2));
  } else {
    console.log(renderChainTree(result));
  }
  // A link refused for its form exits as the receipt verifier would: 1 malformed, 2 an unimplemented algorithm.
  return exitOk(result) ? 0 : result.code ? exitCodeFor(result.code) : 1;
}

/**
 * verify compliance [--framework soc2|iso42001|eu-ai-act|all]
 *                   --receipts-dir <dir> [--start-date ISO] [--end-date ISO]
 *                   [--org "<name>"] [--output <file>] [--json]
 *
 * Produce a compliance evidence bundle: control-mapped receipt
 * summaries, HTML audit report suitable for auditors.
 */
async function runCompliance(opts) {
  const dir = opts.proxyReceiptsDir || opts.receiptsDir || opts.file;
  if (!dir) {
    console.error(red('  verify compliance requires --receipts-dir <dir>'));
    console.error(dim('  usage: verify compliance --receipts-dir <dir> [--framework soc2|iso42001|eu-ai-act|all]'));
    console.error(dim('                            [--start-date ISO] [--end-date ISO] [--org "<name>"] [--output <file>] [--json]'));
    return 2;
  }
  let result;
  try {
    result = exportCompliance({
      receiptsDir: dir,
      framework: opts.frameworkOverride || 'all',
      startDate: opts.startDate,
      endDate: opts.endDate,
      organizationName: opts.organization,
    });
  } catch (err) {
    console.error(red(`  compliance export failed: ${err.message}`));
    return 2;
  }

  if (opts.output) {
    const isHtml = opts.output.endsWith('.html');
    const body = isHtml
      ? renderComplianceHTML(result)
      : JSON.stringify(result, null, 2);
    writeFileSync(opts.output, body);
    console.log(green(`  ✓ Compliance bundle written to ${opts.output}`));
    console.log(dim(`  Receipts scanned: ${result.manifest.receipts_scanned} / in window: ${result.manifest.receipts_in_window}`));
    for (const [fwId, fw] of Object.entries(result.manifest.frameworks)) {
      const evidenced = Object.values(fw.controls).filter((c) => c.evidence_count > 0).length;
      const total = Object.keys(fw.controls).length;
      console.log(dim(`  ${fw.framework}: ${evidenced}/${total} controls evidenced`));
    }
    return;
  }

  if (opts.json) {
    console.log(JSON.stringify(result, null, 2));
    return;
  }

  // Terminal rendering
  console.log('');
  console.log(bold('Compliance evidence bundle'));
  console.log(`  Organization: ${result.manifest.organization}`);
  console.log(`  Receipts:     ${result.manifest.receipts_scanned} scanned, ${result.manifest.receipts_in_window} in window`);
  if (result.manifest.window.start || result.manifest.window.end) {
    console.log(`  Window:       ${result.manifest.window.start || '(begin)'} → ${result.manifest.window.end || '(end)'}`);
  }
  for (const [, fw] of Object.entries(result.manifest.frameworks)) {
    console.log('');
    console.log(bold(`  ${fw.framework}`));
    for (const [ctrlId, ctrl] of Object.entries(fw.controls)) {
      const mark = ctrl.evidence_count > 0 ? green('●') : dim('○');
      console.log(`    ${mark} ${ctrlId}  ${ctrl.name}  ${dim(`(${ctrl.evidence_count})`)}`);
    }
  }
  if (result.warnings.length) {
    console.log('');
    console.log(yellow('  Warnings:'));
    for (const w of result.warnings) console.log(`    • ${w}`);
  }
  console.log('');
}

/**
 * verify dashboard [--port 3847] [--bind 127.0.0.1] [--receipts-dir <dir>]
 *
 * Spin up the local dashboard server. Opens a browser tab to it.
 * Binds loopback only.
 */
async function runDashboard(opts) {
  const receiptsDir = opts.proxyReceiptsDir || opts.receiptsDir;
  let dash;
  try {
    dash = await startDashboard({
      port: opts.dashboardPort || 3847,
      bind: opts.dashboardBind || '127.0.0.1',
      receiptsDir,
    });
  } catch (err) {
    console.error(red(`  dashboard failed to start: ${err.message}`));
    return 2;
  }
  console.log('');
  console.log(bold('  Veritas Acta dashboard'));
  console.log(`  Serving at: ${dash.url}`);
  if (receiptsDir) {
    console.log(`  Receipts:   ${receiptsDir}`);
  } else {
    console.log(dim(`  Receipts:   (none: paste JSON or drop files in the UI)`));
  }
  console.log(dim('  Loopback-only. No TLS, no auth, no telemetry.'));
  console.log(dim('  Press Ctrl+C to stop.'));
  console.log('');

  // Stay alive until interrupted.
  await new Promise(() => {});
}

function selfCheckResult(sigil) {
  if (!sigil) return { canonical: false, integrityMatches: false };
  try {
    const installedSourceBytes = readSigilMonitoredSource(__dirname);
    return selfCheck({ sigil, installedSourceBytes });
  } catch (error) {
    return {
      canonical: false,
      integrityMatches: false,
      sourceMatches: false,
      policyMatches: false,
      sigilMatches: false,
      missingMonitoredSurface: true,
      error: error.message,
    };
  }
}

async function main() {
  const opts = parseArgs();
  if (opts === REFUSED) return 2;

  if (opts.help) { printHelp(); return 0; }
  if (opts.version) { console.log(PKG.version); return 0; }
  if (opts.capabilities) { printCapabilities(); return 0; }

  // --trust-anchor was parsed and never read, so no key was ever taken from the file: a receipt was then refused for
  // want of a key, and a bundle, a Gate record or an embedded key verified against the keys it carried itself. A trust
  // input the verifier cannot apply is refused rather than dropped.
  if (opts.trustAnchor !== null) {
    console.error(red(`verify: --trust-anchor is not implemented, so no key would be read from ${opts.trustAnchor || 'the file'}.`));
    console.error('  Earlier releases accepted the flag and ignored it. Pin the key with --key <hex>, or with --jwks <url|file>');
    console.error('  for a single file. Nothing was verified (exit 2).');
    return 2;
  }

  // --strict disables every compatibility fallback, on every path. It is applied before any subcommand or replay
  // runs: earlier releases applied it to a single file only, so --replay-chain kept the fallbacks it was given to drop.
  if (opts.strict) {
    opts.allowLegacyCanonicalization = false;
    opts.allowPayloadOnlyLinks = false;
    if (opts.allowEmbeddedKey) {
      console.error(yellow('Warning: --strict overrides --allow-embedded-key (embedded keys always rejected in strict mode).'));
      opts.allowEmbeddedKey = false;
    }
    if (opts.trustBundleKeys) {
      console.error(yellow('Warning: --strict overrides --trust-bundle-keys (a bundle\'s own keys are never used in strict mode).'));
      opts.trustBundleKeys = false;
    }
    if (opts.allowCarriedKey) {
      console.error(yellow('Warning: --strict overrides --allow-carried-key (a key the file carries is never accepted in strict mode).'));
    }
  }

  // --trust-bundle-keys applies to an audit bundle alone, and --disclosure-file and --disclose to one receipt. Each is
  // refused where it would be dropped, as --previous is.
  const elsewhere = opts.replayChain ? '--replay-chain' : opts.subcommand ? `verify ${opts.subcommand}` : opts.diff ? '--diff'
    : opts.selfCheck ? '--self-check' : opts.selfTest ? '--self-test' : null;
  if (opts.trustBundleKeys && elsewhere) {
    console.error(red(`verify: --trust-bundle-keys checks an audit bundle with the keys it carries, and does not apply to ${elsewhere}.`));
    console.error('  Nothing was verified (exit 2).');
    return 2;
  }
  const notOneReceipt = elsewhere || (opts.bundle ? '--bundle' : null);
  if ((opts.disclosureFile !== null || opts.disclose.length > 0) && notOneReceipt) {
    console.error(red(`verify: ${opts.disclosureFile !== null ? '--disclosure-file' : '--disclose'} checks disclosures against one receipt's commitments, and does not apply to ${notOneReceipt}.`));
    console.error('  Nothing was verified (exit 2).');
    return 2;
  }

  // --previous names the receipt this one follows. It is read before anything is verified, and refused where it would
  // otherwise be dropped: --replay-chain reads the order from the file, and the subcommands verify other things.
  if (opts.previousFile !== null) {
    const other = opts.replayChain ? '--replay-chain' : opts.subcommand ? `verify ${opts.subcommand}` : opts.diff ? '--diff'
      : opts.bundle ? '--bundle' : opts.selfCheck ? '--self-check' : opts.selfTest ? '--self-test' : null;
    if (!opts.previousFile || other) {
      console.error(red(!opts.previousFile
        ? 'verify: --previous needs the file of the receipt this one follows.'
        : `verify: --previous checks one receipt against the receipt before it, and does not apply to ${other}.`));
      if (opts.replayChain) console.error('  --replay-chain reads the order from the file and checks every link in it.');
      console.error('  Nothing was verified (exit 2).');
      return 2;
    }
    try {
      opts.previousReceipt = parseReceiptJson(readFileSync(opts.previousFile, 'utf-8'), { maxBytes: 50 * 1024 * 1024, maxDepth: 128 });
    } catch (e) {
      console.error(red(`verify: --previous ${opts.previousFile}: ${e.message}`));
      console.error('  Nothing was verified (exit 2).');
      return 2;
    }
    if (!opts.previousReceipt || typeof opts.previousReceipt !== 'object' || Array.isArray(opts.previousReceipt)) {
      console.error(red(`verify: --previous ${opts.previousFile} holds no receipt: a receipt is one JSON object.`));
      console.error('  Nothing was verified (exit 2).');
      return 2;
    }
  }

  if (opts.pinSigil && enforcePinSigil(opts.pinSigil) === REFUSED) return 2;

  // Subcommands
  if (opts.subcommand === 'init') {
    const result = await runInit({ framework: opts.frameworkOverride, org: opts.attestOrg, force: opts.force });
    if (result.status === 'exists') {
      console.error(yellow(result.message));
      return 1;
    }
    console.log('');
    if (!process.env.CI && !process.env.NO_COLOR) {
      console.log(renderTerminalSigil(result.key.pubHex));
      console.log('');
    }
    console.log(`${green('✓')} ${bold('Veritas Acta initialized')}`);
    console.log(`  Directory: ${result.vaDir}`);
    console.log(`  Kid:       ${result.key.kid}`);
    console.log(`  Pubkey:    ${result.key.pubHex}`);
    if (result.detection) {
      console.log(`  Framework: ${green(result.detection.framework)} (${result.detection.language})`);
    } else {
      console.log(`  Framework: ${yellow('not auto-detected')}; see manual setup below`);
    }
    console.log('');
    console.log(bold('Next steps:'));
    for (const line of buildNextSteps(result.detection, result.config)) {
      console.log(`  ${line}`);
    }
    console.log('');
    console.log(dim(`Protocol: https://veritasacta.com`));
    console.log(dim(`Managed:  https://scopeblind.com (optional)`));
    console.log('');
    return 0;
  }

  if (opts.subcommand === 'proxy') {
    const keyPath = opts.attestKey || join(process.cwd(), '.veritasacta', 'attester.json');
    const code = await runProxy({
      target: opts.proxyTarget,
      key: keyPath,
      receiptsDir: opts.proxyReceiptsDir,
      scrubSecrets: opts.scrubSecrets,
      bilateral: opts.proxyBilateral,
      serverKey: opts.serverKey,
      traceId: opts.traceId,
    });
    // The relay goes on reading stdin after the child has exited, so the proxy exits once the child's output is written.
    exitWhenWritten(code);
    return;
  }

  if (opts.subcommand === 'daemon') {
    await runDaemon({
      socket: opts.daemonSocket,
      key: opts.attestKey,
      receiptsDir: opts.proxyReceiptsDir,
    });
    return;
  }

  if (opts.subcommand === 'prompt') {
    return runPromptVerify(opts);
  }

  if (opts.subcommand === 'chain') {
    return runChainExplore(opts);
  }

  if (opts.subcommand === 'compliance') {
    return runCompliance(opts);
  }

  if (opts.subcommand === 'dashboard') {
    return runDashboard(opts);
  }

  if (opts.selfCheck) return runSelfCheck();
  if (opts.selfTest) return runSelfTest(opts);
  if (opts.replayChain) return runReplayChain(opts);
  if (opts.diff) return runDiff(opts);

  // --attest without a file: emit a standalone local-integrity attestation.
  // The wire type and legacy `canonical` field remain compatibility aliases.
  if (opts.attest && !opts.file && !opts.stdin) {
    const sigil = loadSigil();
    const r = selfCheckResult(sigil);
    const att = buildCanonicalAttestation({
      sigil, canonical: r.canonical, org: opts.attestOrg, keyPath: opts.attestKey,
    });
    const output = JSON.stringify(att, null, 2);
    if (opts.output) { writeFileSync(opts.output, output); console.error(dim(`wrote ${opts.output}`)); }
    else console.log(output);
    return 0;
  }

  const raw = await readInput(opts);
  if (raw === null) {
    console.error(red('Error: no input file specified.'));
    console.error('Usage: npx @veritasacta/verify <file.json> [--key <hex>]');
    return 2;
  }

  let input;
  try {
    input = [...CLAIMS_V211_TYPES].some((type) => raw.includes(type))
      ? parseClaimsJsonV211Independent(raw)
      : parseReceiptJson(raw, { maxBytes: 50 * 1024 * 1024, maxDepth: 128 });
  } catch (e) {
    console.error(red(`Error: invalid JSON: ${e.message}`));
    return 2;
  }

  let result = await dispatch(input, opts);
  if (result === REFUSED) return 2;
  result = applyTierGate(result, opts.tier);

  // FIPS mode: a valid result stands only when every algorithm the engine verified is FIPS-approved. The algorithm is
  // the one the engine reports it verified, never a label in the file: earlier releases read the unsigned top-level
  // `algorithm` member before verifying, so an Ed25519 record labelled ml-dsa-65 passed. A result that names no
  // algorithm cannot be confirmed and is refused. A result that does not pass anyway is reported as it is.
  if (opts.fips && exitOk(result)) {
    const algorithms = verifiedAlgorithms(result);
    const refused = algorithms.length === 0
      ? { algorithm: null, reason: 'This format does not report the algorithm it verified, so FIPS mode cannot confirm it.' }
      : algorithms.map((a) => ({ algorithm: a, ...fipsStatus(a) })).find((f) => !f.approved);
    if (refused) {
      const rejection = {
        valid: false,
        error: 'unsupported_algorithm',
        detail: `FIPS mode: ${refused.reason}`,
        format: 'fips-rejected',
        fips: { algorithms, approved: false },
      };
      if (opts.json) console.log(JSON.stringify(rejection, null, 2));
      else {
        console.error(red(refused.algorithm ? `✗ FIPS mode rejects algorithm "${refused.algorithm}"` : '✗ FIPS mode cannot confirm the algorithm'));
        console.error(yellow(refused.reason));
      }
      return 2;
    }
    result.fips = { algorithms, approved: true };
  }
  // The checks made after a receipt's own (a disclosure, a live-context predicate, --tier) can still fail it, so the
  // outcome is read again from the final result: a failure of any of them is invalid, one that could not run is
  // undecidable (-04 §5.3).
  if (result && typeof result.outcome === 'string') {
    result.outcome = result.valid === true ? 'valid' : exitCodeFor(result.error) === 1 ? 'invalid' : 'undecidable';
  }

  // Attach error metadata
  if (result.error) {
    const meta = getError(result.error);
    if (meta) result.errorMeta = meta;
  }

  // EAT output mode (A4): re-serialize the verified receipt as an RFC 9711 EAT
  // claims-set so it is also a valid EAT/TRACE record (JSON names, or CBOR with
  // integer claim keys). Authenticity round-trips to the embedded Acta receipt.
  if (opts.emitEat) {
    const { emitEatJson, emitEatCbor } = await import('./src/output/eat.js');
    const out = opts.emitEat === 'cbor' ? emitEatCbor(input, result) : emitEatJson(input, result);
    if (opts.output) {
      writeFileSync(opts.output, out);
      console.error(dim(`wrote ${opts.output}`));
    } else {
      console.log(out);
    }
    return exitOk(result) ? 0 : result.valid ? 1 : exitCodeFor(result.error);
  }

  // Audit log
  if (opts.auditLog) {
    const sigil = loadSigil();
    try {
      // Each entry chains to the one before it. Before, no previous hash was passed, so every entry was hashed as if it
      // were the first and the chain hash chained nothing.
      appendAuditEntry(opts.auditLog, result, { sigil, org: opts.attestOrg, prevHash: lastChainHash(opts.auditLog) });
    } catch (e) {
      console.error(yellow(`Warning: failed to append audit log: ${e.message}`));
    }
  }

  // Audit report (HTML)
  if (opts.auditReport) {
    const sigil = loadSigil();
    let attestation = null;
    if (opts.attest) {
      const r = selfCheckResult(sigil);
      attestation = buildCanonicalAttestation({
        sigil, canonical: r.canonical, org: opts.attestOrg, keyPath: opts.attestKey,
      });
    }
    const html = renderHtmlReport({ result, sigil, attestation });
    if (opts.output) {
      writeFileSync(opts.output, html);
      console.error(dim(`wrote ${opts.output}`));
    } else {
      console.log(html);
    }
    return exitOk(result) ? 0 : result.valid ? 1 : exitCodeFor(result.error);
  }

  // Resolve a human label for the signer key, if one is known. Display aid only;
  // it never changes the verification result.
  if (result && typeof result === 'object' && typeof result.publicKey === 'string') {
    const issuers = loadKnownIssuers(opts.knownIssuers, join(__dirname, 'known-issuers.json'));
    const label = labelFor(result.publicKey, issuers);
    if (label) result.signerLabel = label;
  }

  // Output
  if (opts.json) {
    const obj = JSON.parse(formatAsJson(result));
    // Optionally attach emitted artifacts
    if (opts.attest) {
      const sigil = loadSigil();
      const r = selfCheckResult(sigil);
      obj.canonical_attestation = buildCanonicalAttestation({
        sigil, canonical: r.canonical, org: opts.attestOrg, keyPath: opts.attestKey,
      });
    }
    if (opts.emitVerificationReceipt && result.valid) {
      const sigil = loadSigil();
      obj.verification_receipt = buildVerificationReceipt({
        subjectResult: result, sigil, keyPath: opts.attestKey,
      });
    }
    console.log(JSON.stringify(obj, null, 2));
  } else {
    // A result accepted with --allow-carried-key says so first: its signature proves nothing about who signed.
    if (result.carriedKeyOnly && result.valid) console.log(yellow(`\n! ${CARRIED_KEY_NOTICE}`));
    if (result.format === 'knowledge-unit') console.log(formatKuResult(result, opts));
    else if (result.format === 'gate-evidence-bundle') console.log(formatGateBundleResult(result, opts));
    else if (result.format === 'macro-track-record') console.log(formatMacroTrackRecordResult(result, opts));
    else if (result.format === 'gate-tuple') console.log(formatGateTupleResult(result, opts));
    else if (result.format === 'legate-governed-receipt') console.log(formatGovernedReceiptResult(result, opts));
    else if (result.format === 'trusted-context-pack') console.log(formatTrustedContextPackResult(result, opts));
    else if (result.artifact_type === 'scopeblind.run_manifest.v1' || result.format === 'repository-evidence') console.log(formatRunManifestResult(result, opts));
    else if (result.total !== undefined) console.log(formatBundleResult(result, opts));
    else console.log(formatReceiptResult(result, opts));

    // Surface attestation artifacts separately for terminal mode
    if (opts.attest) {
      const sigil = loadSigil();
      const r = selfCheckResult(sigil);
      const att = buildCanonicalAttestation({
        sigil, canonical: r.canonical, org: opts.attestOrg, keyPath: opts.attestKey,
      });
      if (opts.output) {
        writeFileSync(opts.output, JSON.stringify(att, null, 2));
        console.error(dim(`wrote local-integrity attestation to ${opts.output}`));
      } else {
        console.log(`${bold('Local-integrity attestation:')}`);
        console.log(JSON.stringify(att, null, 2));
        console.log('');
      }
    }
    if (opts.emitVerificationReceipt && result.valid) {
      const sigil = loadSigil();
      const vr = buildVerificationReceipt({ subjectResult: result, sigil, keyPath: opts.attestKey });
      console.log(`${bold('Verification receipt:')}`);
      console.log(JSON.stringify(vr, null, 2));
      console.log('');
    }
  }

  // Exit. A result flagged `_partial: true` has NOT been fully
  // cryptographically verified (e.g. VOPRF tokens whose DLEQ proof
  // check is structural-only in this release). By default we fail
  // closed with exit code 2 (undecidable). Callers who explicitly
  // want the partial result surfaced as "valid" can opt in with
  // --allow-partial-voprf.
  if (result.valid) {
    if (result._partial && !opts.allowPartialVoprf) {
      if (!opts.json) {
        console.error(red(
          '\n  Exit 2: partial verification is not a full cryptographic check.\n' +
          '  Pass --allow-partial-voprf to treat a partial result as valid.\n'
        ));
      }
      return 2;
    }
    if (!exitOk(result)) {
      if (!opts.json) console.error(red(`\n  Exit 1: the file verifies on its own, but does not bind to what was supplied (${result.binding}). Read the failed checks above.\n`));
      return 1;
    }
    return 0;
  }
  // -04 §5.3: the exit status tells the three outcomes apart.
  return result.outcome === 'invalid' ? 1 : result.outcome === 'undecidable' ? 2 : exitCodeFor(result.error);
}

// main() returns the exit status, and the process ends by itself once stdout and stderr have taken everything written
// to them (see exitWhenWritten).
main().then(
  (code) => { if (code !== undefined) process.exitCode = code; },
  (e) => {
    console.error(red(`Fatal error: ${e.message}`));
    if (process.env.DEBUG) console.error(e.stack);
    process.exitCode = 2;
  },
);