NODEDC_MISSION_CORE/docs/adr/0039-bounded-laboratory-canonicalization-and-intentional-debt.md

ADR 0039: Bounded laboratory canonicalization and intentional debt

Date: 2026-08-05 Status: accepted; executable canary migration remains open

Context

Mission Core accumulated valuable immutable laboratory evidence while the perception contracts, worker boundary and product presentation were still being discovered. Rewriting every historical experiment would consume the same effort as new product work, risk changing preserved evidence and falsely imply that old runs were produced by contracts which did not exist at the time.

The opposite extreme is also unsafe. If every new experiment adds another core router, application branch and presentation component, the product composition will keep growing with the research history. A novel detector, runtime or evaluation method must remain possible without either being discarded or being promoted directly into the stable product architecture.

ADR 0036 made standard evidence discovery configurative. ADR 0038 made the selected immutable evidence report generic and proof-bound. Neither decision made the historical experiment implementations reusable execution graphs.

Decision

Mission Core admits three laboratory lifecycle classes.

Canonical

A canonical LAB uses versioned source, provider, graph and run contracts. Its runner automatically publishes identity, configuration, method, runtime, resources, metrics, gates, artifacts, visual evidence, limitations and retained authority. Adding an ordinary canonical LAB must not add an experiment-specific branch to the application shell or product composition root.

The first executable canaries are deliberately limited to:

• E33 worker shadow, for source pacing, queues, worker identity and telemetry;
• E35 degradation/recovery, for deterministic graph variants and safe terminal accounting;
• E46J raw-fisheye realtime, for model/runtime configuration, GPU capacity and full visual evidence.

Passing those three canaries closes the laboratory canonicalization slice. It does not authorize a bulk migration of historical runs.

Experimental

An experimental LAB may use a stack or execution shape which the current canonical graph cannot express. It is retained through a bounded adapter or separate experiment package instead of being deleted or hidden.

It must still freeze:

• the immutable source and derivative inputs;
• code, configuration, model/runtime and provider identities which are known;
• real artifacts, visual evidence and resource observations;
• terminal outcome, limitations and forbidden authority.

An experimental adapter may not silently change generic product behavior, grant command/navigation/safety authority or require a new visual language. Repeated demonstrated value is the trigger for promotion into a versioned provider or graph contract. Novelty by itself is not a failure and is not a reason to discard evidence.

Legacy

Legacy LABs remain immutable and read-only through their existing validators and bounded projectors. Missing historical provenance remains explicit. Legacy code is changed only for integrity, security, compatibility or preservation defects; it is not rewritten for cosmetic uniformity.

Legacy evidence may be compared or reused as an input reference, but it does not become canonical execution evidence retroactively.

Core admission rule

Architecture tests must prevent uncontrolled core growth, not experimental work itself. A failure is one of the following:

• a canonical LAB needs a new experiment-named branch in app.py, the advanced LAB dispatcher or the generic workspace;
• evidence publication bypasses identity, artifact or authority validation;
• reusable provider or graph behavior is copied into another experiment;
• an experimental implementation is imported by core without an explicit bounded adapter and lifecycle classification.

A self-contained experimental package with honest evidence is allowed even when its stack cannot yet satisfy the canonical graph.

Worker and telemetry boundary

The compute-contour catalog, selector, generic MQTT topic namespace and telemetry query path already support more than one contour. They do not constitute worker provisioning. Credential enrollment, a digest-bound agent bundle and an accepted second agent remain open. Installing GPU drivers, Docker/WSL, Triton, models and the perception runtime is a separate deployment-profile problem and is not folded into a universal one-click installer.

Local telemetry stabilization is part of the architecture freeze: multi-contour credential issuance, executable agent installation, bounded journal rotation, restart/reconnect/duplicate handling, stale and identity-mismatch behavior, and run correlation must be accepted. Fleet TLS, Linux acceptance, HA and production storage/deployment remain explicit intentional debt until their deployment trigger exists.

Consequences

• The historical archive remains useful without dictating current code shape.
• Three representative LABs, not the whole archive, prove the executable canon.
• A new research stack has a legitimate bounded path and is not forced into a premature universal abstraction.
• The product core grows only when repeated value justifies a reusable contract.
• Debt is not treated as a binary pass/fail list: every deferred item names the claim it blocks and the event which returns it to the critical path.