stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity

up

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-27 21:10:06 +02:00
parent cfa2274d31
commit 8abbf9574d
106 changed files with 7078 additions and 3197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/modules/scanner/architecture.md
View File

@@ -485,6 +485,7 @@ ResolveEntrypoint(ImageConfig cfg, RootFs fs):
- WebService ships a **RecordModeService** that assembles replay manifests (schema v1) with policy/feed/tool pins and reachability references, then writes deterministic input/output bundles to the configured object store (RustFS default, S3/Minio fallback) under `replay/<head>/<digest>.tar.zst`.
- Bundles contain canonical manifest JSON plus inputs (policy/feed/tool/analyzer digests) and outputs (SBOM, findings, optional VEX/logs); CAS URIs follow `cas://replay/...` and are attached to scan snapshots as `ReplayArtifacts`.
- Reachability graphs/traces are folded into the manifest via `ReachabilityReplayWriter`; manifests and bundles hash with stable ordering for replay verification (`docs/replay/DETERMINISTIC_REPLAY.md`).
- Worker sealed-mode intake reads `replay.bundle.uri` + `replay.bundle.sha256` (plus determinism feed/policy pins) from job metadata, persists bundle refs in analysis and surface manifest, and validates hashes before use.
- Deterministic execution switches (`docs/modules/scanner/deterministic-execution.md`) must be enabled when generating replay bundles to keep hashes stable.
EntryTrace emits structured diagnostics and metrics so operators can quickly understand why resolution succeeded or degraded:

3
docs/modules/scanner/determinism-score.md
View File

@@ -42,9 +42,10 @@ Required fields:
Output bundle layout:
- `determinism.json` – schema above
- `determinism.json` – schema above, includes per-run artefact hashes and determinism pins (feed/policy/tool) plus runtime toggles.
- `run_i/*.json` – canonicalised artefacts per run
- `diffs/` – minimal diffs when divergence occurs
- `surface/determinism.json` – copy of the worker-emitted determinism manifest from the surface bundle (pins + payload hashes) for cross-checking.
## 4. CI integration (`DEVOPS-SCAN-90-004`)

2
docs/modules/scanner/operations/analyzers.md
View File

@@ -41,7 +41,7 @@ Keep the language analyzer microbench under the < 5 s SBOM pledge. CI emits
- Pager payload should include `scenario`, `max_ms`, `baseline_max_ms`, and `commit`.
- Immediate triage steps:
1. Check `latest.json` artefact for the failing scenario – confirm commit and environment.
2. Re-run the harness with `--captured-at` and `--baseline` pointing at the last known good CSV to verify determinism.
2. Re-run the harness with `--captured-at` and `--baseline` pointing at the last known good CSV to verify determinism; include `surface/determinism.json` in the release bundle (see `release-determinism.md`).
3. If regression persists, open an incident ticket tagged `scanner-analyzer-perf` and page the owning language guild.
4. Roll back the offending change or update the baseline after sign-off from the guild lead and Perf captain.

29
docs/modules/scanner/operations/release-determinism.md Normal file
View File

@@ -0,0 +1,29 @@
# Scanner Release Determinism Checklist
> Completes SCAN-DETER-186-010 by ensuring every release ships a reproducibility bundle.
## What to publish
- `determinism.json` generated by the harness (scores, non-deterministic artefacts, thresholds).
- `surface/determinism.json` copied from worker surface manifests (pins + runtime toggles + payload hashes).
- Canonical artefacts per run (`run_i/*.json`) and diffs for divergent runs.
## Where to publish
- Object store bucket configured for releases (same as reports), prefix: `determinism/<release>/`.
- CAS-style paths: `cas://determinism/<head>/<sha>.tar.zst` for bundle archives.
- Link from release notes and offline kit manifests.
## How to generate
1. Run determinism harness (`SCAN-DETER-186-009`) against release image with frozen clock/seed/concurrency and pinned feeds/policy.
2. Export bundle using the harness CLI (pending) or the helper script `scripts/scanner/determinism-run.sh`.
3. Copy worker-emitted `determinism.json` from surface manifest cache into `surface/determinism.json` inside the bundle for cross-checks.
4. Sign bundles with DSSE (determinism predicate) and, if enabled, submit to Rekor.
## Acceptance gates
- Overall score >= 0.95 and per-image score >= 0.90.
- All bundle files present: `determinism.json`, `surface/determinism.json`, `run_*`, `diffs/` (may be empty when fully deterministic).
- Hashes in `surface/determinism.json` match hashes in `determinism.json` baseline artefacts.
## References
- docs/modules/scanner/determinism-score.md
- docs/modules/scanner/deterministic-execution.md
- docs/replay/DETERMINISTIC_REPLAY.md