refactor(lab): canonize selected evidence reports

This commit is contained in:
DCCONSTRUCTIONS
2026-08-05 11:49:44 +03:00
parent 4c763bd8aa
commit de12e96297
30 changed files with 2876 additions and 134 deletions
@@ -0,0 +1,60 @@
# ADR 0037: Identity-bound laboratory value-review index
Date: 2026-08-05
Status: accepted and implemented; product presentation amended by ADR 0038
## Context
Mission Core had immutable LAB artifacts and increasingly complete visual
result pages, but no reviewed cross-LAB classification. A chronological list
could not distinguish a useful negative result, a reusable architectural gain,
an intermediate comparison, and an unreviewed replacement result. Encoding
those distinctions in renderer branches would make the UI another source of
truth and would let stale conclusions survive a new run.
## Decision
`config/laboratory-value-review.json` is a strict versioned review registry. Each
entry references a catalog id and the exact evidence identity it evaluates,
then records only:
- `progress`, `retained`, or `failed` for the bounded LAB question;
- `current` or `legacy` for architecture lifecycle;
- visual-evidence availability;
It intentionally contains no finding, decision, limitation, metric, or report
copy. Those facts belong to immutable evidence and ADR 0038.
The backend parses the file fail-closed and exposes a read-only value-review index.
The frontend joins it to the live evidence catalog only when `evidence_id`
matches. A replacement result therefore becomes `unreviewed`; it cannot inherit
a green or yellow state from the previous artifact. Historical published
sessions use their immutable provenance and explicit benchmark result as a
bounded legacy fallback.
The registry is a classification input for selector status lamps and lifecycle
review. It is not the engineering report and is not rendered by the `Отчёт`
toggle. ADR 0038 assigns that toggle to the selected immutable LAB evidence.
## Classification semantics
- `progress` means the experiment achieved a declared bounded objective or
established a reusable contract. It does not mean production acceptance.
- `retained` means the evidence remains useful for comparison, diagnosis, or a
later review even though it is not a promoted result.
- `failed` means an explicit gate or candidate objective did not pass. A failed
result may still be valuable regression evidence.
- `legacy` permits removal of experiment-specific implementation while keeping
immutable evidence, report metadata, and a compatible renderer/read model.
## Consequences
- Value-review copy is reviewable configuration rather than JSX or inferred UI text.
- New identities fail visibly into an unreviewed state.
- Valuable legacy experiments no longer justify retaining their orchestration
code in Mission Core.
- The value-review index does not execute experiments and does not solve the future
provider/graph/run configuration contract.
- Full implementation history remains in Ops. Verifiable source, runtime,
telemetry, metrics, gates, artifacts, and hashes belong to the selected LAB
evidence report defined by ADR 0038.
@@ -0,0 +1,48 @@
# ADR 0038: Selected immutable LAB evidence report
Date: 2026-08-05
Status: accepted and implemented
## Context
The first `Отчёт` implementation rendered one cross-LAB list with three pieces
of reviewed prose per run. It did not answer the operator's actual question:
what exact source, configuration, modules, runtime, hardware load, measurements,
gates, artifacts, and limitations prove the currently selected LAB result.
Most of those facts already existed in immutable manifests and report artifacts,
but the UI discarded them.
## Decision
`Отчёт` is the evidence report of the currently selected immutable LAB identity.
It never changes selection and never aggregates other runs.
The backend exposes
`GET /api/v1/laboratory/evidence-reports/{work_id}/{result_id}` using
`missioncore.laboratory-evidence-report/v1`. Before projection it verifies:
- the registered work ID, result ID pattern, document schema, and exact result ID;
- the canonical identity SHA-256 and its binding to the result ID;
- normalized artifact paths with no traversal or symlink;
- byte length and SHA-256 of every declared artifact;
- the selected JSON report and runtime artifact from those verified descriptors.
The response preserves the raw report and normalizes source, configuration,
method, execution, resource telemetry, metrics, gates, decision, limitations,
authority, artifacts, and visual evidence. Each section is marked `recorded` or
`not-recorded`. Absence is not inferred as success, failure, or not-applicable.
The value-review registry from ADR 0037 remains a separate identity-bound input
for filled selector status lamps. It cannot supply missing evidence fields.
## Consequences
- The operator can audit one LAB without reading source code.
- A green review lamp cannot hide missing telemetry or artifacts.
- Older runs expose their actual gaps instead of receiving fabricated modern
fields.
- Artifact tampering closes the report with a verification error.
- New LAB implementations must publish the canonical evidence dimensions if
they want a complete report; UI copy cannot compensate for a weak payload.
- Ops remains the place for implementation history, ownership, and planned work,
while product evidence remains machine-verifiable and identity-bound.