docs(lab): codify immutable laboratory runs
This commit is contained in:
DCCONSTRUCTIONS
@@ -0,0 +1,166 @@
|
||||
# Laboratory run canon
|
||||
|
||||
Status: accepted, 2026-07-26
|
||||
|
||||
## Product boundary
|
||||
|
||||
Mission Core has two different catalogs over related evidence:
|
||||
|
||||
- **Data → Sessions and records** contains only original physical captures.
|
||||
Examples: `RAVNOVES00`, `TEST007`, `TEST009`. A source record is immutable
|
||||
evidence received from a device or recording adapter.
|
||||
- **Test contour → Laboratory contours** contains derived experimental runs.
|
||||
Examples: LAB E24, E25, E26, E28 and E29. A LAB run references an original
|
||||
record and never becomes another original capture.
|
||||
|
||||
The backend may keep both entities in one durable SQLite catalog, but every
|
||||
consumer must request an explicit catalog scope:
|
||||
|
||||
- `scope=source` for original records;
|
||||
- `scope=laboratory` for LAB projections;
|
||||
- `scope=all` only for internal joins that must resolve both a derivative and
|
||||
its source.
|
||||
|
||||
Deleting, renaming or moving source payloads to make the UI look clean is
|
||||
forbidden. Product separation is expressed by typed projections.
|
||||
|
||||
## Immutable identity
|
||||
|
||||
Every LAB run is one append-only result with:
|
||||
|
||||
1. a unique `session_id` and human LAB id;
|
||||
2. the exact `source_session_id`;
|
||||
3. source result/artifact ids and their SHA-256 identities;
|
||||
4. `run_created_at_utc` plus source monotonic/timeline bounds;
|
||||
5. a configuration SHA-256;
|
||||
6. a method manifest;
|
||||
7. immutable artifacts with role, media type, byte length and SHA-256;
|
||||
8. metrics, acceptance gates, limitations, authority and conclusion.
|
||||
|
||||
A LAB cannot use another LAB as its physical source. Derived chains are
|
||||
represented as provenance links while the root `source_session_id` remains the
|
||||
original capture.
|
||||
|
||||
## Required method manifest
|
||||
|
||||
New catalog publication is rejected unless provenance contains
|
||||
`missioncore.laboratory-method/v1`:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "missioncore.laboratory-method/v1",
|
||||
"completeness": "complete",
|
||||
"execution_class": "hybrid",
|
||||
"pipeline_id": "camera-first-local-surface-validation/v1",
|
||||
"components": [
|
||||
{
|
||||
"kind": "model",
|
||||
"name": "semantic provider",
|
||||
"version": "provider release or profile id",
|
||||
"role": "camera semantic class and identity",
|
||||
"identity_sha256": "<64 hex>"
|
||||
},
|
||||
{
|
||||
"kind": "algorithm",
|
||||
"name": "local-surface validation",
|
||||
"version": "profile id",
|
||||
"role": "metric range and occupied support",
|
||||
"identity_sha256": "<64 hex>"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`execution_class` is exactly one of:
|
||||
|
||||
- `deterministic`;
|
||||
- `ai-inference`;
|
||||
- `hybrid`.
|
||||
|
||||
Components are typed as `source`, `tool`, `model`, `algorithm` or `runtime`.
|
||||
Each records a name, version/profile, role and content identity when one
|
||||
exists. A `complete` method must identify every model and algorithm. A digest
|
||||
of a configuration file is not a substitute for a model-weight digest; both
|
||||
are stored when both influence the result.
|
||||
|
||||
The method also records, in its immutable supporting artifacts:
|
||||
|
||||
- ordered preprocessing operations and parameters;
|
||||
- code revision or producer SHA-256;
|
||||
- model architecture, weight identity and inference provider;
|
||||
- deterministic algorithm/profile identities;
|
||||
- container/runtime, accelerator and relevant library versions;
|
||||
- random seed and determinism policy where randomness exists;
|
||||
- host/worker identity and bounded resource policy.
|
||||
|
||||
LAB E19–E26 were published before this contract. They remain valid evidence,
|
||||
but their missing historical model/runtime identities are displayed as
|
||||
`legacy-partial`; Mission Core does not invent them after the fact. Partial
|
||||
method provenance cannot pass a reproducibility or production-promotion gate.
|
||||
|
||||
## Required result record
|
||||
|
||||
Each LAB result must make these sections available to the operator:
|
||||
|
||||
1. **Task** — hypothesis, source, configuration, authority and tested bounds.
|
||||
2. **Method** — tools, models, algorithms, runtime and their identities.
|
||||
3. **Visual evidence** — verified server artifacts, never a mock or a diagram
|
||||
standing in for absent data.
|
||||
4. **Result** — metrics, errors, latency/resources and gate outcomes.
|
||||
5. **Conclusion** — what was proved, what was not proved, limitations and the
|
||||
next gate.
|
||||
|
||||
The result must explicitly state:
|
||||
|
||||
- ground-truth availability and its identity;
|
||||
- timestamp/pose/calibration quality;
|
||||
- dropped, stale, excluded and invalid samples;
|
||||
- processing duration, p50/p95 where relevant, and peak resource use;
|
||||
- every threshold used to produce a pass/fail decision;
|
||||
- `commands_enabled` and `navigation_or_safety_accepted`;
|
||||
- operator notes without credentials or local filesystem paths.
|
||||
|
||||
## One template, two evidence variants
|
||||
|
||||
There are not two unrelated laboratory-page templates. Mission Core has one
|
||||
`LaboratoryWorkTemplate` with fixed slots:
|
||||
|
||||
`task → method → evidence → result → details`.
|
||||
|
||||
The evidence slot has two admitted renderers:
|
||||
|
||||
- `recorded-replay` — the standard full-size spatial viewer. It can present
|
||||
point cloud plus zero, one or several synchronized floating camera windows.
|
||||
“Two viewers” is therefore one replay evidence surface with two admitted
|
||||
sources, not a separate page template.
|
||||
- `diagnostic-model` — a specialized visual result such as the LAB E28 L2.6
|
||||
surface/timeline/review viewer.
|
||||
|
||||
If an experiment needs a new chart or control, the reusable result/evidence
|
||||
component is extended and validated. A one-off page that bypasses the template
|
||||
is not accepted.
|
||||
|
||||
## Publication gates
|
||||
|
||||
A LAB run is catalogued only when:
|
||||
|
||||
- its root source exists and is immutable;
|
||||
- all referenced artifacts exist and match size/hash metadata;
|
||||
- its source/timeline binding is exact;
|
||||
- its method manifest passes schema validation;
|
||||
- visual evidence is actually available on the server;
|
||||
- command and safety authority remain explicit;
|
||||
- publication is idempotent for the same identity and refuses conflicting
|
||||
provenance.
|
||||
|
||||
A LAB run may be shown as diagnostic evidence with `legacy-partial` method
|
||||
metadata. It may be called reproducible or promoted only when the method is
|
||||
`complete` and its experiment-specific acceptance gates pass.
|
||||
|
||||
## Storage and Git
|
||||
|
||||
Raw captures, model weights, generated RRD, videos and large derived arrays stay
|
||||
in the configured Mission Core data/evidence roots on disk D. Git stores only
|
||||
contracts, code, redacted manifests, small reports and documentation. Every
|
||||
physical capture retains UTC and monotonic time evidence, operator notes and
|
||||
raw SHA-256 according to `AGENTS.md`.
|
||||
Reference in New Issue
Block a user