validation methodology
this page documents how fatcousin forensics validates tool engines and session exports — not collection-stage chain-of-custody software, but hash-anchored analysis-phase session custody log infrastructure with committed fixture goldens and build-stamped receipts. it is the factual reference for determinism and discrepancy handling; for verification steps see /forensics/verify, for architecture narrative see the whitepaper.
tool processing model
every forensics tool runs read-only in the examiner's browser. the investigator selects local files; engines parse or transform them client-side and emit structured output — csv, json, timelines, hashes — without uploading bytes to FatCousin Labs Inc. or any third party.
- tool components load as per-tool esbuild bundles from
/tool-bundles/after the host runtime installs — the next.js build does not compile individual tool graphs - heavy parsers (ffmpeg, onnx, sql.js, large wasm) execute in web workers under
/public/workers/— not via server round-trips - inputs are read from the user's filesystem via file picker or drag-and-drop; engines do not mutate source files on disk
- each run can emit a reproducibility receipt: tool slug, semver, build sha, input filename, input/output sha-256 digests, utc timestamp — an engineering reproducibility check, not a collection-stage chain-of-custody record by itself
confirm local-only behavior independently: devtools network tab + the global verify panel. see verify · nothing left the device.
session model
investigators attach tool runs to a case session at /forensics/sessions. a session captures tool slug, semver, build sha, timestamps, input filenames, sha-256 hashes of inputs and optional outputs, structured engine findings when available, free-text notes, and append-only custody events — not a per-event hash chain or blockchain-style linkage.
- pre-export state lives in mutable localStorage on the examiner workstation. a compromised browser profile or manual devtools edit could alter in-progress session data before export
- export mitigates but does not eliminate that risk:
.fc-casezip withmanifest.json,manifest.sha256sidecar, custody log payload, and optional ed25519 signatures over custody log + manifest bytes - corrections are new custody events — prior rows are not silently rewritten
- input bytes are not stored by default; investigators may opt in per run to embed attachments in the export archive
what ships in the export package is documented at /forensics/scope#record-h. import and verify instructions: /forensics/verify.
determinism · fixture packs · goldens
flagship proof scenarios ship synthetic fixture packs under app/tools/__fixtures__/cases/<slug>/: evidence files, MANIFEST.sha256, and committed golden outputs at expected/*.golden.json. packs are fictional — inspired by real incident classes, not copies of live breaches.
- each pack includes a deterministic build script seeded with a public string so anyone can regenerate byte-identical evidence
- proof pages at /forensics/proof let reviewers replay synthetic evidence in-browser and compare output digests to receipts
- ci runs
npm run check:flagshipas part ofnpm run check— it replays every committed golden through the fixture runner and compares output. last verified count: 370/370 - live smoke against production:
npm run forensics:proof-spot-check -- --base=https://fatcousin.com
npm run check:flagship # 370/370 golden replay gate in npm run check
golden replay supports examiner testimony and counsel review by proving that a pinned engine version produces deterministic output on reference inputs. it does not prove upstream acquisition integrity or legal admissibility.
discrepancy · regold vs fix engine
when npm run check:flagship fails, maintainers classify the mismatch before merging. regolding to silence a regression is a process failure — fix the engine instead.
| situation | action | when |
|---|---|---|
| intentional engine fix or spec correction | regold — regenerate expected/*.golden.json with the pack capture script documented in the fixture readme | behavior change is correct; output should differ on the same synthetic input |
| unintentional output drift on unchanged input | fix engine — treat golden mismatch as a regression; do not regold to hide it | same semver intent + same fixture bytes should produce identical output |
| live evidence differs from proof fixture output | expected — goldens pin synthetic packs, not your case files | golden replay proves engine behavior on reference inputs, not that live evidence matches a scenario |
practitioners auditing a specific scenario: open the proof page, download the fixture pack, replay locally, and compare output sha-256 to the golden sidecar. step-by-step verification ritual: verify · tool output.
build provenance
every forensics tool page shows a version footer: slug · v[semver] · build [sha]. the build sha is NEXT_PUBLIC_BUILD_SHA — a short git commit identifier for the deployed site build, injected at build time via next.config.mjs.
- session custody log entries stamp semver + build sha at capture time — so an export records which deployed build produced each run, not just the tool name
- reproducibility receipts and
.fc-caseper-run json include the same fields for third-party correlation - cite both semver and build sha when referencing a run in reports — see /forensics/cite templates
comparing a run from today against a golden captured last month requires matching tool semver and build context — engine bundles change when the site deploys even if manifest semver is unchanged.
non-goals
validation methodology documents engineering checks — not legal outcomes. fatcousin is not any of the following:
- not collection-stage chain-of-custody software. no write-block imaging, no live-device acquisition, no sealed-bag custody at collection. upstream acquisition stays with ftk imager, cellebrite, axiom, or your lab sop.
- not a cloud evidence processor. files never leave the examiner's device. if a tool transmits user evidence bytes off-device, that is a bug — report it.
- not court compliant · admissible · certified for litigation. admissibility is per case, judge, and jurisdiction. fatcousin supports examiner testimony and counsel review — not a product badge or legal outcome guarantee.
full honest boundaries: scope · record. external reviewer path: reviewer kit.