fini-proof 0.3.0

package/src/report.mjs

@@ -0,0 +1,73 @@
+// Output formats: text (humans), json (the evidence record itself), sarif (GitHub code scanning, SARIF 2.1.0).
+// Reads evidence@1 and evidence@2 (the @2 fields go through evidence.mjs so an @1 record renders unchanged).
+import { ENGINES, TOOL_VERSION } from './runner.mjs'
+import { propertyId, snapshotOf } from './evidence.mjs'
+
+const useColor = () => process.stdout.isTTY && !process.env.NO_COLOR
+const c = (code, s) => (useColor() ? `\x1b[${code}m${s}\x1b[0m` : s)
+const VERDICT_STYLE = { PASS: '1;32', FAIL: '1;31', NOT_MEASURED: '1;33' }
+
+export function toText(r, { evidencePath } = {}) {
+  const L = []
+  L.push(`fini-proof ${TOOL_VERSION} · run ${r.runId}`)
+  const snap = r.snapshot ? snapshotOf(r) : null
+  L.push(`commit ${r.repo.commit || (r.repo.git ? '(no commit yet)' : '(not a git repo)')}${r.repo.dirty ? ' (+ uncommitted changes)' : ''}${snap?.tree_hash ? ` · tree ${snap.tree_hash.slice(0, 12)}` : ''} · scope ${r.scope.mode || '-'}${r.scope.base ? ` vs ${r.scope.base}` : ''} · fail-on ${r.failOn}`)
+  const m = r.attestation?.maker
+  if (m && m.source !== 'git-author' && m.source !== 'none') L.push(`maker ${m.kind}:${m.id}${m.model ? ` (${m.model})` : ''} · verifier fini-proof ${r.attestation.verifier?.version || TOOL_VERSION}`)
+  L.push('')
+  for (const e of r.engines) {
+    const nc = e.controls.filter((x) => x.kind === 'negative')
+    const ctl = nc.length ? `${nc.filter((x) => x.ok).length}/${nc.length} negative controls caught` : 'controls not run'
+    const st = c(e.status === 'MEASURED' ? '32' : e.status === 'NOT_MEASURED' ? '33' : '90', e.status.padEnd(14))
+    L.push(`  ${e.id.padEnd(13)} ${st} ${String(e.filesScanned).padStart(5)} files · ${ctl}${e.findings ? ` · ${e.findings} finding(s)` : ''}`)
+    if (e.reason) L.push(`                ${e.reason}`)
+  }
+  if (r.findings.length) {
+    L.push('')
+    L.push('Findings')
+    for (const f of r.findings) {
+      const sev = f.severity.toUpperCase()
+      L.push(`  ${c(f.blocking ? '31' : '90', sev.padEnd(6))} ${f.file}:${f.line}  ${c('1', f.rule)}  [${f.engine}]`)
+      L.push(`         ${f.message}`)
+      L.push(`         proof:   ${f.proof}`)
+      L.push(`         control: ${f.negativeControl}  (npx fini-proof negctl ${f.negativeControl})`)
+    }
+  }
+  L.push('')
+  const n = (st) => r.engines.filter((e) => e.status === st).length
+  const notRun = [n('NO_SCOPE') && `${n('NO_SCOPE')} with no changed file in scope`, n('NOT_APPLICABLE') && `${n('NOT_APPLICABLE')} not applicable`].filter(Boolean)
+  L.push(`VERDICT: ${c(VERDICT_STYLE[r.verdict], r.verdict)}${r.summary ? ` — ${r.summary.blocking} blocking / ${r.summary.findings} finding(s), ${r.summary.enginesMeasured}/${r.engines.length} engines measured${notRun.length ? ` (${notRun.join(', ')})` : ''}` : ''}`)
+  if (r.verdict === 'NOT_MEASURED' && r.reason) L.push(`  why: ${r.reason}`)
+  if (evidencePath) L.push(`evidence: ${evidencePath}  (sha256 ${r.evidenceDigest.slice(0, 16)}…)`)
+  return L.join('\n')
+}
+
+const SARIF_LEVEL = { high: 'error', medium: 'warning', low: 'note', info: 'note' }
+
+export function toSarif(r) {
+  const rules = new Map()
+  for (const f of r.findings) {
+    const id = `${f.engine}/${f.rule}`
+    if (!rules.has(id)) rules.set(id, { id, name: f.rule, shortDescription: { text: `${f.rule} (${f.engine})` }, fullDescription: { text: f.message }, defaultConfiguration: { level: SARIF_LEVEL[f.severity] }, properties: { negativeControl: f.negativeControl } })
+  }
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: { driver: { name: 'fini-proof', version: TOOL_VERSION, informationUri: 'https://finipe.com/fini-proof', rules: [...rules.values()] } },
+      automationDetails: { id: `fini-proof/${r.runId}` },
+      versionControlProvenance: r.repo.commit ? [{ repositoryUri: 'file:///', revisionId: r.repo.commit }] : undefined,
+      invocations: [{ executionSuccessful: r.verdict !== 'NOT_MEASURED', properties: { verdict: r.verdict, evidenceDigest: r.evidenceDigest, schema: r.schema, treeHash: snapshotOf(r).tree_hash, maker: r.attestation?.maker || null, engines: r.engines.map((e) => ({ id: e.id, version: e.version, sha256: e.sha256, status: e.status, reason: e.reason })) } }],
+      results: r.findings.map((f) => ({
+        ruleId: `${f.engine}/${f.rule}`,
+        level: SARIF_LEVEL[f.severity],
+        message: { text: `${f.message}\nProof: ${f.proof}\nNegative control: ${f.negativeControl}` },
+        locations: [{ physicalLocation: { artifactLocation: { uri: f.file }, region: { startLine: f.line } } }],
+        partialFingerprints: { finiProof: `${f.engine}:${f.rule}:${f.file}:${f.line}` },
+        properties: { propertyId: propertyId(f), proof: f.proof, negativeControl: f.negativeControl, blocking: f.blocking },
+      })),
+    }],
+  }
+}
+
+export const engineIds = () => ENGINES.map((e) => e.id)

package/src/runner.mjs

@@ -0,0 +1,306 @@
+// The verdict engine. Order per engine: negative controls (a planted defect MUST be caught) and positive controls
+// (a clean input MUST stay clean) run FIRST; an engine that fails either is NOT_MEASURED — a check that cannot
+// fail is not evidence. Then the engine scans the in-scope files. Any unreadable in-scope file makes the engine
+// NOT_MEASURED (never silently skipped — finipe check-entrypoint-guard.mjs, Codex §17.19b).
+import { createHash, randomUUID } from 'node:crypto'
+import { readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { performance } from 'node:perf_hooks'
+import { fileURLToPath } from 'node:url'
+import { git, globToRegExp, listFiles, loadBaseline, loadConfig, repoInfo } from './files.mjs'
+import { EVIDENCE_SCHEMA, computeDigest, makerFrom, verifierFrom } from './evidence.mjs'
+import hollow from './engines/hollow-tests.mjs'
+import gitleaks from './engines/gitleaks.mjs'
+import secrets from './engines/secrets.mjs'
+import failOpen from './engines/fail-open.mjs'
+import skipRatchet from './engines/skip-ratchet.mjs'
+import tenantFilter from './engines/tenant-filter.mjs'
+import migrations from './engines/migrations.mjs'
+
+export const TOOL_VERSION = '0.3.0'
+// Order matters in one place: an orchestrated engine runs before the built-in engine it `replaces` (gitleaks → secrets).
+export const ENGINES = [hollow, gitleaks, secrets, failOpen, skipRatchet, tenantFilter, migrations]
+const ENGINE_FILES = {
+  'hollow-tests': ['engines/hollow-tests.mjs', 'engines/vendor/vacuous-spec-core.mjs'],
+  gitleaks: ['engines/gitleaks.mjs', 'engines/secrets.mjs', 'engines/vendor/secrets-core.mjs'],
+  secrets: ['engines/secrets.mjs', 'engines/vendor/secrets-core.mjs'],
+  'fail-open': ['engines/fail-open.mjs', 'engines/vendor/entrypoint-guard-core.mjs', 'engines/vendor/vacuous-spec-core.mjs'],
+  'skip-ratchet': ['engines/skip-ratchet.mjs', 'engines/vendor/vacuous-spec-core.mjs'],
+  'tenant-filter': ['engines/tenant-filter.mjs', 'engines/migrations.mjs', 'engines/vendor/migration-invariants-core.mjs', 'engines/vendor/vacuous-spec-core.mjs'],
+  migrations: ['engines/migrations.mjs', 'engines/vendor/migration-invariants-core.mjs'],
+}
+const SRC_DIR = path.dirname(fileURLToPath(import.meta.url))
+const MAX_BYTES = 5 * 1024 * 1024
+export const SEVERITY_RANK = { info: 0, low: 1, medium: 2, high: 3 }
+
+export const sha256 = (s) => createHash('sha256').update(s).digest('hex')
+
+export function engineDigest(id) {
+  const h = createHash('sha256')
+  for (const f of ENGINE_FILES[id] || []) h.update(readFileSync(path.join(SRC_DIR, f)))
+  return h.digest('hex')
+}
+
+/**
+ * Run one engine over an in-memory file set; applies finalize (ratchet) with the given baseline. An orchestrated
+ * engine (engines/gitleaks.mjs, SSOT PART 9) scans the whole set at once via scanRepo and returns findings with `file`.
+ */
+export function scanWith(engine, files, ctx) {
+  let findings = []
+  if (engine.scanRepo) {
+    for (const f of engine.scanRepo(files, ctx)) findings.push({ ...f, engine: engine.id })
+  } else {
+    for (const { rel, content } of files) {
+      for (const f of engine.scanFile(rel, content, ctx)) findings.push({ ...f, file: rel, engine: engine.id })
+    }
+  }
+  let measurements = {}
+  if (engine.finalize) ({ findings, measurements } = engine.finalize(findings, ctx))
+  return { findings, measurements }
+}
+
+export function runControl(engine, control, kind, root) {
+  const ctx = { root, baseline: {}, ...(control.ctx || {}) }
+  const t0 = performance.now()
+  let findings = null
+  let error = null
+  // A control that throws (an external engine crashed, timed out) is a control that did not pass — never skipped.
+  try { ({ findings } = scanWith(engine, [{ rel: control.file, content: control.content }], ctx)) } catch (e) { error = e.message }
+  const ms = Math.round((performance.now() - t0) * 1000) / 1000
+  const got = findings ? findings.map((f) => f.rule) : []
+  const errorField = error === null ? {} : { error }
+  if (kind === 'negative') {
+    const caught = !!findings && findings.some((f) => f.rule === control.expect)
+    return { id: control.id, kind, expect: control.expect, ok: caught, got, ms, ...errorField }
+  }
+  return { id: control.id, kind, ...(control.rule ? { rule: control.rule } : {}), ok: !!findings && findings.length === 0, got, ms, ...errorField }
+}
+
+/** evidence@2 `nc_results[]` of an engine record, from the control runs that gated it (no second run). */
+export const ncResultsOf = (controls) => controls.filter((c) => c.kind === 'negative').map((c) => ({ id: c.id, expect: c.expect, caught: c.ok, ms: c.ms }))
+
+/** The same ignore rule for check() and for `state` (what a proof's scope may contain). */
+export function scopeFilter(cfg) {
+  const ignoreRes = [/^\.fini-proof\//, ...cfg.ignore.map(globToRegExp)]
+  return (f) => !ignoreRes.some((re) => re.test(f))
+}
+
+/** evidence@2 snapshot: the git HEAD tree. Not a git repo / no commit → NOT_MEASURED (the per-file hashes remain). */
+export function snapshotOf(root, info) {
+  if (!info.git) return { tree_hash: null, commit: null, dirty: null, status: 'NOT_MEASURED', reason: 'not a git repository: no tree hash (inputs.perFile still identifies every file that was checked)' }
+  const t = git(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{tree}'])
+  if (!t.ok || !t.out) return { tree_hash: null, commit: null, dirty: info.dirty, status: 'NOT_MEASURED', reason: 'the repository has no commit yet: no tree hash' }
+  return { tree_hash: t.out, commit: info.commit, dirty: info.dirty, status: 'MEASURED', ...(info.dirty ? { reason: 'uncommitted changes: tree_hash is the HEAD tree; inputs.perFile holds the bytes that were checked' } : {}) }
+}
+
+export function runControls(engine, root = process.cwd()) {
+  return [
+    ...engine.negativeControls.map((c) => runControl(engine, c, 'negative', root)),
+    ...(engine.positiveControls || []).map((c) => runControl(engine, c, 'positive', root)),
+  ]
+}
+
+/** A cached, fail-closed reader over the repository (an error is recorded, never swallowed). */
+export function makeReader(root) {
+  const cache = new Map()
+  const read = (rel) => {
+    if (!cache.has(rel)) {
+      try {
+        const st = statSync(path.join(root, rel))
+        if (st.size > MAX_BYTES) cache.set(rel, { error: `larger than ${MAX_BYTES} bytes` })
+        else cache.set(rel, { content: readFileSync(path.join(root, rel), 'utf8') })
+      } catch (e) { cache.set(rel, { error: e.code || e.message }) }
+    }
+    return cache.get(rel)
+  }
+  return { read, cache }
+}
+
+/**
+ * Whole-repository context an engine needs before it scans (e.g. which tables are multi-tenant). Runs over the FULL
+ * listing even in --base mode: a changed query is judged against the whole schema, not just the changed files.
+ * Returns { ctx, measurements } or { unmeasured } / { notApplicable }.
+ */
+export function prepareEngine(engine, { root, cfg, allFiles, read }) {
+  // (read may be an engine-scoped wrapper that records which files this engine looked at — evidence@2 scope_files)
+  const base = { exists: (rel) => allFiles.has(rel), read: (rel) => read(rel).content }
+  if (!engine.prepare) return { ctx: base }
+  const p = engine.prepare({ root, config: cfg.raw || {}, files: [...allFiles], read })
+  return { ...p, ctx: { ...base, ...(p.ctx || {}) } }
+}
+
+function proofCommand(f) {
+  return `npx fini-proof prove --engine ${f.engine} --file ${JSON.stringify(f.file)} --line ${f.line}`
+}
+
+export function check(root, opts = {}) {
+  const startedAt = new Date().toISOString()
+  const failOnName = opts.failOn || 'high'
+  const failOn = failOnName === 'none' ? Infinity : SEVERITY_RANK[failOnName]
+  if (failOn === undefined) throw new Error(`--fail-on must be one of high|medium|low|none (got ${failOnName})`)
+  const cfg = loadConfig(root)
+  const baseline = loadBaseline(root)
+  const info = repoInfo(root)
+  let listed = listFiles(root, { base: opts.base })
+  if (opts.only && opts.only.length && !listed.unmeasured) {
+    // --only: exactly these files (an editor / agent hook checking the file it just wrote). Missing = not in repo.
+    const want = new Set(opts.only.map((f) => path.relative(root, path.resolve(root, f)).split(path.sep).join('/')))
+    listed = { ...listed, files: listed.files.filter((f) => want.has(f)), mode: 'files', only: [...want] }
+  }
+  const selected = (opts.engines && opts.engines.length) ? ENGINES.filter((e) => opts.engines.includes(e.id)) : ENGINES
+  const result = {
+    schema: EVIDENCE_SCHEMA,
+    runId: randomUUID(),
+    tool: { name: 'fini-proof', version: TOOL_VERSION, node: process.version },
+    startedAt,
+    repo: { ...info, rootCommitDigest: info.rootCommit ? sha256(info.rootCommit) : sha256(path.resolve(root)) },
+    scope: { mode: listed.mode || null, ...(listed.only ? { only: listed.only } : {}), base: opts.base || null, baseCommit: listed.baseCommit || null, mergeBase: listed.mergeBase || null, ignore: cfg.ignore, config: cfg.source },
+    snapshot: snapshotOf(root, info),
+    failOn: failOnName,
+    engines: [],
+    findings: [],
+    inputs: { files: 0, digest: null, perFile: {} },
+  }
+  const attest = () => { result.attestation = { maker: makerFrom({ explicit: opts.maker, gitAuthor: info.author }), verifier: verifierFrom({ version: TOOL_VERSION, engines: result.engines }) } }
+  if (listed.unmeasured) {
+    result.verdict = 'NOT_MEASURED'
+    result.reason = listed.unmeasured
+    attest()
+    return finish(result)
+  }
+  const keep = scopeFilter(cfg)
+  const files = listed.files.filter(keep)
+  const { read, cache } = makeReader(root)
+  let allFiles = null
+  const all = () => {
+    if (!allFiles) allFiles = new Set(listed.mode === 'full' || listed.mode === 'full-walk' ? files : (listFiles(root).files || []).filter(keep))
+    return allFiles
+  }
+  for (const engine of selected) {
+    const er = { id: engine.id, version: engine.version, title: engine.title, provenance: engine.provenance, sha256: engineDigest(engine.id), controls: [], nc_results: [], scope_files: [], status: 'MEASURED', filesScanned: 0 }
+    result.engines.push(er)
+    // Orchestration contract (engines/gitleaks.mjs): a built-in engine yields to the orchestrated engine that replaces
+    // it when that engine was MEASURED in this run; an external engine that is absent is NOT_APPLICABLE before its
+    // controls, and its binary fingerprint is part of the engine digest (a new binary = a new verifier).
+    const primary = result.engines.find((x) => x.status === 'MEASURED' && selected.some((e) => e.id === x.id && e.replaces === engine.id))
+    if (primary) { er.status = 'NOT_APPLICABLE'; er.reason = `${primary.id} passed its negative controls and is the primary check this run; ${engine.id} is the fallback (SSOT PART 9)`; continue }
+    if (engine.precondition) {
+      const pc = engine.precondition()
+      if (pc.notApplicable) { er.status = 'NOT_APPLICABLE'; er.reason = pc.notApplicable; continue }
+      if (pc.unmeasured) { er.status = 'NOT_MEASURED'; er.reason = pc.unmeasured; continue }
+      if (pc.identity) { er.external = pc.identity; er.sha256 = sha256(`${er.sha256}\n${pc.identity.sha256}`) }
+    }
+    const controls = runControls(engine, root)
+    er.controls = controls
+    er.nc_results = ncResultsOf(controls)
+    const badControl = controls.find((c) => !c.ok)
+    if (badControl) {
+      er.status = 'NOT_MEASURED'
+      er.reason = badControl.error
+        ? `${badControl.kind} control ${badControl.id} could not run (${badControl.error}) — this check cannot be shown to fail, so its silence is not evidence`
+        : badControl.kind === 'negative'
+        ? `negative control ${badControl.id} was NOT caught (planted ${badControl.expect}, got [${badControl.got}]) — this check cannot fail, so its silence is not evidence`
+        : `positive control ${badControl.id} raised [${badControl.got}] on a clean input — this check cannot be trusted`
+      continue
+    }
+    const touched = new Set()
+    const readE = (rel) => { touched.add(rel); return read(rel) }
+    const scopeOut = () => { er.scope_files = [...touched].filter((rel) => cache.get(rel)?.content !== undefined).sort() }
+    const prep = prepareEngine(engine, { root, cfg, allFiles: all(), read: readE })
+    if (prep.measurements) er.measurements = prep.measurements
+    if (prep.unmeasured) { er.status = 'NOT_MEASURED'; er.reason = prep.unmeasured; continue }
+    if (prep.notApplicable) { er.status = 'NOT_APPLICABLE'; er.reason = prep.notApplicable; continue }
+    const inScope = files.filter((f) => engine.appliesTo(f))
+    const unreadable = []
+    const loaded = []
+    for (const rel of inScope) {
+      const r = readE(rel)
+      if (r.error) unreadable.push(`${rel} (${r.error})`)
+      else loaded.push({ rel, content: r.content })
+    }
+    er.filesScanned = loaded.length
+    scopeOut()
+    if (unreadable.length) {
+      er.status = 'NOT_MEASURED'
+      er.reason = `${unreadable.length} in-scope file(s) could not be read: ${unreadable.slice(0, 5).join(', ')} — an unread file is not a clean file`
+      continue
+    }
+    if (loaded.length === 0) {
+      if (listed.mode === 'diff' || listed.mode === 'files') { er.status = 'NO_SCOPE'; er.reason = 'no changed file is in this engine\'s scope' }
+      else if (engine.optionalScope) { er.status = 'NOT_APPLICABLE'; er.reason = engine.notApplicableReason }
+      else { er.status = 'NOT_MEASURED'; er.reason = 'no file in this repository is in this engine\'s scope — an empty scan is not a pass' }
+      continue
+    }
+    try {
+      const { findings, measurements } = scanWith(engine, loaded, { root, baseline, ...prep.ctx })
+      er.measurements = { ...(er.measurements || {}), ...measurements }
+      const nc = engine.negativeControls
+      for (const f of findings) {
+        const ctl = nc.find((c) => c.expect === f.rule)
+        result.findings.push({
+          ...f,
+          property_id: `${f.engine}/${f.rule}`,
+          negativeControl: ctl ? ctl.id : nc[0].id,
+          proof: proofCommand(f),
+          blocking: SEVERITY_RANK[f.severity] >= failOn,
+        })
+      }
+      er.findings = findings.length
+    } catch (e) {
+      er.status = 'NOT_MEASURED'
+      er.reason = `engine crashed: ${e.message}`
+    }
+  }
+  for (const [rel, r] of cache) if (r.content !== undefined) result.inputs.perFile[rel] = sha256(r.content)
+  result.inputs.files = Object.keys(result.inputs.perFile).length
+  result.inputs.digest = sha256(Object.entries(result.inputs.perFile).sort().map(([k, v]) => `${v}  ${k}`).join('\n'))
+  const blocking = result.findings.filter((f) => f.blocking).length
+  const unmeasured = result.engines.filter((e) => e.status === 'NOT_MEASURED')
+  result.summary = { findings: result.findings.length, blocking, enginesMeasured: result.engines.filter((e) => e.status === 'MEASURED').length, enginesNotMeasured: unmeasured.length }
+  if (blocking > 0) result.verdict = 'FAIL'
+  else if (unmeasured.length > 0) { result.verdict = 'NOT_MEASURED'; result.reason = unmeasured.map((e) => `${e.id}: ${e.reason}`).join('; ') }
+  else result.verdict = 'PASS'
+  attest()
+  return finish(result)
+}
+
+function finish(result) {
+  result.finishedAt = new Date().toISOString()
+  delete result.evidenceDigest
+  result.evidenceDigest = computeDigest(result)
+  return result
+}
+
+export const EXIT = { PASS: 0, FAIL: 1, USAGE: 2, NOT_MEASURED: 3, LICENCE: 4 }
+
+/**
+ * Re-run one engine on one file (the `prove` command, the MCP explain_finding tool). Controls first: an engine whose
+ * control fails proves nothing. Returns { status: 'NOT_MEASURED', reason } | { status: 'OK', hits, content, sha }.
+ */
+export function prove(root, engineId, file, line = null) {
+  const engine = ENGINES.find((e) => e.id === engineId)
+  if (!engine) return { status: 'USAGE', reason: `unknown engine ${engineId}` }
+  const pc = engine.precondition ? engine.precondition() : {}
+  if (pc.notApplicable || pc.unmeasured) return { status: 'NOT_MEASURED', reason: `${engine.id}: ${pc.notApplicable || pc.unmeasured}` }
+  const bad = runControls(engine, root).find((c) => !c.ok)
+  if (bad) return { status: 'NOT_MEASURED', reason: `${engine.id} control ${bad.id} failed; this check cannot prove anything` }
+  const { read } = makeReader(root)
+  const r = read(file)
+  if (r.error) return { status: 'NOT_MEASURED', reason: `cannot read ${file}: ${r.error}` }
+  const listed = listFiles(root)
+  const prep = prepareEngine(engine, { root, cfg: loadConfig(root), allFiles: new Set(listed.files || []), read })
+  if (prep.unmeasured || prep.notApplicable) return { status: 'NOT_MEASURED', reason: prep.unmeasured || prep.notApplicable }
+  let findings
+  try { ({ findings } = scanWith(engine, [{ rel: file, content: r.content }], { root, baseline: loadBaseline(root), ...prep.ctx })) } catch (e) { return { status: 'NOT_MEASURED', reason: `${engine.id} crashed: ${e.message}` } }
+  const hits = findings.filter((f) => line === null || f.line === line)
+  return { status: 'OK', engine, hits, content: r.content, sha: sha256(r.content) }
+}
+
+/** The rule catalogue (list_rules / explain_finding): every engine, its rules, provenance and controls. */
+export function ruleCatalogue() {
+  return ENGINES.map((e) => ({
+    engine: e.id, version: e.version, title: e.title, provenance: e.provenance,
+    rules: Object.entries(e.rules || {}).map(([id, r]) => ({ id, ...r, negativeControl: (e.negativeControls.find((c) => c.expect === id) || {}).id || null })),
+    negativeControls: e.negativeControls.map((c) => c.id),
+  }))
+}

package/src/state.mjs

@@ -0,0 +1,189 @@
+// `fini-proof state` — Proof State v0, local form (SSOT PART 5 and PART 13 NOW-3).
+//
+// Five states per property (property = "<engine>/<rule>"), no sixth:
+//   PROVEN        the engine passed ALL its controls in that run, the rule has its OWN negative control that was
+//                 caught and its OWN positive control (nearest clean look-alike, `rule` on the control) that stayed
+//                 clean in that run, and no finding of the rule exists in the engine's scope
+//   FAILED        a finding of severity medium/high exists (each carries a proof command); `blocking` says whether
+//                 it failed the run under --fail-on
+//   NOT_MEASURED  the engine was not MEASURED (a control failed, unreadable file, not applicable, no scope …), or
+//                 the rule lacks its own negative or positive control. `cause` says which; a NOT_APPLICABLE engine
+//                 stays NOT_MEASURED here (SSOT PART 5: five states, no sixth) with cause 'engine-not-applicable'
+//   STALE         derived at READ time only (`--against`): the record said PROVEN/FAILED, but a file in the proof's
+//                 scope changed (per-file sha256 differs, deleted, or a new in-scope file appeared in a full-scope
+//                 proof) or the engine digest changed since. The fix is the next run.
+//   ADVISORY      the rule's severity is low/info (e.g. TENANT_FILTER_UNPROVEN, SKIPPED_TEST): a recommendation,
+//                 never rendered as PROVEN, never blocking
+//
+// Two modes:
+//   fini-proof state                      run the licensed check now (same path as `check`) and report its states
+//   fini-proof state --against <file>     run NOTHING: verify that evidence file's digest, derive its states, and
+//                                         mark STALE whatever the working tree has invalidated since
+// Reuse: states are derived from the evidence record itself (evidence.mjs readers accept @1 and @2), file hashing
+// uses the runner's fail-closed reader, the scope uses the runner's ignore filter and the engines' own appliesTo.
+import path from 'node:path'
+import { ncResults, propertyId, scopeFiles, snapshotOf } from './evidence.mjs'
+import { listFiles, loadConfig } from './files.mjs'
+import { ENGINES, engineDigest, makeReader, scopeFilter, sha256 } from './runner.mjs'
+
+export const STATES = Object.freeze(['PROVEN', 'FAILED', 'NOT_MEASURED', 'STALE', 'ADVISORY'])
+export const STATE_SCHEMA = 'fini-proof/state@1'
+const RANK = { info: 0, low: 1, medium: 2, high: 3 }
+const FULL_MODES = new Set(['full', 'full-walk'])
+
+/** Per-property states of one evidence record (no file-system access). */
+export function deriveStates(doc, engines = ENGINES) {
+  const rows = []
+  const snap = snapshotOf(doc)
+  const findingsBy = new Map()
+  for (const f of doc.findings || []) {
+    const id = propertyId(f)
+    if (!findingsBy.has(id)) findingsBy.set(id, [])
+    findingsBy.get(id).push(f)
+  }
+  for (const er of doc.engines || []) {
+    const mod = engines.find((e) => e.id === er.id)
+    const catalogue = mod?.rules || {}
+    const ruleIds = new Set([...Object.keys(catalogue), ...(doc.findings || []).filter((f) => f.engine === er.id).map((f) => f.rule)])
+    const ncs = ncResults(er)
+    const controls = er.controls || []
+    // Trust only what the record shows: MEASURED *and* every control it ran passed (a status alone is not enough).
+    const engineOk = er.status === 'MEASURED' && controls.length > 0 && controls.every((c) => c.ok === true) && ncs.every((n) => n.caught === true)
+    const { files: scope, source: scopeSource } = scopeFiles(er, doc)
+    for (const rule of [...ruleIds].sort()) {
+      const pid = `${er.id}/${rule}`
+      const fs = findingsBy.get(pid) || []
+      const nc = ncs.find((n) => n.expect === rule) || null
+      const pc = controls.find((c) => c.kind === 'positive' && c.rule === rule) || null
+      const sev = catalogue[rule]?.severity || fs.reduce((m, f) => (RANK[f.severity] > RANK[m] ? f.severity : m), 'info')
+      const row = {
+        property: pid, engine: er.id, rule, severity: sev, state: null, reason: null,
+        runId: doc.runId, snapshot: snap.tree_hash ?? null, commit: snap.commit ?? null,
+        engineVersion: er.version ?? null, engineDigest: er.sha256 ?? null, engineStatus: er.status,
+        ncId: nc ? nc.id : null, pcId: pc ? pc.id : null, cause: null, findings: fs.length, blocking: fs.filter((f) => f.blocking).length,
+        provenAt: null, scope, scopeSource,
+      }
+      const serious = fs.filter((f) => RANK[f.severity] >= RANK.medium)
+      if (!engineOk) {
+        row.state = 'NOT_MEASURED'
+        row.cause = er.status === 'MEASURED' ? 'control-failed' : er.status === 'NOT_APPLICABLE' ? 'engine-not-applicable' : er.status === 'NO_SCOPE' ? 'no-scope' : 'engine-not-measured'
+        row.reason = er.status === 'MEASURED' ? 'the record shows a control that did not pass — nothing from this engine is proof' : `${er.status}${er.reason ? `: ${er.reason}` : ''}`
+      } else if (serious.length) {
+        row.state = 'FAILED'
+        row.reason = `${serious.length} finding(s); re-run: ${serious[0].proof}`
+      } else if (RANK[sev] <= RANK.low || fs.length) {
+        row.state = 'ADVISORY'
+        row.reason = fs.length ? `${fs.length} low/info finding(s) — a recommendation, not a proof` : 'low/info rule — advisory only, never shown as proven'
+      } else if (!nc) {
+        row.state = 'NOT_MEASURED'
+        row.cause = 'missing-negative-control'
+        row.reason = 'no negative control plants this rule, so it has not been shown able to fail'
+      } else if (!pc) {
+        row.state = 'NOT_MEASURED'
+        row.cause = 'missing-positive-control'
+        row.reason = 'no positive control is this rule\'s clean look-alike, so a detector too lax for it would go unseen'
+      } else if (nc.caught !== true || pc.ok !== true) {
+        row.state = 'NOT_MEASURED'
+        row.cause = 'control-failed'
+        row.reason = nc.caught !== true ? `negative control ${nc.id} was not caught` : `positive control ${pc.id} raised a finding`
+      } else {
+        row.state = 'PROVEN'
+        row.provenAt = doc.finishedAt || null
+      }
+      rows.push(row)
+    }
+  }
+  return rows
+}
+
+/**
+ * Read-time invalidation: PROVEN/FAILED rows whose scope changed on disk (or whose engine changed) become STALE.
+ * Unchanged rows keep their state. Returns the same rows (mutated) for convenience.
+ */
+export function applyStaleness(rows, doc, root, engines = ENGINES) {
+  const { read } = makeReader(root)
+  const recorded = doc.inputs?.perFile || {}
+  const now = new Map()
+  const hashNow = (rel) => {
+    if (!now.has(rel)) { const r = read(rel); now.set(rel, r.error ? null : sha256(r.content)) }
+    return now.get(rel)
+  }
+  // Files in the repository now, under the same ignore rule — to see NEW in-scope files for a full-scope proof.
+  let current = null
+  const currentFiles = () => {
+    if (current === null) {
+      const listed = listFiles(root)
+      current = listed.unmeasured ? [] : listed.files.filter(scopeFilter(loadConfig(root)))
+    }
+    return current
+  }
+  const fullScope = FULL_MODES.has(doc.scope?.mode)
+  for (const row of rows) {
+    if (row.state !== 'PROVEN' && row.state !== 'FAILED') continue
+    const changed = []
+    for (const rel of row.scope) {
+      const h = hashNow(rel)
+      if (h === null) changed.push({ file: rel, change: 'deleted or unreadable' })
+      else if (h !== recorded[rel]) changed.push({ file: rel, change: 'modified' })
+    }
+    const mod = engines.find((e) => e.id === row.engine)
+    if (fullScope && mod && row.scopeSource === 'engine') {
+      const inScope = new Set(row.scope)
+      for (const rel of currentFiles()) if (mod.appliesTo(rel) && !inScope.has(rel)) changed.push({ file: rel, change: 'added' })
+    }
+    let engineChanged = null
+    if (mod && !mod.external && row.engineDigest && engineDigest(mod.id) !== row.engineDigest) engineChanged = `engine ${mod.id} changed since the proof (digest ${row.engineDigest.slice(0, 12)}… → ${engineDigest(mod.id).slice(0, 12)}…)`
+    if (!changed.length && !engineChanged) continue
+    row.previousState = row.state
+    row.state = 'STALE'
+    row.invalidatedBy = { files: changed.slice(0, 50), filesChanged: changed.length, ...(engineChanged ? { engine: engineChanged } : {}) }
+    row.reason = [changed.length ? `${changed.length} covered file(s) changed: ${changed.slice(0, 3).map((c) => `${c.file} (${c.change})`).join(', ')}${changed.length > 3 ? ', …' : ''}` : null, engineChanged].filter(Boolean).join('; ')
+  }
+  return rows
+}
+
+export function summarise(rows) {
+  const out = Object.fromEntries(STATES.map((s) => [s, rows.filter((r) => r.state === s).length]))
+  const causes = {}
+  for (const r of rows) if (r.state === 'NOT_MEASURED') causes[r.cause] = (causes[r.cause] || 0) + 1
+  out.notMeasuredBy = causes
+  return out
+}
+
+/** The JSON document `state --format json` prints. `scope` lists are replaced by counts to keep it readable. */
+export function stateDocument(doc, rows, { mode, evidencePath, root }) {
+  return {
+    schema: STATE_SCHEMA,
+    mode,
+    generatedAt: new Date().toISOString(),
+    evidence: { path: evidencePath ? path.relative(root, evidencePath) : null, schema: doc.schema, runId: doc.runId, evidenceDigest: doc.evidenceDigest, finishedAt: doc.finishedAt || null, snapshot: snapshotOf(doc) },
+    summary: summarise(rows),
+    properties: rows.map(({ scope, ...r }) => ({ ...r, scopeFiles: scope.length })),
+  }
+}
+
+const ORDER = ['FAILED', 'STALE', 'NOT_MEASURED', 'ADVISORY', 'PROVEN']
+export function stateText(sd) {
+  const L = []
+  const snap = sd.evidence.snapshot
+  L.push(`fini-proof state · ${sd.mode === 'against' ? 'as of now, against' : 'this run'} ${sd.evidence.runId} · tree ${snap.tree_hash ? snap.tree_hash.slice(0, 12) : `(none: ${snap.reason})`} · ${sd.evidence.schema}`)
+  L.push('')
+  for (const st of ORDER) {
+    const rows = sd.properties.filter((x) => x.state === st)
+    // An engine that did not run leaves every one of its properties NOT_MEASURED for the same reason: one line each.
+    const whole = st === 'NOT_MEASURED' ? [...new Set(rows.filter((x) => x.engineStatus !== 'MEASURED').map((x) => x.engine))] : []
+    for (const eng of whole) {
+      const g = rows.filter((x) => x.engine === eng)
+      L.push(`  ${st.padEnd(13)} ${`${eng}/* (${g.length} properties)`.padEnd(40)} ${g[0].reason}`)
+    }
+    for (const p of rows.filter((x) => !whole.includes(x.engine))) {
+      const extra = p.state === 'PROVEN' ? `controls ${p.ncId} + ${p.pcId} · ${p.scopeFiles} file(s)` : p.reason
+      L.push(`  ${p.state.padEnd(13)} ${p.property.padEnd(40)} ${p.previousState ? `(was ${p.previousState}) ` : ''}${extra || ''}`)
+    }
+  }
+  L.push('')
+  const nmBy = Object.entries(sd.summary.notMeasuredBy || {}).map(([k, v]) => `${v} ${k}`).join(', ')
+  L.push(`STATE: ${ORDER.map((s) => `${s} ${sd.summary[s]}${s === 'NOT_MEASURED' && nmBy ? ` (${nmBy})` : ''}`).join(' · ')}`)
+  L.push('ADVISORY is a recommendation, never a proof. STALE means re-run `fini-proof check`. Only PROVEN is proven.')
+  return L.join('\n')
+}

package/src/upload.mjs

@@ -0,0 +1,85 @@
+// `fini-proof check --upload`: send the run's evidence to the Finipe Developer workspace (POST <api>/runs).
+// The upload is a COPY of evidence that is already on disk. It never changes the verdict or the exit code: a
+// failed upload is a warning on stderr, and the local evidence file stays the record.
+import { spawnSync } from 'node:child_process'
+import { gzipSync } from 'node:zlib'
+import path from 'node:path'
+import { TOOL_VERSION } from './runner.mjs'
+
+export const DEFAULT_API = 'https://developer.finipe.com/api/v1/fini-proof'
+// Same rules the server applies (backend fini-proof-evidence.ts), so a bad name fails here with a clear message.
+const REPOSITORY_RE = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/
+const BRANCH_RE = /^[^\s\x00-\x1f]{1,255}$/
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1'])
+
+function git(root, args) {
+  const r = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' })
+  return r.status === 0 ? r.stdout.trim() : ''
+}
+
+/** `owner/name` from the origin remote (https, ssh or scp form), else the directory name. */
+export function repositoryName(root, explicit) {
+  if (explicit) return String(explicit).trim()
+  if (process.env.FINI_PROOF_REPOSITORY) return process.env.FINI_PROOF_REPOSITORY.trim()
+  const url = git(root, ['remote', 'get-url', 'origin'])
+  const m = /[:/]([^/:]+\/[^/]+?)(?:\.git)?\/?$/.exec(url)
+  if (m) return m[1]
+  return path.basename(path.resolve(root))
+}
+
+function branchName(root) {
+  const env = process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || process.env.CI_COMMIT_REF_NAME || process.env.BITBUCKET_BRANCH || process.env.BRANCH_NAME
+  const b = env || git(root, ['rev-parse', '--abbrev-ref', 'HEAD'])
+  return b && b !== 'HEAD' && BRANCH_RE.test(b) ? b : null
+}
+
+/**
+ * Upload `result` (the evidence object `check` just wrote). Returns { ok, status?, runId?, error? } and never throws.
+ * The API key is sent only in the Authorization header, and only over https (plain http is allowed for a local
+ * server only, so a key is never sent in clear text across a network).
+ */
+/** Opt-in gzip: `--upload-gzip` or FINI_PROOF_UPLOAD_GZIP=1. Opt-in because the server must accept Content-Encoding. */
+export const gzipWanted = (flag, env = process.env) => flag === true || /^(1|true|yes)$/i.test(env.FINI_PROOF_UPLOAD_GZIP || '')
+
+export async function uploadEvidence(result, { root, repository, api, key, timeoutMs = 15_000, gzip = false } = {}) {
+  const apiKey = key ?? process.env.FINI_PROOF_API_KEY
+  if (!apiKey) return { ok: false, error: 'FINI_PROOF_API_KEY is not set' }
+  const base = String(api || process.env.FINI_PROOF_API || DEFAULT_API).replace(/\/+$/, '')
+  let url
+  try { url = new URL(`${base}/runs`) } catch { return { ok: false, error: `FINI_PROOF_API is not a URL: ${base}` } }
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOCAL_HOSTS.has(url.hostname))) {
+    return { ok: false, error: `refusing to send the API key over ${url.protocol} to ${url.hostname} (https only, http only for localhost)` }
+  }
+  const name = repositoryName(root, repository)
+  if (!REPOSITORY_RE.test(name)) return { ok: false, error: `repository name "${name}" is not valid — set --repository <owner/name> or FINI_PROOF_REPOSITORY` }
+  const branch = branchName(root)
+  const payload = JSON.stringify({ ...result, repository: name, source: process.env.CI ? 'ci' : 'cli', ...(branch ? { branch } : {}) })
+  // Evidence grows ~156 bytes per checked file (per-file sha256 + per-engine scope, both needed for STALE); gzip cuts
+  // it ~3x. The bytes the server verifies are the JSON after decompression, so the digest is unaffected.
+  const body = gzip ? gzipSync(payload) : payload
+
+  const ctrl = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs)
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', ...(gzip ? { 'content-encoding': 'gzip' } : {}), 'user-agent': `fini-proof/${TOOL_VERSION}` },
+      body,
+      signal: ctrl.signal,
+    })
+    const text = await res.text()
+    let json = null
+    try { json = JSON.parse(text) } catch { json = null }
+    if (!res.ok) {
+      const msg = json?.message || json?.error?.message || json?.code || text
+      const hint = res.status === 413 && !gzip ? ` (evidence is ${Buffer.byteLength(payload)} bytes; retry with --upload-gzip if the workspace accepts gzip)` : ''
+      return { ok: false, status: res.status, error: `HTTP ${res.status}${msg ? ` — ${String(Array.isArray(msg) ? msg.join('; ') : typeof msg === 'string' ? msg : JSON.stringify(msg)).slice(0, 300)}` : ''}${hint}` }
+    }
+    const data = json && typeof json === 'object' && json.data && typeof json.data === 'object' ? json.data : json
+    return { ok: true, status: res.status, runId: data?.id ?? null }
+  } catch (e) {
+    return { ok: false, error: e.name === 'AbortError' ? `timed out after ${timeoutMs} ms` : (e.cause?.code || e.message) }
+  } finally {
+    clearTimeout(timer)
+  }
+}