docs(knowledge): LAB-vs-canonical firewall + 10 architecture invariants#223
Merged
Conversation
cognitive-shader-driver IS the unified API. Its re-exported super DTO family (ShaderDispatch/ShaderHit/MetaWord/BindSpace/ShaderDriver plus UnifiedStep/OrchestrationBridge) is the ONLY consumer-facing surface. REST/gRPC servers, per-op Wire DTOs, codec_research, codec_bridge, planner_bridge are LAB-ONLY scaffolding for Claude Code backend testing — never shipped to consumers. - Cargo.toml: `lab` umbrella feature (serve+grpc+with-planner+ with-engine) and shader-lab binary. Canonical library surface available with zero features; REST+gRPC coexist behind siblings. - lib.rs: explicit "Canonical / LAB-ONLY" section header + STOP block pointing future sessions at the knowledge doc before they add REST endpoints. - wire / serve / grpc / codec_research / codec_bridge / planner_bridge: `//! **LAB-ONLY.**` banners naming the hallucination failure mode and the canonical alternative. Anti-hallucination docs: - .claude/knowledge/lab-vs-canonical-surface.md — Decision Procedure, Kahneman-Tversky / Dunning-Kruger traps named explicitly, 5-layer stack mapping (L0 ndarray → L4 Planner), list of every canonical re-export. - .claude/agents/BOOT.md — 3 new activation triggers (REST/gRPC/Wire DTO; OrchestrationBridge/UnifiedStep; codec research). - CLAUDE.md — P0 rule for the new knowledge doc. Grounded against THINKING_RECONCILIATION.md, INTEGRATION_PLAN_CS.md, BINDSPACE_MIGRATION_GAP.md, COGNITIVE_SHADER_HYDRATION.md, COGNITIVE_MERGE_MAP.md, SESSION_HANDOFF_PRIORITIES.md, CODEC_INVARIANTS_AND_EXPERIMENTS.md. Research is one consumer of the unified DTO via StepDomain::Ndarray — not the reason the DTO exists. Build: both `cargo check` (canonical, no features) and `cargo check --features lab` compile clean. `cargo test --lib --features lab` → 46 passing. Zero runtime cost on canonical path. https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh
Extends lab-vs-canonical-surface.md with: - AGI IS the struct-of-arrays section (Era 8 CognitiveRecord → 4-axis BindSpace columns: topic/angle/thinking/planner) - Per-cycle contract: dispatch/branch/merge/dream lifecycle - Migration status note (4-column SoA distills 11-field Era 8) - 10 non-negotiable architecture invariants citing docs/: 1. BindSpace read-only + CollapseGate airgap protocol 2. ndarray::simd::* canonical import rule 3. Layer temporal scopes (L0 sub-ns → L4 ms) 4. Temperature hierarchy (Hot/Warm/Cold/Frozen) 5. Thinking = AdjacencyStore (one engine, two graphs) 6. Weights are seeds (GGUF → hydrate → BindSpace, no matmul) 7. Per-cycle cascade budget (~2.3ms/1M, monotone narrowing) 8. 4096 address surface (16 prefix × 256 slots) 9. Three DTO families (Stream/Resonance/Bus) — doctrinal 10. HEEL/HIP/BRANCH/TWIG/LEAF progressive precision hierarchy Grounded in: INTEGRATION_PLAN_CS.md, COGNITIVE_SHADER_HYDRATION.md, SEMIRING_ALGEBRA_SURFACE.md, METADATA_SCHEMA_INVENTORY.md, THINKING_PIPELINE.md, integrated-architecture-map.md, ZECKF64_VSA_SYNERGY_MAP.md, HISTORICAL_CONTEXT.md. https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh
Remove duplicate "Architecture Invariants (from docs/)" that was positioned after the doc's closing sentinel. The canonical version (I1-I10) sits inside the doc body at its correct structural position. https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 59adfb973b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+31
to
+33
| name = "shader-lab" | ||
| path = "src/bin/serve.rs" | ||
| required-features = ["lab"] |
There was a problem hiding this comment.
shader-lab is introduced as the umbrella lab target, but it is wired to src/bin/serve.rs, whose main only launches the Axum HTTP server; it never starts the tonic gRPC server path. In practice, running cargo run --features lab --bin shader-lab enables gRPC dependencies but exposes only REST, so any workflow expecting gRPC from the new single lab binary will fail at runtime.
Useful? React with 👍 / 👎.
The LAB-ONLY surface isn't just quarantine scaffolding — it's the codec-research iteration testbed. Its reason for existing is the cost of the alternative: every codec candidate re-measured through a cargo build cycle burns minutes per iteration. With the lab REST/gRPC + wire DTOs, a single binary serves dozens of candidates against the same safetensors in seconds per call. PR #220 falsified PR #219's ICC-0.9998 claim via exactly this path: the calibration CLI + /v1/shader/calibrate endpoint surfaced mean ICC 0.195 / 0/234 pass rate on full Qwen3-TTS-0.6B tensors before any production consumer linked the codec. Two purposes now named explicitly in the doc: 1. Iteration velocity (positive) — lab surface = curl-friendly research loop, no rebuild per candidate. 2. Canonical firewall (guard) — consumers still walk UnifiedStep via OrchestrationBridge; they never see Wire* per-op DTOs. Changes: - New subsection "Why the Lab Surface Exists (positive purpose — not just quarantine)" with the #219 → #220 worked-example table. - Decision Procedure item 3 reframed: research ops and curl-friendly debug shortcuts are a legitimate use of the lab surface, with a graduation rule (full-size validation → new StepDomain variant; lab endpoint stays for continued iteration, production moves to bridge). https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh
AdaWorldAPI
pushed a commit
that referenced
this pull request
Apr 20, 2026
Retroactive hygiene for the recent PR arc + prospective enforcement so the gap never recurs. User directive: "should have happened to begin with." LATEST_STATE.md: - Header: "Last updated 2026-04-20 post PR #224 (PR #225 open)" - Recently Shipped table: prepended rows for #225 (open), #224, and #223 with full shipped-content summaries - Contract Inventory: expanded cam:: entry with all new codec- sweep types (LaneWidth / Distance / Rotation / ResidualSpec / CodecParams / CodecParamsBuilder / CodecParamsError) including the precision-ladder-fires-before-JIT invariant - Active Branches: recorded claude/teleport-session-setup-wMZfb and its three merged PRs - Active Integration Plans: added codec-sweep-via-lab-infra-v1 alongside elegant-herding-rocket-v1 - Immediate Next Work: codec-sweep Phase 0 remainder (D0.1/0.2/0.3/ 0.5) + the elegant-herding Phase 2 block PR_ARC_INVENTORY.md (APPEND-ONLY — PREPEND only): - #225 entry: plan + CodecParams/Builder/precision validation + rules A-F locked + decisions for future PRs - #224 entry: three-part lab stack + thinking harvest + I11 measurability locked - #223 entry: LAB-ONLY firewall + AGI-as-SoA + I1-I10 invariants locked (the cross-cutting architectural ruleset this workspace now enforces) STATUS_BOARD.md: - New section: codec-sweep-via-lab-infra-v1 with 18 D-ids across 5 phases (D0.6/D0.7 marked Shipped-in-#225; remainder Queued) EPIPHANIES.md (APPEND-ONLY — PREPEND only, 6 new dated entries): - Board hygiene is the driving seat, not cleanup (this session's self-reflection turned into a rule) - Codec cert is token agreement, not synthetic ICC (#219 → #220 arc; #225 CalibrationEqualsMeasurement typed rejection) - Lab REST surface is three-part (API + Planner + JIT), not just scaffolding - Thinking harvest via REST/Cypher = the AGI magic bullet - SoA never scalarises without ndarray (iron rule Rule C) - AGI is the glove, not the oracle — four-axis SoA is what you wear CLAUDE.md — new top-level § "The Stance — Driving Seat + AGI-as-Glove (P0, read first)": - Explicit driving-seat posture: the session STEERS the stack, doesn't observe it - AGI-as-glove doctrine concrete: topic → FingerprintColumns, angle → QualiaColumn, thinking → MetaColumn, planner → EdgeColumn. New capability lands as a new column, not a layer. - MANDATORY Board-Hygiene Rule as a table: every PR that adds a type / plan / D-id / epiphany / tech-debt / issue MUST update the corresponding board file IN THE SAME COMMIT. Retroactive hygiene (merge PR → later cleanup) is now an anti-pattern the rule forbids. - "Consult, don't guess" — agent/knowledge-first discipline: specialist-agent card → knowledge doc → board inventory → only then grep. Subagent spawn with curated docs beats main- thread grep. 147/147 contract suite still passing. Doc-only PR otherwise (Cargo.toml / src/* unchanged; the orphan serde_yaml/base64 deps from the timed-out bus-compiler subagent were reverted — they'll land with D0.1/D0.3 when the Wire code lands). https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Hardens
.claude/knowledge/lab-vs-canonical-surface.mdinto thecross-cutting anti-hallucination guard for the cognitive-shader-driver
surface. Three commits on this branch:
b183673—lab-vs-canonical-surface.mdinitial doc: theLAB-ONLY vs canonical split (REST/gRPC server, Wire DTOs, per-op
handlers are scaffolding;
UnifiedStepviaOrchestrationBridgeis the canonical consumer surface). CLAUDE.md P0 rule added:
read this before touching REST/gRPC/shader-lab/OrchestrationBridge.
62530f4— AGI-as-struct-of-arrays invariant + 10architecture rules (I1–I10) folded in from 8 absorbed docs.
59adfb9— dedup fix (accidentally landed two "ArchitectureInvariants" sections; kept the well-positioned one, removed the
trailing duplicate).
The 10 Invariants (cite these; do not drift)
Arc<[u64; 256*N]>+ CollapseGate airgap (XOR/Bundle merge modes)docs/INTEGRATION_PLAN_CS.mdndarray::simd::*— neverndarray::hpc::*docs/INTEGRATION_PLAN_CS.mddocs/COGNITIVE_SHADER_HYDRATION.mddocs/SEMIRING_ALGEBRA_SURFACE.mdAdjacencyStore— 36 styles at τ-prefix 0x0D; one engine, two graphsdocs/THINKING_PIPELINE.mddocs/COGNITIVE_SHADER_HYDRATION.mddocs/COGNITIVE_SHADER_HYDRATION.mdAddr(u16)docs/METADATA_SCHEMA_INVENTORY.mddocs/integrated-architecture-map.mddocs/integrated-architecture-map.mdPlus the session-level anchor: AGI = (topic, angle, thinking,
planner) = struct-of-arrays consuming cognitive-shader-driver
identity. The super-DTO family IS the unified API; the 4-column
BindSpace (fingerprints / qualia / meta / edges) is the distilled
Era-8 CognitiveRecord.
PR #221 Audit (architecturally clean — included context)
Verified that PR #221's codec-research REST/gRPC + planner bridge
did NOT violate these invariants:
codec_research.rs— no semiring references. Research functions(
list_tensors,calibrate_tensor,row_count_probe) operate ontensor metadata only.
codec_bridge.rs:101—SemiringChoice::HammingMinappears onlyas step metadata on the
UnifiedStep, not as an op.PaletteSemiring— stayspub(crate)insideShaderDriver(L2 nanosecond budget); never re-exported from
lib.rs.OrchestrationBridge for PlannerAwareness— correctly placed inthe canonical planner crate; always compiled.
Forward risk flagged:
ShaderDriver.semiringispub(crate)today. A future session tempted to make it
pubwould violate I4(temperature hierarchy keeps the semiring on the hot path only).
Docs Absorbed Into Invariants
docs/COGNITIVE_SHADER_HYDRATION.mddocs/INTEGRATION_PLAN_CS.mddocs/METADATA_SCHEMA_INVENTORY.mddocs/SEMIRING_ALGEBRA_SURFACE.mddocs/ZECKF64_VSA_SYNERGY_MAP.mddocs/integrated-architecture-map.mddocs/THINKING_PIPELINE.mddocs/endgame-holographic-agi.md(partial) +docs/p1-audit-status.mdPlus
.claude/board/LATEST_STATE.md+.claude/phases/integration_phases.mdfor current-state grounding.
Test Plan
lab-vs-canonical-surface.mdis referenced by CLAUDE.md P0 rule(pre-existing) so future sessions will actually load it
a future session can drill down without re-reading everything
59adfb9dedup fix)https://claude.ai/code/session_01SbYsmmbPf9YQuYbHZN52Zh