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

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.

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.