docs(lab): codify immutable laboratory runs
This commit is contained in:
@@ -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
|
despite much lower latency and a small Ground-IoU gain, obstacle non-ground
|
||||||
recall regressed from `80.46%` to `69.70%`.
|
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).
|
[ADR 0021](docs/adr/0021-dataset-gateway-representation-boundary.md).
|
||||||
|
|
||||||
## Simulation Polygon
|
## Simulation Polygon
|
||||||
|
|||||||
@@ -481,7 +481,8 @@ policy.
|
|||||||
All paths are same-origin and expose opaque identifiers only:
|
All paths are same-origin and expose opaque identifiers only:
|
||||||
|
|
||||||
```text
|
```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}
|
GET /api/v1/observation-sessions/{id}
|
||||||
POST /api/v1/observation-sessions/{id}/replay
|
POST /api/v1/observation-sessions/{id}/replay
|
||||||
GET /api/v1/observation-sessions/{id}/recording-preparation
|
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.
|
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
|
`POST .../replay` returns either a verified replay v2 launch document or HTTP
|
||||||
202 with the preparation v1 document, `Location`, `Retry-After`, an exact quoted
|
202 with the preparation v1 document, `Location`, `Retry-After`, an exact quoted
|
||||||
preparation `ETag` and a same-origin status URL. Polling
|
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
|
- **Тестировочный контур → Лабораторные контуры** owns immutable experiment
|
||||||
configurations and results. The first selector chooses a configuration
|
configurations and results. The first selector chooses a configuration
|
||||||
profile, the second chooses one LAB work inside it, and the output uses one
|
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
|
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
|
camera-first semantic/geometry result. Published E19–E26 recordings remain a
|
||||||
separate profile and are not duplicated into the saved-session catalog UI.
|
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 |
|
| **Наблюдение** | 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 |
|
| **Данные** | 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 |
|
| **Тестировочный контур** | 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 |
|
| **Система** | Deeper module, integration, network, audit and configuration administration | Daily operational health summary |
|
||||||
| **Парк** | Devices, sensors and live device operation | Offline algorithm-development reports |
|
| **Парк** | 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
|
сцена** to the runtime-published live source. A selected archive cannot leak
|
||||||
into the live observation surface.
|
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
|
Dataset sources use a single-open accordion. Expanding one source mounts its
|
||||||
viewer and analysis inside that source card, pushes later sources down, and
|
viewer and analysis inside that source card, pushes later sources down, and
|
||||||
closes the previously expanded source.
|
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.
|
2. a **laboratory work** selects one immutable result inside that profile.
|
||||||
|
|
||||||
The selected work opens one reusable output structure: task and configuration,
|
The selected work opens one reusable output structure: task and configuration,
|
||||||
full-size visual evidence, then structured metrics, errors, timing and
|
method manifest, full-size visual evidence, then structured metrics, errors,
|
||||||
conclusion. LAB E28 owns the L2.6 local-surface viewer, complete-recording
|
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
|
timeline and review queue. LAB E29 owns the camera-first semantic/geometry
|
||||||
coverage result. Recorded E19–E26 LAB instances are exposed through a separate
|
coverage result. Recorded E19–E26 LAB instances are exposed through a separate
|
||||||
published-perception profile backed by the existing observation-session
|
published-perception profile backed by the existing observation-session
|
||||||
catalog. They are not rendered as a second saved-session archive.
|
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
|
Neither E28 nor E29 is live device diagnostics. A future device-diagnostics
|
||||||
workspace must require an attached device and its own diagnostic contract.
|
workspace must require an attached device and its own diagnostic contract.
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user