docs(lab): codify immutable laboratory runs
This commit is contained in:
DCCONSTRUCTIONS
@@ -189,7 +189,8 @@ sealed Current/Patchwork++ comparison rejected Patchwork++ for navigation:
|
||||
despite much lower latency and a small Ground-IoU gain, obstacle non-ground
|
||||
recall regressed from `80.46%` to `69.70%`.
|
||||
|
||||
See [the Dataset Gateway plan](docs/14_LIDAR_DATASET_GATEWAY.md) and
|
||||
See [the Dataset Gateway plan](docs/14_LIDAR_DATASET_GATEWAY.md),
|
||||
[the laboratory run canon](docs/15_LABORATORY_RUN_CANON.md) and
|
||||
[ADR 0021](docs/adr/0021-dataset-gateway-representation-boundary.md).
|
||||
|
||||
## Simulation Polygon
|
||||
|
||||
@@ -481,7 +481,8 @@ policy.
|
||||
All paths are same-origin and expose opaque identifiers only:
|
||||
|
||||
```text
|
||||
GET /api/v1/observation-sessions?limit=3
|
||||
GET /api/v1/observation-sessions?limit=3&scope=source
|
||||
GET /api/v1/observation-sessions?limit=3&scope=laboratory
|
||||
GET /api/v1/observation-sessions/{id}
|
||||
POST /api/v1/observation-sessions/{id}/replay
|
||||
GET /api/v1/observation-sessions/{id}/recording-preparation
|
||||
@@ -498,6 +499,11 @@ PUT /api/v1/workspace-layouts/observation.spatial
|
||||
```
|
||||
|
||||
The catalog embeds each replayable session's preparation state and progress.
|
||||
`scope=source` returns only original physical records and is the only scope
|
||||
used by **Данные → Сессии и записи**. `scope=laboratory` returns immutable LAB
|
||||
projections. `scope=all` is reserved for internal joins such as resolving a LAB
|
||||
projection together with its source; pagination is applied after the scope
|
||||
filter so a growing LAB history cannot hide original records.
|
||||
`POST .../replay` returns either a verified replay v2 launch document or HTTP
|
||||
202 with the preparation v1 document, `Location`, `Retry-After`, an exact quoted
|
||||
preparation `ETag` and a same-origin status URL. Polling
|
||||
|
||||
@@ -117,7 +117,9 @@ The gateway and current local-surface work are not live device diagnostics.
|
||||
- **Тестировочный контур → Лабораторные контуры** owns immutable experiment
|
||||
configurations and results. The first selector chooses a configuration
|
||||
profile, the second chooses one LAB work inside it, and the output uses one
|
||||
reusable `task → full visual evidence → structured result` template.
|
||||
reusable `task → method → full visual evidence → structured result` template.
|
||||
The method identifies tools, models, algorithms, profiles and producer
|
||||
digests according to `docs/15_LABORATORY_RUN_CANON.md`.
|
||||
LAB E28 owns the L2.6 local-surface viewer and review queue; LAB E29 owns the
|
||||
camera-first semantic/geometry result. Published E19–E26 recordings remain a
|
||||
separate profile and are not duplicated into the saved-session catalog UI.
|
||||
|
||||
@@ -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`.
|
||||
@@ -23,7 +23,7 @@ Mission Core assigns one owner to each operator concept:
|
||||
| **Наблюдение** | Current live sensor scene and live-only spatial controls | Saved-session selection or offline experiments |
|
||||
| **Данные** | Saved sessions, replay, public datasets, streams, entities and export | Simulation execution or laboratory conclusions |
|
||||
| **Тестировочный контур** | Versioned laboratory work, test configuration and visual evidence | Source-of-record retention or public dataset storage |
|
||||
| **Центр → Состояние контура** | Live compute nodes, processes, network reachability and connected devices | Static feature inventory or a separate activity page |
|
||||
| **Парк → Состояние контура** | Live compute nodes, processes, network reachability and connected devices | Static feature inventory or a separate activity page |
|
||||
| **Система** | Deeper module, integration, network, audit and configuration administration | Daily operational health summary |
|
||||
| **Парк** | Devices, sensors and live device operation | Offline algorithm-development reports |
|
||||
|
||||
@@ -41,6 +41,10 @@ not expand the catalog into the content column. Leaving either archive returns
|
||||
сцена** to the runtime-published live source. A selected archive cannot leak
|
||||
into the live observation surface.
|
||||
|
||||
The saved-session dropdown requests only `scope=source`; LAB E19–E29 never
|
||||
appear there. Laboratory catalogs use `scope=laboratory`, while internal LAB
|
||||
joins may use `scope=all` to resolve a derivative and its root source.
|
||||
|
||||
Dataset sources use a single-open accordion. Expanding one source mounts its
|
||||
viewer and analysis inside that source card, pushes later sources down, and
|
||||
closes the previously expanded source.
|
||||
@@ -51,13 +55,18 @@ The laboratory surface is a two-level catalog:
|
||||
2. a **laboratory work** selects one immutable result inside that profile.
|
||||
|
||||
The selected work opens one reusable output structure: task and configuration,
|
||||
full-size visual evidence, then structured metrics, errors, timing and
|
||||
conclusion. LAB E28 owns the L2.6 local-surface viewer, complete-recording
|
||||
method manifest, full-size visual evidence, then structured metrics, errors,
|
||||
timing and conclusion. The template has `recorded-replay` and
|
||||
`diagnostic-model` evidence renderers; synchronized point cloud and camera
|
||||
windows remain one replay evidence surface. LAB E28 owns the L2.6 local-surface viewer, complete-recording
|
||||
timeline and review queue. LAB E29 owns the camera-first semantic/geometry
|
||||
coverage result. Recorded E19–E26 LAB instances are exposed through a separate
|
||||
published-perception profile backed by the existing observation-session
|
||||
catalog. They are not rendered as a second saved-session archive.
|
||||
|
||||
The full publication and UI contract is defined in
|
||||
`docs/15_LABORATORY_RUN_CANON.md`.
|
||||
|
||||
Neither E28 nor E29 is live device diagnostics. A future device-diagnostics
|
||||
workspace must require an attached device and its own diagnostic contract.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user