refactor(lab): canonize selected evidence reports
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user