refactor(platform): bound lab canon and contour identity

2026-08-05 12:00:27 +03:00
parent de12e96297
commit 6d0abbc569
10 changed files with 199 additions and 8 deletions
@@ -0,0 +1,116 @@
+# 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.
+