diff --git a/README.md b/README.md index 053cc7e..39d29db 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/09_OBSERVATION_SESSIONS.md b/docs/09_OBSERVATION_SESSIONS.md index b1f2115..fef27c4 100644 --- a/docs/09_OBSERVATION_SESSIONS.md +++ b/docs/09_OBSERVATION_SESSIONS.md @@ -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 diff --git a/docs/14_LIDAR_DATASET_GATEWAY.md b/docs/14_LIDAR_DATASET_GATEWAY.md index c0ee877..b129d5f 100644 --- a/docs/14_LIDAR_DATASET_GATEWAY.md +++ b/docs/14_LIDAR_DATASET_GATEWAY.md @@ -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. diff --git a/docs/15_LABORATORY_RUN_CANON.md b/docs/15_LABORATORY_RUN_CANON.md new file mode 100644 index 0000000..f59a127 --- /dev/null +++ b/docs/15_LABORATORY_RUN_CANON.md @@ -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`. diff --git a/docs/adr/0022-operator-surface-ownership.md b/docs/adr/0022-operator-surface-ownership.md index d960918..b1768c8 100644 --- a/docs/adr/0022-operator-surface-ownership.md +++ b/docs/adr/0022-operator-surface-ownership.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.