refactor(lab): canonize selected evidence reports
This commit is contained in:
DCCONSTRUCTIONS
@@ -10,7 +10,8 @@ GUI for every LAB run. The product surface remains compact, readable,
|
||||
predictable, and based on the approved NODE.DC Design Guideline.
|
||||
|
||||
This document governs Control Station product UI, laboratory summaries,
|
||||
evidence viewers, and the boundary with complete engineering reports in Ops.
|
||||
evidence viewers, selected-LAB evidence reports, and the boundary with
|
||||
implementation history and architecture narratives in Ops.
|
||||
It complements `docs/15_LABORATORY_RUN_CANON.md`, which governs publication and
|
||||
provenance. New non-LAB surfaces and their placement are governed by
|
||||
`docs/19_PRODUCT_SURFACE_EXTENSION_PROTOCOL.md`.
|
||||
@@ -95,6 +96,48 @@ to these components and must not reproduce their classes or DOM structure.
|
||||
Changing this anatomy is a template-version decision, not a LAB-specific
|
||||
layout edit.
|
||||
|
||||
### Selected-LAB evidence report mode
|
||||
|
||||
The LAB content window has two views of the same selected immutable run: the
|
||||
individual LAB template and its complete evidence report. A canonical text `Button` in
|
||||
`ApplicationPanel.headerTools` switches between `Отчёт` and `Лабораторные
|
||||
контуры`; this is not a new root navigation item and it preserves the selected
|
||||
LAB. The control uses the default canonical height so it aligns with the panel
|
||||
actions.
|
||||
|
||||
`missioncore.laboratory-evidence-report/v1` is generated from the selected
|
||||
run's verified document and artifact manifest. It must expose, without dropping
|
||||
the raw report:
|
||||
|
||||
- exact work/result identity, schema versions, document/report SHA-256;
|
||||
- source and preprocessing contract;
|
||||
- run configuration, method, modules, models, algorithms, and their identities;
|
||||
- actual worker/runtime and resource telemetry when recorded;
|
||||
- measured metrics, thresholds, checks, decision, limitations, and retained authority;
|
||||
- every verified artifact with role, byte length, SHA-256, and media/schema metadata;
|
||||
- an explicit `recorded` or `not-recorded` completeness state for every section.
|
||||
|
||||
The UI must never fill a missing field from review copy or visual inference.
|
||||
Artifact hash or identity failure closes the report rather than presenting a
|
||||
partial success.
|
||||
|
||||
The separate value-review index is not rendered as the report. It binds an
|
||||
operator classification to exact immutable evidence identity and carries two
|
||||
independent dimensions:
|
||||
|
||||
- signal: `progress`, `retained`, or `failed` for the declared LAB question;
|
||||
- lifecycle: `current` or `legacy` for code and architecture treatment.
|
||||
|
||||
Green means the bounded LAB question produced confirmed progress, yellow means
|
||||
the evidence is retained for comparison, and gray means a gate failed or a new
|
||||
identity is not yet reviewed. None of these colors grants production,
|
||||
navigation, or safety authority. A new result identity never inherits the
|
||||
classification of the previous result automatically.
|
||||
|
||||
The same signal is projected into catalog selectors with a small filled status
|
||||
lamp using the established status colors. Useful legacy evidence remains readable while its experiment
|
||||
implementation may be removed from the product core.
|
||||
|
||||
### Canonical summary content
|
||||
|
||||
The summary must let an operator understand the evidence before opening the
|
||||
@@ -188,13 +231,15 @@ Do not render:
|
||||
- a separate layout because one LAB has a different algorithm.
|
||||
|
||||
If information is necessary only for development or governance, place it in
|
||||
Ops, a report, an ADR, a runbook, or developer tooling.
|
||||
Ops, an ADR, a runbook, or developer tooling. Evidence needed to verify the
|
||||
selected LAB belongs in its product evidence report.
|
||||
|
||||
## Ops engineering report
|
||||
|
||||
The complete report for a LAB or architecture milestone lives in the Mission
|
||||
Core Ops project. Keep the issue description concise and place the report in
|
||||
titled structured blocks. Use this canonical order:
|
||||
The complete implementation history and architecture narrative for a LAB or
|
||||
milestone lives in the Mission Core Ops project. It links the canonical product
|
||||
evidence report instead of retyping its metrics. Keep the issue description
|
||||
concise and place the narrative in titled structured blocks. Use this order:
|
||||
|
||||
1. Objective and architecture stage.
|
||||
2. Decision question and hypothesis.
|
||||
@@ -209,8 +254,10 @@ titled structured blocks. Use this canonical order:
|
||||
11. Next stage and authority that remains forbidden.
|
||||
12. Acceptance checker with short verifiable items.
|
||||
|
||||
The product summary is a projection of this report, never a second independent
|
||||
narrative.
|
||||
The product summary and selected-LAB evidence report are projections of
|
||||
immutable runtime evidence, never a second independent narrative. Ops adds
|
||||
engineering context, ownership, implementation history, and future work; it is
|
||||
not a substitute for source/runtime/metric/artifact proof.
|
||||
|
||||
## Review gate before A3
|
||||
|
||||
|
||||
@@ -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