docs(knowledge): LAB-vs-canonical firewall + 10 architecture invariants

.claude/agents/BOOT.md

@@ -159,6 +159,9 @@ documents listed in its trigger row BEFORE producing output.
 | **Story arc / ONNX emergence** | ripple-architect + contradiction-cartographer | crystal-quantum-blueprints.md (§Quantum mode), endgame-holographic-agi.md |
 | **Argmax / codec / PolarQuant** | truth-architect + family-codec-smith | fractal-codec-argmax-regime.md (ORTHOGONAL to grammar work) |
 | **Cross-repo harvest** | savant-research | cross-repo-harvest-2026-04-19.md, linguistic-epiphanies-2026-04-19.md |
+| **REST / gRPC / Wire DTO / endpoint / serve / shader-lab / external API** | integration-lead + truth-architect | **lab-vs-canonical-surface.md (MANDATORY — prevents System-1 "add another REST endpoint" hallucination)** |
+| **OrchestrationBridge / UnifiedStep / StepDomain / BridgeSlot** | integration-lead | lab-vs-canonical-surface.md, cam-pq-unified-pipeline.md |
+| **codec research / calibrate / probe / tensors op** | integration-lead + truth-architect | lab-vs-canonical-surface.md (research is just a consumer, not the canonical) |
 
 **The insight update cycle:**
 

CLAUDE.md

@@ -535,6 +535,7 @@ SIBLING REPOS:
 .claude/knowledge/two-basin-routing.md           — Two-basin doctrine, representation routing, pairwise rule, attribution
 .claude/knowledge/encoding-ecosystem.md          — MANDATORY: full encoding map, synergies, read-before-write checklist
 .claude/knowledge/frankenstein-checklist.md       — Composition failure modes (VibeTensor §7), boundary test matrix
+.claude/knowledge/lab-vs-canonical-surface.md     — MANDATORY before touching REST/gRPC/Wire DTO/endpoint/shader-lab (prevents "add another REST endpoint" hallucination)
 .claude/CALIBRATION_STATUS_GROUND_TRUTH.md       — OVERRIDE: read BEFORE any SESSION_*.md
 .claude/PLAN_BF16_DISTANCE_TABLES.md             — 5-phase plan for BF16 distance tables
 .claude/TECHNICAL_DEBT_SIGNED_SESSION.md          — 56% useful, 44% bypass (honest review)
@@ -548,6 +549,16 @@ codec, encoding, distance, compression, or representation work.** This is the
 map of all 8+ encoding representations, their crate locations, their invariants,
 their synergies, and their FINDING/CONJECTURE status. Never guess architecture.
 
+**P0 Rule: `.claude/knowledge/lab-vs-canonical-surface.md` must be read BEFORE
+any work that mentions REST, gRPC, Wire DTOs, `/v1/shader/*` endpoints, the
+shader-lab binary, `OrchestrationBridge`, `UnifiedStep`, codec research ops,
+or "external API".** The canonical consumer surface is `UnifiedStep` via
+`OrchestrationBridge` — the REST/gRPC server and per-op Wire DTOs are
+LAB-ONLY scaffolding. Adding another `/v1/<thing>` endpoint is the
+Kahneman-Tversky System-1 easy path and is nearly always wrong; extending
+the canonical bridge is the System-2 correct move. See the Decision
+Procedure in that doc before writing a single new handler.
+
 Every `.claude/knowledge/` document has a `READ BY:` header listing which agents
 MUST load it before producing output in that domain. When a knowledge trigger fires
 (see `.claude/agents/BOOT.md § Knowledge Activation Protocol`), the relevant

crates/cognitive-shader-driver/Cargo.toml

@@ -23,6 +23,15 @@ name = "shader-grpc"
 path = "src/bin/grpc.rs"
 required-features = ["grpc"]
 
+# shader-lab — the ONE lab binary. Compiles every endpoint behind the
+# unified DTO (UnifiedStep via OrchestrationBridge). Per-op endpoints
+# inside are lab-test shortcuts that dispatch through the same bridge
+# and are NEVER the canonical consumer surface.
+[[bin]]
+name = "shader-lab"
+path = "src/bin/serve.rs"
+required-features = ["lab"]
+
 [dependencies]
 lance-graph-contract = { path = "../lance-graph-contract" }
 p64-bridge            = { path = "../p64-bridge" }
@@ -58,4 +67,15 @@ with-planner = ["dep:lance-graph-planner"]
 serve = ["dep:serde", "dep:serde_json", "dep:axum", "dep:tokio"]
 grpc = ["dep:prost", "dep:tonic", "dep:tonic-build", "dep:tokio"]
 
+# `lab` — umbrella switch for the single shader-lab binary. Enables every
+# endpoint (REST + gRPC), the planner bridge, the thinking-engine bridge,
+# and the research consumer (codec_research + CodecResearchBridge).
+#
+# Architecture note: the canonical surface is `UnifiedStep` via
+# `OrchestrationBridge` from lance-graph-contract. The `lab` feature only
+# adds test-convenience wrappers (per-op Wire DTOs, HTTP/gRPC transports)
+# on top of that canonical trait. Research is just one consumer of the
+# unified DTO, not the reason the DTO exists.
+lab = ["serve", "grpc", "with-engine", "with-planner"]
+
 [dev-dependencies]

crates/cognitive-shader-driver/src/codec_bridge.rs

@@ -1,8 +1,16 @@
-//! OrchestrationBridge impl for codec research — owns `StepDomain::Ndarray`.
+//! **LAB-ONLY consumer.** `OrchestrationBridge` impl for codec research —
+//! owns `StepDomain::Ndarray`.
+//!
+//! The canonical architecture is `OrchestrationBridge` + `UnifiedStep` in
+//! the contract. Research is just one consumer plugged into that trait;
+//! production consumers plug in the same way under different `StepDomain`
+//! values (Crew / Ladybug / N8n / LanceGraph / Thinking / Query / Semantic
+//! / Persistence / Inference / Learning). The architecture does not
+//! revolve around this consumer.
 //!
 //! Dispatches `nd.calibrate`, `nd.probe`, `nd.tensors` step-types through
-//! the codec_research module. This complements the LanceGraph bridge on
-//! the planner — together they cover `lg.*` + `nd.*` domains.
+//! the codec_research module. Combined with the LanceGraph bridge on the
+//! planner, together they cover `lg.*` + `nd.*` domains.
 //!
 //! Consumers combine bridges: `Vec<Box<dyn OrchestrationBridge>>` and route
 //! each step to whichever bridge reports `domain_available() = true`.

crates/cognitive-shader-driver/src/codec_research.rs

@@ -1,13 +1,17 @@
-//! Codec research — backing logic for the `/v1/shader/{tensors,calibrate,probe}`
-//! DTO operations on the unified shader-driver API.
+//! **LAB-ONLY.** Codec research — one consumer of the unified DTO.
+//!
+//! Research is not the canonical architecture; it's a consumer like any
+//! other domain. It plugs into `OrchestrationBridge` via
+//! `CodecResearchBridge` (see `codec_bridge.rs`) under `StepDomain::Ndarray`.
+//! The functions below are the lab-convenience backing logic for the per-op
+//! Wire DTOs; the canonical dispatch path is `UnifiedStep` through the
+//! bridge.
 //!
 //! Reuses:
 //! - `ndarray::hpc::cam_pq::{train_geometric, CamCodebook}` — production codec
 //! - `ndarray::hpc::safetensors::read_safetensors_header` — tensor directory
 //! - `ndarray::hpc::gguf::read_tensor_f32` — BF16/F16/F32 dequant
 //! - `lance_graph_contract::cam::route_tensor` — CamPq / Passthrough / Skip
-//!
-//! Zero new feature gates — rides on the existing `serve` / `grpc`.
 
 use std::fs::File;
 use std::io::BufReader;

crates/cognitive-shader-driver/src/grpc.rs

@@ -1,7 +1,12 @@
-//! gRPC service — protobuf interface for live shader testing.
+//! **LAB-ONLY.** gRPC service — protobuf interface for live shader testing
+//! in the Claude Code backend. Not shipped to consumers.
 //!
-//! Behind `--features grpc`. Uses tonic + prost. Same quarantine as REST:
-//! debug-only, never in production binary.
+//! Same story as `serve.rs`: the canonical consumer surface is
+//! `UnifiedStep` + `OrchestrationBridge` in the library; this module just
+//! exposes that bridge over tonic/prost for test convenience.
+//!
+//! Behind `--features grpc` (or the umbrella `--features lab`). Uses
+//! tonic + prost. Never in any production binary.
 //!
 //! ```bash
 //! # Start gRPC server:

crates/cognitive-shader-driver/src/lib.rs

@@ -34,46 +34,111 @@
 //! - **Commit sinks** (`ShaderSink` trait; `NullSink` as zero-cost default)
 //! - **Feature gates** (`with-engine` pulls thinking-engine; core stays lean)
 //! - **No forward pass at runtime** — bgz17 distance is precomputed
+//!
+//! ---
+//!
+//! ## STOP — Canonical vs LAB-ONLY (read before touching this crate)
+//!
+//! **Do NOT add new REST endpoints, new per-op Wire DTOs, or new
+//! HTTP/gRPC handlers without reading
+//! `.claude/knowledge/lab-vs-canonical-surface.md` first.**
+//!
+//! **`cognitive-shader-driver` IS the unified API.** Its public
+//! re-exports form the super DTO family that every consumer speaks:
+//!
+//! - **Per-cycle hot path:** `ShaderDispatch` → `ShaderDriver` →
+//!   `ShaderHit` + `MetaWord` via `ShaderSink`. `BindSpace*` columns
+//!   are the substrate.
+//! - **Cross-domain composition:** `UnifiedStep` routed via
+//!   `OrchestrationBridge` by `StepDomain`. Every consumer
+//!   (thinking-engine, planner, codec research) plugs in through this
+//!   trait.
+//!
+//! Both layers are zero-dep, always compiled, and consumer-facing.
+//! That is the stable downstream-visible API.
+//!
+//! Everything else in this crate — `wire.rs`, `serve.rs`, `grpc.rs`,
+//! `codec_research.rs`, `codec_bridge.rs`, `planner_bridge.rs`, and the
+//! per-op `Wire*` DTOs — is **LAB-ONLY** scaffolding. It exists so the
+//! Claude Code backend can test the canonical bridge over HTTP/gRPC.
+//! It is **not** part of the consumer API. Future sessions must not
+//! "extend the REST API" with new per-op endpoints; they must extend the
+//! canonical bridge and let the lab transport follow automatically.
+//!
+//! Feature layout:
+//!
+//! ```text
+//! default       = canonical library surface only (no HTTP, no gRPC, no wire DTOs)
+//! serve         = lab REST transport
+//! grpc          = lab gRPC transport
+//! with-engine   = thinking-engine consumer wired in
+//! with-planner  = planner consumer wired in
+//! lab           = umbrella: all of the above → the shader-lab binary
+//! ```
+//!
+//! Research (codec_research, codec_bridge) is gated under serve/grpc
+//! because it only exists to be tested through the lab transport. It is
+//! one consumer of the unified DTO — not the reason the DTO exists.
 
 #![warn(rust_2018_idioms)]
 
+// ──────────────────────────────────────────────────────────────────────
+// Canonical surface — always compiled. Consumers depend on exactly this.
+// ──────────────────────────────────────────────────────────────────────
+//
+// The canonical consumer-facing DTO is `UnifiedStep` + `OrchestrationBridge`
+// re-exported from `lance-graph-contract` (see the `pub use` block below).
+// Everything below dispatches through that trait; research, planner, and
+// engine are just consumers that plug in via the bridge.
 pub mod bindspace;
 pub mod driver;
 pub mod auto_style;
 pub mod engine_bridge;
 pub mod sigma_rosetta;
 
-// Debug-only: REST server + wire types. NEVER in production binary.
-// serde is a debugging tool, not a runtime dependency.
+// ──────────────────────────────────────────────────────────────────────
+// LAB-ONLY modules — compiled only into the shader-lab binary. Never
+// shipped to downstream consumers; never part of the canonical API.
+// ──────────────────────────────────────────────────────────────────────
+//
+// Umbrella switch: `--features lab` turns on everything here at once.
+// Individual features (`serve`, `grpc`, `with-planner`, `with-engine`)
+// remain selectable for narrower lab builds.
+//
+// Architecture rule: these modules expose per-op Wire DTOs and REST/gRPC
+// transports for test convenience in the Claude Code backend. They all
+// ultimately route through `OrchestrationBridge` + `UnifiedStep` — the
+// canonical surface. No business logic lives here that isn't also
+// reachable through the canonical bridge.
+
+// Per-op Wire DTOs (REST + protobuf). LAB-ONLY.
 #[cfg(feature = "serve")]
 pub mod wire;
+
+// Axum REST server. LAB-ONLY.
 #[cfg(feature = "serve")]
 pub mod serve;
 
-// gRPC: protobuf + tonic. Also debug-only.
+// tonic gRPC server. LAB-ONLY.
 #[cfg(feature = "grpc")]
 pub mod grpc;
 
-// Codec research (calibrate / tensors / probe) — same debug quarantine
-// as serve. Rides on the unified shader-driver API surface; no new feature
-// gate. Runs the production CAM-PQ codec from ndarray against safetensors
-// tensors selected via route_tensor from lance-graph-contract.
+// Codec research consumer — backing logic for the research Wire DTOs.
+// LAB-ONLY. Research is one consumer of the unified DTO, not its reason.
 #[cfg(any(feature = "serve", feature = "grpc"))]
 pub mod codec_research;
 
-// Planner bridge — delegates WirePlan DTOs to lance-graph-planner's
-// PlannerAwareness. Optional, gated on `with-planner`. Same EmbedAnything
-// pattern as `with-engine`. Without this feature the shader-driver REST
-// server still works; /v1/shader/plan returns 503.
-#[cfg(feature = "with-planner")]
-pub mod planner_bridge;
-
-// OrchestrationBridge impl for codec research — owns StepDomain::Ndarray.
-// Dispatches nd.calibrate / nd.probe / nd.tensors through codec_research.
-// Complement to planner's LanceGraph bridge.
+// OrchestrationBridge impl for the codec research consumer — owns
+// StepDomain::Ndarray. LAB-ONLY (sits next to its backing logic).
 #[cfg(any(feature = "serve", feature = "grpc"))]
 pub mod codec_bridge;
 
+// Planner bridge — lab test-shortcut for the per-op WirePlan DTOs.
+// PlannerAwareness implements OrchestrationBridge directly in the
+// planner crate; that's the canonical path. LAB-ONLY.
+#[cfg(feature = "with-planner")]
+pub mod planner_bridge;
+
 pub use lance_graph_contract::cognitive_shader::{
     CognitiveShaderDriver, ColumnWindow, EmitMode, MetaFilter, MetaSummary, MetaWord,
     NullSink, RungLevel, ShaderBus, ShaderCrystal, ShaderDispatch, ShaderHit,

crates/cognitive-shader-driver/src/planner_bridge.rs

@@ -1,12 +1,16 @@
-//! Planner bridge — delegates `WirePlan*` DTOs to `lance-graph-planner`.
-//!
-//! Behind `--features with-planner`. Same pattern as `with-engine`:
-//! heavy dep is optional; absence returns a clear runtime error.
+//! **LAB-ONLY adapter.** Planner bridge — delegates `WirePlan*` DTOs to
+//! `lance-graph-planner`.
 //!
 //! Per INTEGRATION_PLAN_CS.md §5-layer-stack, Layer 4 is the planner.
-//! The shader-driver (Layer 2) exposes plan operations through the same
-//! unified REST/gRPC endpoint and delegates execution here. Nothing
-//! below Layer 4 reimplements planning.
+//! `PlannerAwareness` already implements `OrchestrationBridge` directly
+//! (see `lance-graph-planner/src/orchestration_impl.rs`); that's the
+//! canonical consumer surface. This module only exists as a test shortcut
+//! that converts the per-op `WirePlan*` DTOs into direct calls for the
+//! lab REST/gRPC transports.
+//!
+//! Behind `--features with-planner` (or the umbrella `--features lab`).
+//! Same pattern as `with-engine`: heavy dep is optional; absence returns
+//! a clear runtime error.
 
 use std::time::Instant;
 

crates/cognitive-shader-driver/src/serve.rs

@@ -1,4 +1,12 @@
-//! Axum REST server — external API for live testing cognitive shader cycles.
+//! **LAB-ONLY.** Axum REST server for live testing cognitive shader cycles
+//! in the Claude Code backend. Not shipped to consumers.
+//!
+//! Canonical consumer surface is `UnifiedStep` + `OrchestrationBridge` in
+//! the library. This server just exposes that bridge over HTTP for test
+//! convenience. Per-op endpoints (`/v1/shader/{calibrate,probe,tensors,
+//! dispatch,plan}`) are thin adapters that build a `UnifiedStep` and
+//! dispatch through the same bridge; the canonical endpoint is
+//! `/v1/shader/route`.
 //!
 //! ```bash
 //! cargo run -p cognitive-shader-driver --features serve --bin shader-serve

crates/cognitive-shader-driver/src/wire.rs

@@ -1,4 +1,13 @@
-//! Wire types for the external REST + protobuf API.
+//! **LAB-ONLY.** Wire types for the REST + protobuf transports used by the
+//! shader-lab binary. Not part of the canonical consumer surface.
+//!
+//! The canonical consumer surface is `UnifiedStep` + `OrchestrationBridge`
+//! from `lance-graph-contract`. Everything in this file — per-op DTOs
+//! (`WireDispatch`, `WireCalibrateRequest`, `WireProbeRequest`,
+//! `WireTensorsRequest`, `WirePlanRequest`, `WireRunbookRequest`) — is
+//! test-convenience scaffolding that ultimately dispatches through the
+//! same bridge. Consumers (including the research consumer) speak
+//! `UnifiedStep`, not these per-op shortcuts.
 //!
 //! These are the EXTERNAL types — serde + prost, owned strings, no lifetimes.
 //! Internal types in lance-graph-contract stay zero-dep and zero-copy.