# Scanner Deterministic Execution Invariants

> **Imposed rule:** Deterministic mode must pin clock, RNG, feeds, policy, tooling, and concurrency; any nondeterministic output is a test failure.

This note collects the invariants required for reproducible Scanner runs and replays.

## Runtime switches (config/env)
- Clock: `scanner:determinism:fixedClock=true`, `scanner:determinism:fixedInstantUtc=2024-01-01T00:00:00Z` or `SCANNER__DETERMINISM__FIXEDCLOCK=true`, `SCANNER__DETERMINISM__FIXEDINSTANTUTC=...`.
- RNG: `scanner:determinism:rngSeed=1337` or `SCANNER__DETERMINISM__RNGSEED=1337`.
- Concurrency cap: `scanner:determinism:concurrencyLimit=1` (worker clamps `MaxConcurrentJobs` to this) or `SCANNER__DETERMINISM__CONCURRENCYLIMIT=1`.
- Feed/policy pins: `scanner:determinism:feedSnapshotId=<frozen-feed>` and `scanner:determinism:policySnapshotId=<rev>` to stamp submissions and reject mismatched runtime policies.
- Log filtering: `scanner:determinism:filterLogs=true` to strip timestamps/PIDs before hashing.
- Evidence: worker emits `determinism.json` into the surface manifest (view `replay`) summarising fixed clock, seed, concurrency cap, feed/policy pins, per-payload hashes, and a Merkle root over payload hashes for quick verification.
- Sealed replay intake: worker reads `replay.bundle.uri` + `replay.bundle.sha256` (and `determinism.feed`/`determinism.policy` pins) from job metadata; stores bundle pins in analysis so downstream stages stay hermetic. Stage: `ingest-replay` runs before image resolution.
- Surface manifest includes `replayBundle` (uri + sha256 + pins) so offline kits can verify sealed inputs without scheduler context.

## Ordering
- Sort inputs (images, layers, files, findings) deterministically before processing/serialization.
- Canonical JSON writers: sorted keys, UTF-8, stable float formatting.

## Hashing & manifests
- Compute SHA-256 for each artefact; aggregate into Merkle root for replay bundles.
- Record tool/policy/feed hashes in `replay.yaml`; include analyzer versions.

## Outputs to verify
- SBOM (CycloneDX/SPDX), findings, VEX, reachability graphs, logs.
- Optional entropy reports (`entropy.report.json`, `layer_summary.json`).
- `determinism.json` when harness is run.

## CI/bench hooks
- `bench:determinism` runs replay with fixed switches; fails on hash deltas.
- `stella replay run --sealed --fixed-clock ... --seed 1337 --single-threaded` for local.

## Offline/air-gap
- All inputs from bundle; no egress.
- Rekor lookups skipped; rely on bundled proofs.

## References
- `docs/replay/DETERMINISTIC_REPLAY.md`
- `docs/replay/TEST_STRATEGY.md`
- `docs/modules/scanner/determinism-score.md`