NODEDC_MISSION_CORE/docs/15_LABORATORY_RUN_CANON.md

Laboratory run canon

Status: accepted, 2026-07-26

Product boundary

Mission Core has two different catalogs over related evidence:

• Data → Sessions and records contains independent original physical captures. Examples: RAVNOVES00, TEST007, TEST009. A source record is immutable evidence received from a device or recording adapter. Per the 2026-09-21 owner decision, physical passes acquired by the planner are shown with their studies in LAB → Planner, not in Data or the reference selector.
• 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=standalone for Data and planner reference choices: original records excluding explicit planner-acquisition bindings;
• scope=source for all original records, including planner passes needed for recorded comparisons and scientific inspection;
• 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.

A planner pass remains a physical source, not a synthetic LAB projection. Classification uses exact run/session acquisition bindings, never names or registration success. Hiding it from Data does not remove its raw evidence or its historical planning report. See the full-reference/catalog audit.

Current reference-source policy

RAVNOVES00 is the sole active physical reference source for the current product-maturation cycle defined by ADR 0030. Until its source-scoped release candidate is accepted:

• new perception and product iterations use RAVNOVES00;
• each iteration creates a new immutable LAB and never rewrites an older one;
• TEST007 and E36 replay are deferred, not required current gates;
• no agent may initiate or imply a new capture without explicit operator authorization;
• the active quality target is at least 90% on each frozen task-level validation dimension, never one unqualified aggregate accuracy number.

ADR 0032 corrects the present validation meaning. E37's 146-row slice is historical evaluated visible engineering validation: its labels are not independent truth and its development/evaluation groups overlap. It remains an immutable comparison contract, but it cannot close a blind accuracy gate. Prediction packages must exclude truth, split, severity and scoring material, and evaluation must join those artifacts only after prediction.

The owner has authorized preparation for a later same-K1/new-route recording, not agent-initiated collection. E43 freezes that future protocol before data exists. Until the recording is supplied, no LAB result, metric or transfer claim is created for it.

This policy is a development priority, not a universality claim. Later second-source transfer remains required before any cross-route or cross-camera generalization statement.

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:

{
  "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.

If an algorithmic result has a spatial, image-plane, temporal, geometric or otherwise directly visualizable interpretation, metrics alone are not a complete LAB record. The published run must include bounded visual evidence derived from the same immutable input and result identities. That evidence must expose the operator question and the relevant truth/prediction/error layers without recomputing, retuning or substituting the measured result.

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:

compact summary → evidence → result → optional reusable details.

The executable product contract is versioned as missioncore.laboratory-report/v1. Its canonical summary always contains the four named fields question, approach, principalResult, and limitation. Its ordinary result uses the shared LaboratoryResultSummary with metrics and the three named conclusions proved, notProved, and decision. LAB feature modules provide typed values; they do not render laboratory-summary or laboratory-result-summary markup themselves.

Catalog profile/work selectors precede the template. The compact summary projects the task, method, principal result, limitation, and retained authority from typed LAB data; it does not reproduce the complete engineering report.

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.

ADR 0045 amends the full-session recorded-replay transport. A canonical recorded LAB uses one unmodified upstream Rerun viewer, recording identity and timeline for camera, semantic and spatial evidence. The source RRD owns pose, point cloud and trajectory; a digest-bound RRD sidecar may add only immutable derived entities which are absent from the source. Model or layer selection is a blueprint/profile change, not a new player or renderer. Missing full-route TGS, semantic 3D, boxes or cuboids remain disabled instead of being inferred from sparse review artifacts.

Recorded camera clips used for review are a frozen sub-contract of the admitted viewer, missioncore.laboratory-recorded-clip-viewer/v1, implemented by LaboratoryRecordedClipPlayer. It owns the generation-bound fMP4 manifest, bounded MediaSource buffering, source-time playback clock, clip looping and the canonical timeline. A LAB may provide typed overlays and an alternative spatial scene, but it may not implement its own frame timer, per-frame JPEG playback, media cache, port, Rerun blueprint or loading grammar. Exact JPEG remains a paused-frame/fallback evidence endpoint, never the continuous playback transport. Forward frame progression may roll an already-buffered segment target; a backward seek or clip loop must perform an explicit decoder seek and remain decoder-ready without exposing a per-frame loader.

That clip contract remains available to historical bounded clip instruments. It is legacy comparison transport for a migrated full-session LAB and must not be mounted, prefetched or run in parallel with the canonical Rerun profile.

When recorded camera and frame-indexed spatial evidence are both required for one review question, the shared player presents them simultaneously on the same media clock. The camera remains the clock owner; a bounded experiment-neutral spatial cache prefetches exact source sequences, including across the loop boundary. Mode switching changes presentation only. It must not pause the clock, hide the companion camera, create another transport, or flash a full-stage loader between spatial frames. Connected M4.8 workflows project CAMERA, 3D and PLAN through the same left-side vertical glass rail of canonical circular actions; the report, assisted correction and formal review flows do not invent separate mode-control geometry.

An admitted diagnostic viewer may own the result interaction internally when the evidence itself is the review/result instrument, as in E28 and E30. This is not permission to omit the result from a new ordinary LAB report. New bounded ENNResult.tsx modules use LaboratoryResultSummary.

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.

Changing slot order, removing a required summary/conclusion field, or changing shared report geometry requires product-owner agreement, a new contract version, migration of all consumers, and an updated architecture test. A single LAB run never changes the v1 anatomy.

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.

Lifecycle classes and bounded canonicalization

ADR 0039 separates the value of laboratory evidence from the maturity of its execution architecture:

• canonical is the ordinary reusable path through versioned source, provider, graph and run contracts;
• experimental is an admitted bounded adapter or package for a novel stack or method which the current graph cannot honestly express;
• legacy is immutable historical evidence retained through its existing validator/projector without retroactive provenance.

An experimental LAB is not rejected merely because it does not fit the current canonical stack. It still must retain real source/configuration/runtime/artifact identities, visual evidence, terminal outcome, limitations and forbidden authority. It may not silently become a core dependency. Promotion occurs only after repeated value justifies a reusable provider or graph contract.

Mission Core does not bulk-migrate the archive. E33, E35 and E46J are the bounded execution canaries. Once they prove one automatic run-to-evidence path, the LAB canonicalization slice closes and remaining historical work stays legacy unless an integrity or product need justifies a targeted migration.

Observatory durable recorded queue and Worker dispatch

Selecting a source and a laboratory setup in Observatory is not itself a run. The exact legacy submission contains only source_session_id, setup_id and an idempotency key. A portable submission additionally returns the server-owned definition_sha256 and one content-bound check_sha256 obtained from preflight; both must be echoed unchanged during submit. Neither request can supply commands, executable text, filesystem paths, container images, model identities, resource limits or priority. The server resolves the allowlisted identities and seals all executable identity into one durable record:

• the current source-catalog snapshot captured at admission, plus immutable source bundle and source-capability-manifest SHA-256 identities;
• source-adapter id, version and SHA-256;
• setup RunDefinition id, version and SHA-256;
• executor release and image SHA-256 identities;
• learned-model manifest and resource-profile identities;
• checkpoint policy and the server-owned priority class.

An exact retry returns the existing job. Reusing an idempotency key for another identity fails closed. The ordinary lifecycle advances through accepted, queued, claimed and running, then terminates as succeeded or failed. paused, preemption-pending and reconciliation-required are explicit safety branches rather than hidden retries. The durable queue serializes one recorded compute owner and does not equate a queued receipt with a Worker execution receipt.

The only pair currently admitted to the durable queue is the exact RAVNOVES00 source and M4.9T5 · TRAVEL TGS · CPU-only, без ML RunDefinition. It seals an explicitly empty learned-model list because TGS is an algorithmic CPU pipeline, not an unknown model dependency. The binding pins the exact source pack rather than a volatile whole-catalog digest; the server captures and seals the current catalog snapshot into each admitted job.

Two source-independent definitions are projected by the portable catalog:

• LAB V1 · EoMT Cityscapes Large 1024 + DDRNet-39 seals the exact model/component/resource identities and the missioncore.recorded-eomt-ddrnet-review/v2 result contract;
• M4.9T5 · TRAVEL TGS · CPU-only, без ML v2 seals an explicitly empty model manifest, dynamic source-derived frame counts, causal TGS invariants and the missioncore.recorded-tgs-costmap-review/v2 result contract.

Neither portable definition contains a source Session id, label, fixed frame count or filesystem path. Compatibility is derived independently for every setup from the selected Session's real K1 capabilities. A compatible source may therefore report capability pass while that setup's executor remains blocked. Blocked definitions stay projectable and do not prevent an unrelated ready definition from entering the durable queue allowlist.

The server now owns a definition-SHA/check-SHA fenced portable check/submit boundary. Submission still fails closed unless that exact definition has a sealed ready executor release and image and is present in the durable queue. Both repository portable definitions currently declare not-installed, so their preflight remains blocked; no release or image hash is fabricated. The generic v2 assemblers, verified publisher and Worker transport exist as a dormant fail-closed implementation, but exact executor installation, central storage, authentication, tunnel acceptance and end-to-end canaries remain pending. The old missioncore.lab-v1-vegetation-shadow/v1 result and the exact RAVNOVES00 M4.9 result remain only in their existing immutable catalogs; neither is reclassified as a result of a portable definition.

Recorded work has priority rank 100. A future live K1 lease has rank 0 and closes new recorded claims while it is pending or active. Cooperative executors yield only at an allowlisted checkpoint. A non-checkpointable monolith must be cancelled by the scheduler, discard all staging output and later restart from zero. Cancellation uses a crash-safe two-phase protocol: Mission Core first persists one stable cancellation intent and activates live work only after an identity-bound receipt proves resource release and staging discard. A retry uses the same cancellation identity. A missing callback or receipt remains durably pending for retry; a conflicting or indeterminate receipt enters reconciliation. Every unresolved form blocks live activation and concurrent ownership. An explicit live terminal trigger requeues paused recorded work.

ADR 0046 records this decision. Durable queue and identity contracts, the authenticated Worker pull protocol and transport-agnostic Worker agent exist as foundation. The production app hard-disables the Worker router even when a valid credential is present until an expiring claim lease and verified result publisher are accepted. Installation of the exact executors, Worker deployment and wiring from the real K1 lifecycle to live-lease triggers remain pending. Therefore a submitted exact legacy M4.9T5 job may honestly wait in queued without implying that Worker 006 can execute it yet. Portable LAB V1 and portable M4.9T5 cannot currently be submitted because their executor states are not-installed and the authenticated Worker dispatch gate is closed.

Worker telemetry remains secondary observation evidence. It does not replace the authoritative queue ledger, result validation or common laboratory receipt. K1 acquisition and control, the legacy LAB archive, and Simulation/Gaussian runtimes are outside this boundary and are not restarted, migrated or modified by it.

Planning discipline

A planned LAB number is not a placeholder page. Before execution it must name:

1. one decision question or falsifiable hypothesis;
2. the exact immutable source and admitted derivative inputs;
3. the method identities and the one configuration allowed to vary;
4. the required visual evidence;
5. measurements, exclusions and predeclared thresholds;
6. the exit decision and the authority that remains forbidden.

After execution, the planned definition is retained in the immutable result. Changing the source, algorithm, model weights, preprocessing, thresholds or runtime creates a new LAB run. A failed experiment is publishable only when real input and failure evidence exist. A gate blocked before execution remains in the roadmap/Ops plan and does not create a LAB catalog item. An empty viewer or invented metric is never a laboratory result.

The accepted E30–E36 camera-first/K1 research sequence is maintained in docs/13_LIDAR_WORKER_PRODUCT_AND_ROADMAP.md. It deliberately starts with the E29 disagreement audit and recorded evidence already available in Mission Core. It does not require a connected K1 or new data collection before the existing recording has exhausted its admitted questions.

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.