LinxISA · zhoubot · Jun 9, 2026
diff --git a/docs/architecture/interfaces.md b/docs/architecture/interfaces.md
@@ -1,12 +1,5 @@
 # LinxCore External Interface Contracts
 
-This document defines the externally consumed LinxCore interface contracts for
-model integration, trace generation, and cross-tool synchronization.
-
-The contracts below are normative for pyCircuit, testbench, trace tooling,
-viewer tooling, and any other producer or consumer that observes LinxCore
-through non-ISA interfaces.
-
 ## pyCircuit-LinxCore interface contract (LC-IF-PYC-001)
 
 The pyCircuit/LinxCore integration contract is versioned and gate-enforced.
@@ -20,28 +13,17 @@ Rules:
 
 - Contract version follows `MAJOR.MINOR`.
 - Backward-compatible additions increment `MINOR`.
-- Breaking field removals, renames, or semantic redefinitions increment
-  `MAJOR`.
+- Breaking field removals/renames or semantic redefinitions increment `MAJOR`.
 - Gate tooling rejects unversioned interface breaks.
 
-The pyCircuit interface contract is the required compatibility boundary for:
-
-- pyCircuit-generated DUTs,
-- C++ testbench integration,
-- compare tooling,
-- commit-trace consumers used by QEMU correlation and bring-up gates.
-
 ## Required commit payload contract (LC-IF-PYC-002)
 
 Required commit fields from `pyc_linxcore_interface_contract.json`:
 
 - `cycle`, `pc`, `insn`
-- `src0_valid`, `src0_reg`, `src0_data`
-- `src1_valid`, `src1_reg`, `src1_data`
-- `dst_valid`, `dst_reg`, `dst_data`
 - `wb_valid`, `wb_rd`, `wb_data`
-- `mem_valid`, `mem_is_store`, `mem_addr`, `mem_wdata`, `mem_rdata`, `mem_size`
-- `trap_valid`, `trap_cause`, `traparg0`, `next_pc`
+- `mem_valid`, `mem_addr`, `mem_wdata`, `mem_rdata`, `mem_size`
+- `trap_valid`, `trap_cause`, `next_pc`
 
 Required environment controls:
 
@@ -50,164 +32,58 @@ Required environment controls:
 - `PYC_MEM_BYTES`
 - `PYC_MAX_CYCLES`
 
-Canonical producers and consumers live under:
-
-- `rtl/LinxCore/tb/`
-- `rtl/LinxCore/tools/trace/`
-- `tools/bringup/check_pycircuit_interface_contract.py`
-
-### Commit stream rules
-
-- Commit payloads describe architecturally retiring work only.
-- Multi-commit cycles must retain per-slot ordering semantics.
-- Empty placeholder rows are forbidden in the architecturally compared commit
-  stream.
-- Commit-side trap, memory, and writeback payloads must remain coherent with
-  the retiring uop or macro event they describe.
-- Source-operand validity, register identity, and value correlation are
-  required contract payload, not optional debug metadata.
-- Destination correlation must remain explicit even when `wb_*` aliases are
-  also present for backward consumer convenience.
-
-### DUT control rules
-
-- Boot, memory-size, and commit-trace control environment variables are part of
-  the external contract, not incidental implementation details.
-- A contract-visible change in required environment controls must be versioned
-  the same way as a field-level interface change.
-
-## Block command fabric contract
-
-The block-command interface remains part of the externally visible LinxCore
-behavior because backend, `BISQ`, `BCTRL`, and engine paths must agree on a
-single command envelope.
-
-Required block-command fields:
-
-- `cmd_valid`
-- `cmd_kind[2:0]`
-- `cmd_tag[7:0]`
-- `cmd_tile[5:0]`
-- `cmd_payload[63:0]`
-- `cmd_src_rob`
-- `cmd_bid`
-
-Required rules:
-
-- `cmd_tag == bid[7:0]`
-- response tags route back to the correct `BROB` entry
-- `BID` remains visible through enqueue, issue, completion, and flush rollback
-
-### Block command response rules
-
-- Command responses must preserve source-to-`BROB` routing correctness.
-- Tag reuse must remain synchronized with `BID` lifetime and flush semantics.
-- Engine-local completion metadata must not bypass block-level retirement rules.
-
-Detailed command-lane behavior remains in:
-
-- `rtl/LinxCore/docs/architecture/block_fabric_contract.md`
-
-## Memory and MMIO visibility contract
-
-The external LinxCore memory-visible contract includes:
-
-- architecturally visible load/store commit payloads,
-- committed-store drain visibility where applicable,
-- MMIO-visible UART and exit signaling used by canonical bring-up flows.
-
-Rules:
-
-- MMIO-visible effects must remain explicit and traceable.
-- Memory metadata exported through commit trace must remain sufficient for
-  architectural compare and debugging flows.
-- Memory-side debug metadata may be additive, but it must not redefine the
-  required commit payload semantics.
-
 ## LinxTrace schema contract (LC-IF-TRACE-001)
 
 Trace schema governance:
 
-- canonical schema contract: `docs/bringup/contracts/trace_schema.md`
-- runtime format contract: `rtl/LinxCore/docs/trace/linxtrace_v1.md`
-- pipeline refresh rule: `rtl/LinxCore/docs/trace/linxtrace_pipeline_refresh_rule.md`
+- canonical contract: `docs/bringup/contracts/trace_schema.md`
 - producer-side schema validation: `tools/bringup/validate_trace_schema.py`
 - SemVer compatibility gate: `tools/bringup/check_trace_semver_compat.py`
 
 Rules:
 
-- LinxTrace output is a single `*.linxtrace` JSONL file.
-- The first non-empty record is `{"type":"META", ...}`.
 - `MAJOR` schema mismatch is a hard failure.
-- `MINOR` requires producer version to satisfy consumer expectations.
+- `MINOR` must be producer >= consumer expectation.
 - Breaking trace changes require major bump and migration checks.
 
-### Required trace content
-
-- The trace must define stage, lane, and row catalogs in-band.
-- Unknown stage, lane, or row identifiers are hard errors.
-- Stage ownership must come from real producer-side stage state, not
-  viewer-side reconstruction.
-- Trace rows must preserve block and uop identity sufficiently for
-  LinxCoreSight and compare tooling to render without inventing lifecycle
-  state.
-
 ## Trace compatibility contract (LC-IF-TRACE-002)
 
 - `linxtrace.v1` remains stable for additive changes.
-- Major-version bump is mandatory for incompatible field or semantic changes.
+- Major-version bump is mandatory for incompatible field/semantics changes.
 - Compatibility checks must fail fast on major mismatch.
-- Producer-side fixes are preferred over compare-tool masking when trace
-  content diverges from architectural behavior.
-
-Backward-compatible additions must not silently change the meaning of existing
-fields or lifecycle ordering.
 
 ## Cross-tool synchronization contract (LC-IF-SYNC-001)
 
-The following must stay synchronized when trace or pipeline contracts change:
+The following must stay synchronized when trace/pipeline contracts change:
 
 - `rtl/LinxCore/src/common/stage_tokens.py`
 - `rtl/LinxCore/tb/tb_linxcore_top.cpp`
 - `rtl/LinxCore/tools/trace/build_linxtrace_view.py`
 - `rtl/LinxCore/tools/linxcoresight/lint_linxtrace.py`
 - `rtl/LinxCore/tools/linxcoresight/lint_trace_contract_sync.py`
 
-Viewer-side contract sync is validated through LinxTrace gates.
-
-The published superproject LinxCore mirror pages are part of this
-cross-tool/publication contract: they must remain synchronized with the
-canonical submodule docs after contract edits.
-
 ## Scope boundary
 
-This document covers external LinxCore interface governance only:
+This document covers **external** LinxCore interface governance only:
 
-- pyCircuit contract,
-- trace schema contract,
-- cross-tool synchronization rules.
+- pyCircuit contract
+- trace schema contract
+- cross-tool synchronization rules
 
-Detailed LinxCore microarchitectural interface contracts, including the
-two-layer block machine, `BROB`-facing resolve behavior, raw engine fabric, and
-engine/block-type mapping, belong under:
+Detailed LinxCore **microarchitectural** interface contracts (two-layer block machine, `BROB`-facing resolve,
+raw engine fabric, engine/block-type mapping) belong under:
 
 - `rtl/LinxCore/docs/architecture/`
-- `rtl/LinxCore/docs/architecture/microarchitecture.md`
+- `docs/architecture/linxcore/microarchitecture.md`
 
-The promoted stage contracts from `F0` through the baseline issue/wakeup slice
-(`S1`, `S2`, `P1`, `I1`, `I2`, `E1`, `W1`) are captured normatively in the
-canonical microarchitecture page, while this document remains limited to
-external and tool-facing governance.
+For the current architecture-writing pass, the promoted stage contracts from
+`F0` through the baseline issue/wakeup slice (`S1/S2/P1/I1/I2/E1/W1`) are
+captured normatively in `docs/architecture/linxcore/microarchitecture.md`,
+while this document remains limited to external/tool-facing interface
+governance.
 
 ## Interface change control
 
 - Interface-visible changes must update contract artifacts first.
-- Gate rows in `rtl/LinxCore/docs/architecture/verification-matrix.md` are the
-  release blocker for interface promotion.
+- Gate rows in `docs/architecture/linxcore/verification-matrix.md` are the release blocker for interface promotion.
 - Any contract-major bump must include migration notes and dual-lane evidence.
-- Published mirrors in `docs/architecture/linxcore/` must be regenerated after
-  contract edits.
-
-Deep-dive implementation notes may expand a mechanism, but they must not create
-an alternative compatibility contract outside this document and the referenced
-machine-readable artifacts.
diff --git a/docs/architecture/microarchitecture.md b/docs/architecture/microarchitecture.md
@@ -1,8 +1,8 @@
-# LinxCore v0.4 Microarchitecture Contract
+# LinxCore v0.56 Microarchitecture Contract
 
 ## Baseline superscalar contract
 
-LinxCore is the canonical superscalar out-of-order core for LinxISA `v0.4`.
+LinxCore is the canonical superscalar out-of-order core for LinxISA `v0.56`.
 It retires precisely, executes out of order, and preserves a block-ordered
 architectural control model across scalar and engine-backed work.
 
@@ -14,14 +14,14 @@ Current baseline limits:
 - commit width: up to 4
 - LSU width: 1
 
-These limits are the live `v0.4` closure baseline. Wider issue or multi-LSU
+These limits are the live `v0.56` closure baseline. Wider issue or multi-LSU
 scaling is a follow-on track, not part of the normative contract here.
 
 ## Architectural state model
 
 LinxCore must preserve the following architectural state classes:
 
-- scalar, control, and privilege state defined by LinxISA `v0.4`,
+- scalar, control, and privilege state defined by LinxISA `v0.56`,
 - CSR, trap, MMU, and interrupt-visible state,
 - block-visible architectural state for `BSTART`, `BSTOP`, and
   boundary-authoritative redirect,
@@ -181,8 +181,6 @@ future canonical updates, but it must not contradict the rules below.
 - `D2` is the rename request and translation stage.
 - `D2` preserves decode-slot program order across one decode group.
 - `D2` resolves boundary metadata and prepares ROB-visible boundary uops.
-- `D2` also resolves immediate-only architectural producers that must bypass
-  IQ allocation and late writeback, including `SETRET` and `C.SETRET`.
 - `D2` carries the canonical architectural uop shape:
 
 ```text
@@ -513,7 +511,7 @@ Detailed BROB and block-fabric behavior remains documented in:
 ## MMU contract (LC-MA-MMU-001)
 
 - Translation success and failure must produce deterministic trap envelopes.
-- MMU behavior must remain aligned with the `v0.4` privileged contract wording.
+- MMU behavior must remain aligned with the `v0.56` privileged contract wording.
 - MMU fault paths must preserve precise retirement and recovery ordering.
 
 ## Interrupt contract (LC-MA-IRQ-001)
@@ -565,8 +563,11 @@ Detailed ordering behavior remains documented in:
 ### Workload-engine composition
 
 - `VEC` remains the general programmable SIMT compute engine.
-- `TMA`, `CUBE`, and `TAU` integrate into LinxCore through the same block/BID
-  contract as the rest of the machine.
+- `TMA` integrates into LinxCore through the same block/BID contract as the
+  rest of the machine, but its southbound memory traffic is owned by the CSU
+  subsystem and targets CSU L2 alongside frontend refill traffic.
+- `CUBE` and `TAU` continue to integrate through the same block/BID contract
+  as peer engines.
 - Engine issue, completion, exception, and flush behavior must remain visible
   to ROB, BROB, and trace machinery through the canonical interfaces.
 

diff --git a/docs/architecture/module-catalog.md b/docs/architecture/module-catalog.md
@@ -1,7 +1,7 @@
 # LinxCore Module Catalog
 
 This chapter defines the canonical module structure for LinxCore under the live
-`v0.4` superscalar contract.
+`v0.56` superscalar contract.
 
 It freezes which module families own architectural behavior, which files are
 the canonical owners of those behaviors, and how those modules compose into the
@@ -175,9 +175,6 @@ metadata, and UID allocation required by the stage, block, and trace contracts.
 - Owns `D2`.
 - Performs rename request/translation preparation and resolves ROB-visible
   boundary metadata for `BSTART` and `BSTOP`.
-- Also resolves immediate-only return-target producers `SETRET` and
-  `C.SETRET`, which bypass IQ ownership and complete from the D2 path.
-
 ### `src/bcc/ooo/ren.py`
 
 - Owns `D3`.
@@ -392,13 +389,25 @@ metadata, and UID allocation required by the stage, block, and trace contracts.
 
 ## Engine and accelerator modules
 
+### `src/csu/subsystem.py`
+
+- Owns the unified CSU parent subsystem that absorbs IFU refill traffic and
+  CSU-internal TMA transport ownership.
+
+### `src/csu/{tma_cmd_frontend,tma_ctx_tracker,tma_l2_client,client_arb}.py`
+
+- Own the CSU-internal TMA command ingress, context tracking, L2-client
+  translation, and refill-versus-TMA arbitration boundaries.
+
 ### `src/vec/vec.py`
 
 - Owns the `VEC` engine boundary.
 
 ### `src/tma/tma.py`
 
-- Owns the `TMA` engine boundary.
+- Remains the standalone compatibility facade for isolated TMA unit tests.
+- Janus top-level integration no longer treats it as the normative southbound
+  transport owner.
 
 ### `src/cube/cube.py`