clm-kernel 0.0.4__tar.gz → 0.0.11__tar.gz

{clm_kernel-0.0.4 → clm_kernel-0.0.11}/.gitignore

@@ -16,9 +16,9 @@
 # The whole runtime directory: the three tapes, the lifecycle sidecars (ORC-29), and
 # `.init_done`. Nothing here is source, and an untracked entry refuses a sandwich for no
 # reason — the loop scopes `dirty` to the target's own tracked content.
-db/
-db/snapshots/
-db/.init_done
+/db/
+/db/snapshots/
+/db/.init_done
 data/*.db
 graphify-out/
 .graphify-out/
@@ -72,6 +72,7 @@ output.txt
 dummy.yaml
 test.yaml
 py_esc1.yaml
+%SystemDrive%/
 scratch.sh
 run_manual
 test_rust_exec
@@ -96,9 +97,18 @@ meta_functionality.db
 *.so
 *.dylib
 *.dll
+*.pyd
+kernel/clm_py_core/*.exe
 
 # Ephemeral test and build data
 kernel/clm_rust_core/data/
+kernel/clm_py_core/clm/logs/
 kernel/clm_py_core/clm/tests/
+kernel/clm_py_core/clm/tests/data/*.db
 tests/data/
+.artifacts/
+
+# OS metadata
+.DS_Store
+Thumbs.db
 

{clm_kernel-0.0.4 → clm_kernel-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clm-kernel
-Version: 0.0.4
+Version: 0.0.11
 Summary: Card Lifecycle Manager (CLM) Kernel — Sovereign Functional Agentic Operating System
 Author: GovTech Digital Identity & Autonomous Systems
 License: MIT
@@ -27,6 +27,7 @@ Requires-Dist: duckdb>=1.0.0
 Requires-Dist: fastapi>=0.100.0
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: mpmath>=1.3.0
 Requires-Dist: networkx>=3.0
 Requires-Dist: pillow>=10.0.0
 Requires-Dist: pydantic>=2.0.0

clm_kernel-0.0.11/README.md

@@ -0,0 +1,316 @@
+# Cubical Logic Model (CLM)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests: 1,677 Passing](https://img.shields.io/badge/Tests-1%2C677%20Passing-brightgreen)](tests/)
+[![Rust: 2024 Edition](https://img.shields.io/badge/Rust-2024%20Edition-orange)](kernel/clm_rust_core/)
+[![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)](kernel/clm_py_core/)
+[![Node.js: 20+](https://img.shields.io/badge/Node.js-20%2B-green)](kernel/clm_js_core/)
+[![Polyglot Consensus: 100%](https://img.shields.io/badge/Polyglot%20Consensus-100%25-success)](tests/polyglot/)
+[![Boundary Gates: 30/30 Green](https://img.shields.io/badge/Boundary%20Gates-30%2F30%20Green-brightgreen)](tools/make/boundaries.mk)
+
+> **The Cubical Logic Model (CLM)** is a polyglot computational substrate and conversational operating system implementing the Kenotic Layer 0–5 strata. Using **Cordis Calculus** (spatiotemporal composability & reversible `Fiber` effects), **Type Lattice Theory** (stratified universes, Bounded Place Type Lattice $\mathcal{L}_N$, & MISU Meet gates), and **Petri Net Algebra** (All-`MCard` Triad, linear incidence conservation $x^\top D = 0^\top$, cyclic T-invariants $D y = 0$, Siphons & Traps) as foundational primitives, CLM articulates **Storage Resource**, **Data Transport Activities**, **Learning State Changes**, and **Security Perimeter** across Python, Rust, and TypeScript runtimes. Cross-runtime equivalence is established per declared feature and shared test vector; it is not a blanket claim that every API or behavior is identical.
+
+> **MCard sync status (`EPIC-KX` / `SyncContract v1`):** the published package line is `0.0.10`; the workspace line is `0.0.11`. Under `EPIC-KX` (`KX-01`..`KX-07`), CLM implements the additive 4-module **`SyncContract v1`** (`types`, `codec`, `petri`, `service`) across JavaScript/TypeScript (`kernel/clm_js_core/src/layer2/sync/`, exported at `clm-kernel/sync`), Python (`kernel/clm_py_core/clm/layer2/sync/`), and Rust (`kernel/clm_rust_core/src/layer2/sync/`), verified against shared golden fixtures (`tests/fixtures/sync-contract-v1/`), Petri P-invariant checks (`tools/guards/check_sync_net_invariants.py`), and 14 cross-runtime parity invariants (`tools/guards/check_kx_cross_runtime.py`) while preserving 100% of existing `0.0.10` public APIs and export subpaths. Downstream npm consumers remain exact-pinned to published `0.0.10` until live three-registry publication of `0.0.11` is approved.
+
+---
+
+## 🚀 Key Highlights & Performance
+
+- **Additive Tri-Runtime `SyncContract v1` & Petri Sync Net Parity (`EPIC-KX` / `KX-01`..`KX-06`)**: Implemented the additive 4-module Layer 2 sync contract (`types`, `codec`, `petri`, `service`) across TypeScript (`kernel/clm_js_core/src/layer2/sync/`, exported at `./sync`), Python (`kernel/clm_py_core/clm/layer2/sync/`), and Rust (`kernel/clm_rust_core/src/layer2/sync/`) with zero host globals (`check_kx_host_coupling.py`), injected transport/storage ports, `SyncPetriNet` / `SyncTransferNet` P-invariant token conservation ($y^\top C = 0$, verified by `tools/guards/check_sync_net_invariants.py`), shared golden wire fixtures (`tests/fixtures/sync-contract-v1/`), and 14/14 tri-runtime behavioral parity invariants (`tools/guards/check_kx_cross_runtime.py`), while preserving all 15 existing `clm-kernel@0.0.10` export subpaths and legacy sync APIs (`legacy-sync-api.compat.test.ts`, `test_sync_legacy_api.py`).
+- **Kernel Fast Paths, Baldwin Modularity & Gate 30 Governance (`INV-521`..`INV-526`)**: Zero-allocation buffer slicing in Layer 0 BLAKE3 and canonical codecs accelerated TypeScript hashing **7.78×** (`39.32 ms` → `5.05 ms`), bounded Poset reachability and Dedekind–MacNeille cut completion via 64-bit sparse/dense bitset tables (`5.80 ms` TS / `29.95 ms` Py), and backend-owned handle indexing collapsed composite handle resolution to **`0.76 ms`** without dual-map synchronization. Gate 30 (`check_kernel_contract.py`) ratchets all 30 boundary gates across 1,818 modules, enforcing 15+1 public export subpaths, 8 isolated facades, zero internal facade leaks, and six-operator Baldwin modularity algebra ($\div, =, +, -, ^{-1}, \to$) while preserving exact downstream consumer pins at `clm-kernel@0.0.10`.
+- **Declared Polyglot Vector Agreement & `image/jpx` `TypeInterpreter` Parity**: The enumerated 109 vectors (including `image/jpx` JPEG 2000 Part 2 magic-byte signature `0000000c6a5020200d0a870a` and `.jpx`/`.jpf`/`.jp2` extension judgment across `TypeInterpreter` and Layer 2 `detect_mime`/`detectMime`) and 33 Type Lattice features ($U_0$–$U_5$) pass across Python, Rust, and TypeScript. This evidence is scoped to those vectors/features and does not establish full API or MCard sync parity.
+- **Full-Stack `MCard`/`PCard` Duality & All-`MCard` Petri Net Engine (`INV-507`..`INV-514`)**: Every Petri Net Token (`TokenMCard` $\cong$ `PrimitivePCard` $\mathbf{1} \to X$ or `NetMCard`), Place (`PlaceMCard` $\cong$ `BooleanPCard` $X \to \mathbf{2}$), and Transition (`TransitionMCard` $\cong$ `DynamicPCard` $A \to B$ + `CordisCoeffects`) is an immutable Layer 0 `MCard` verified under coordinate $a$ of `g_time` (**BLAKE3 official default**). Places form a **Bounded Place Type Lattice** $\mathcal{L}_N = (P, \sqsubseteq, \sqcup, \sqcap, \bot, \tau_{\text{mid}}, \tau_{\text{exception}}, \top)$ with Tarjan SCC condensation, **Dedekind–MacNeille normal cut completion** (`dm_cuts` for strict least upper bound $\sqcup$ and greatest lower bound $\sqcap$ guarantees on arbitrary nets), MISU Meet preconditions, and Quarantine Trap routing; markings reside in `MCardTokenNamespace` (`mcard://ns/<net_id>/...`), and all services across Layers 2–5 are wrapped in composable 4-Place `PetriProcessPCard`s speaking the 9-operation authenticated Namespace Protocol (`version`, `put`, `get`, `stat`, `resolve`, `bind`, `list`, `history`, `watch`).
+- **Cross-Runtime Fractal Parity, Distributed Namespace & Release Readiness (`INV-515`..`INV-520`)**: Algorithm agility (`blake3`, `sha256`) and transitive supertype lattice closure; `PetriProcessPCard` execution with atomic `FiringReceiptMCard` sealing; Layer 2 host filesystem mounts, namespace unions, and chunked streaming in Rust and TypeScript; full fractal Petri net parity across Layers 3–5 (`Layer3CommPetriNet`, `Layer4TrellisNavigationNet`, `Layer5EpistemicLearningNet`) across all three runtimes; multi-node Satori IPC mesh with distributed P-invariant token conservation ($M \cdot y = M_0 \cdot y$); and clean-room polyglot consumer verification for release v0.0.8.
+- **Append-Only G-Set Retirement (`INV-CAS-04`/`INV-CAS-21`)**: `MCardCollection.removeHandle` and `MCardHostMountAdapter.rm` now retire handles by appending a `TOMBSTONE` transition with author attribution — card bytes and `handle_history` are preserved across Memory, Node SQLite, SQL.js, and CRDT-synced backends; retired handles vanish from active projections but stay resolvable by hash and lineage. Storage-size reduction remains the separate anchored-pruning path (`INV-513`), which archives unreachable records before reclaiming them — never a bare `DELETE`.
+- **Test-Plane Typecheck Gate**: new `tsconfig.tests.json` + `npm run typecheck:tests` close the hole where `tsconfig.json` excluded `tests/`; the full kernel test estate now compiles cleanly (306 diagnostics → 0), including a typed `llm/fallback-triggered` Cordis event and corrected fixture signatures across ~25 suites.
+- **Microsecond Systems Substrate**: Rust native CPN transitions execute in $\le 25\mu\text{s}$, zero-copy rollback in $<0.1\text{ms}$, and WAL database throughput exceeds $>900\text{k}$ QPS.
+- **Transactional Savepoint Decoupling**: Selective Tri-DB savepoint rollback (`content_memory`, `agent_identities`) with non-blocking, append-only `execution_log` emission and exponential backoff retry loops on SQLite lock contention.
+- **Architectural Certification & Module Ceiling Ratchet**: 100% green across all 30 Layer Boundary Gates (including Gate 25 Sovereign Shell Quarantine `INV-488`, Gate 26 Tri-Runtime Sovereignty & SSOT `INV-494`, Gate 27 500-Line Module Ceiling Ratchet `INV-500` across 1,818 modules, Gate 28 Automated Makefile Efficiency & DAG Deduplication Guard `INV-506`, Gate 29 Full-Stack `MCard`/`PCard` & Petri Conformance Ratchet `INV-512`..`INV-514`, Gate 30 Kernel Contract, Private Ownership & Causal Vector Guard `INV-526`, and VFS Module DAG Acyclicity & Stratification Guard `INV-294-02`), all 27 Layer-by-Stage verification suites (100% pass across $L_0$–$L_5$, 382 tests), complete Type Lattice tri-runtime consensus (`make test-equivalence`), Layer 1 CPN VM Stage 1/Stage 2 test suites (9/9 suites pass), and 25 foundational architectural invariants (`INV-01` through `INV-25`).
+- **Zero-Fork Evaluator & Governance Gate Routing**: Direct in-process evaluation across all governance pre-condition gates (`file_exists`, `hash_matches`, `valid_yaml`, `valid_clm`, `type_conforms`) in `compose.rs`, severing legacy shell bridge fallbacks and fully complying with Gate 25 shell quarantine (`INV-488`).
+- **Comprehensive Polyglot Sprint Battery**: 100% green across all sprint verification targets (Sprints 145–156, 161, 165–211, 222–226, 250–255, 309–312, 313–316, 317–320, 344–348, 392–396, 407–421, 438–453, 483–488, 489–494, 495–500, 501–506, 507–514, 515–520, and 521–526), certifying tri-runtime parity, downstream packaging integrity (`make test-sprints-packaging`), hermetic build conformance (`make test-sprints-build-hermeticity`), universal concurrent expressibility, and Makefile DAG efficiency across Windows, macOS, and Linux.
+- **High-Velocity Parallel Fleet & Deduplicated Make DAG**: 1,677+ tests executed in parallel in **14.79s** via `make test-parallel-fast` ($\le 30.0\text{s}$ target budget), full `make test` regression battery accelerated **2.76x** (**219.0s → 79.43s**) with `CLM SYSTEM VERIFICATION SCORECARD [RUST]` telemetry across macOS, Linux, and Windows (`INV-501`), Tri-Runtime CAS & N-Version Consensus (`make test-sprints-tri-runtime`) accelerated **8.97x** (**78.93s → 8.80s**), and 16 sprint batch cards evaluated in **253ms** via `make test-sprints-batch`.
+
+---
+
+## 🛠️ Installation & Setup
+
+Before running the `clm` CLI or switching runtimes, install and activate the environment. Python execution throughout the repository is hermetically managed via **[`uv`](https://docs.astral.sh/uv/)**.
+
+### 1. Quick Install (From Source)
+
+Clone the repository, provision dependencies across all runtimes, and activate your shell:
+
+```bash
+# Clone repository
+git clone https://github.com/xlp0/CLM.git
+cd CLM
+
+# 1. Provision all multi-runtime dependencies, compile Rust core, & init databases
+make install    # or: make setup (runs uv sync, npm install, cargo build)
+
+# 2. Activate Python virtual environment (adds 'clm' to your PATH)
+source .venv/bin/activate       # On macOS/Linux
+# source .venv/Scripts/activate # On Windows (PowerShell: .venv\Scripts\Activate.ps1)
+
+# Or run directly via uv without activation:
+uv run clm version
+
+# 3. Verify installation
+clm version                     # or: clm --version
+```
+
+> **Zero-Activation Shortcut**: You can also use the repository's native root launcher directly without activating `.venv`:
+>
+> ```bash
+> ./clmEval evaluate assets/clm/manifests/example.yaml --json
+> ```
+
+### 2. Prerequisites & Toolchains
+
+- **Python**: 3.10+ managed via **`uv`** (all `make` targets invoke Python via `uv run python` and `uv run pytest`)
+- **Rust**: 1.80+ (`cargo` with 2024 edition support)
+- **Node.js**: 20+ (`npm` or `pnpm`)
+- **Build Tools**: GNU Make 3.81+, SQLite 3.38+
+
+### 3. Granular Build Targets
+
+- **Recompile Rust Core**: `make build-rust` (`cargo build --release --features python` — automatically builds and links `clm_rust_core.so` on Linux/macOS or `clm_rust_core.pyd` on Windows, and syncs `kernel/scripts/clmEval-rs`; `make test` also auto-verifies and syncs these artifacts during `test-preconditions`)
+- **Initialize / Reset Runtime Tapes**: `make init-db` (initializes the Sovereign Triad SQLite databases, syncs Rust release links, and auto-resets `db/execution_log.db` if it exceeds the 44 MB `INV-417` pre-flight budget)
+- **Clean Workspace**: `make clean` (`ARG_MAX`-safe cleanup of execution logs, scratch directories, IPC artifacts, and SQLite databases)
+- **Compile TypeScript Bundle**: `npm --prefix kernel/clm_js_core run build`
+- **Rebuild All Polyglot Targets**: `make build-all`
+
+### 4. Install Pre-built Packages
+
+Consume CLM directly via language-specific package managers:
+
+```bash
+pip install clm-kernel          # Python (PyPI)
+npm install clm-kernel          # Node.js / TypeScript (npm)
+cargo install clm-kernel        # Rust (crates.io)
+```
+
+> **Cross-Platform Verification (Windows, Linux, macOS)**: Windows, Linux, and Mac have all proven to pass 100% of tests for CLM's `make test`, `make test-parallel-fast`, and all 30 boundary gates and 27 layer-by-stage verification suites. On Windows, execution is fully supported natively (PowerShell / Git Bash) and via WSL without POSIX-specific failures. Python toolchains are unified through `uv run python` and `uv run pytest`, eliminating path space issues. Native PyO3 builds automatically produce `kernel/clm_py_core/clm_rust_core.pyd` and `kernel/scripts/clmEval-rs.exe`. See [`docs/guides/windows-setup-and-practices.md`](docs/guides/windows-setup-and-practices.md) for automated bootstrap scripts, path normalization, and MSVC settings.
+>
+> Windows-specific hardening (see [`CHANGELOG.md`](CHANGELOG.md), `0.0.11`):
+> - Test subprocesses decode output as UTF-8, so the default cp1252 console codec no longer crashes them.
+> - Latency benchmarks warm up first and use `TCP_NODELAY`.
+> - `msvcrt` lock contention and read-only SQLite `-wal`/`-shm` files are handled.
+> - The `clm_js_core` build cleans `dist/` with `fs.rmSync({ force: true })`.
+> - The `make test` scorecard now reports measured per-layer durations.
+>
+> Avoid launching two `make test` runs at once: they share `db/` and `kernel/clm_js_core/dist/`.
+
+---
+
+## 🌐 The Three Language Runtimes
+
+Under the **Kenotic Principle (`INV-01`)**, CLM strictly separates abstract specifications ($A$) from concrete host execution ($C$). It delivers Python, Rust, and TypeScript runtime implementations with feature-specific conformance contracts; language APIs remain idiomatic, and parity claims are limited to tested capabilities:
+
+```mermaid
+flowchart TD
+    SPEC["Universal Specification (A)<br/>YAML Schemas • CEL Dicts • CPN Graphs"]
+  
+    SPEC --> PY["<b>Python Runtime</b><br/>kernel/clm_py_core/ (clm-kernel)<br/>• Dynamic Duck-Typing & Pydantic v2<br/>• AI Agent Orchestration & REPL<br/>• PyO3 Native Acceleration Bridge"]
+  
+    SPEC --> RS["<b>Rust Microkernel</b><br/>kernel/clm_rust_core/ (clm-kernel)<br/>• Zero-Cost Systems Substrate<br/>• Sub-25µs Petri Net Transition<br/>• Bare-Metal Daemon & CLI Fastpath"]
+
+    SPEC --> TS["<b>TypeScript / Node.js Runtime</b><br/>kernel/clm_js_core/ (clm-kernel)<br/>• Isomorphic V8 Engine<br/>• Cordis Reactive Plugin Micro-Harness<br/>• WebStudio & In-Browser CAS Storage"]
+
+    PY <===>|"Gate 23 (TypeInterpreter) & Gate 24 (TypedValue)"| RS
+    RS <===>|"Byte-Identical BLAKE3 & Marking Parity"| TS
+    TS <===>|"Universal Subcommand Grammar (USG)"| PY
+```
+
+### Runtime Capability & Performance Matrix
+
+| Runtime              | Implementation                                         | Primary Role                                               | Latency Profile                                              | Primary Target                 |
+| :------------------- | :----------------------------------------------------- | :--------------------------------------------------------- | :----------------------------------------------------------- | :----------------------------- |
+| **Python**     | `kernel/clm_py_core/` (`clm-kernel`)               | Reference model, AI agents, dynamic prototyping            | ~5ms (pure) / <2ms (PyO3)                                    | `clm` / `python -m clm`    |
+| **Rust**       | `kernel/clm_rust_core/` (`clm-kernel`)             | Systems microkernel, zero-copy CAS, high-throughput daemon | $\le 25\mu\text{s}$ transition, $<0.1\text{ms}$ rollback | `clm_rust_core` / native FFI |
+| **TypeScript** | `kernel/clm_js_core/` (`clm-kernel`)               | Web & edge runtime, Cordis plugins, in-browser CAS         | ~1ms V8 execution                                            | `npx clmEval` / Browser      |
+
+### 🔀 Transparent Runtime Selection (`CLM_RUNNER`)
+
+Once your environment is activated, CLM routes commands through a Universal Subcommand Grammar facade. Switch engines dynamically on the fly using the `CLM_RUNNER` environment variable:
+
+```bash
+# 1. Auto-dispatch (resolves compiled Rust binary if available, falls back to Python)
+clm evaluate assets/clm/manifests/example.yaml --json
+
+# 2. Force native Rust microkernel (<2ms dispatch, sub-25µs transitions)
+CLM_RUNNER=rust clm evaluate assets/clm/manifests/example.yaml --json
+
+# 3. Force Python reference engine
+CLM_RUNNER=python clm evaluate assets/clm/manifests/example.yaml --json
+
+# 4. Force Node.js / TypeScript engine
+CLM_RUNNER=node clm evaluate assets/clm/manifests/example.yaml --json
+```
+
+For the comprehensive comparative analysis of algorithms and benchmarks, see [`docs/architecture/tri-language-runtime-parity-and-performance.md`](docs/architecture/tri-language-runtime-parity-and-performance.md).
+
+---
+
+## ⚡ Common Workflows & Developer Tools
+
+### 1. Headless Streaming Gateway Server
+
+Launch the universal WebSocket JSON-RPC 2.0 streaming gateway on port 4000:
+
+```bash
+clm gateway
+```
+
+### 2. Interactive Developer TUI Menu
+
+Launch the interactive terminal dashboard for running tests, diagnostics, and benchmarks:
+
+```bash
+make menu
+# or: python3 tools/make/interactive_menu.py
+```
+
+### 3. Programmatic SDK Usage
+
+#### Python
+
+```python
+from clm.layer0.typed_value import TypedValue
+
+# Create and canonically hash a universe-stratified value
+tv = TypedValue.from_data({"status": "ready", "tokens": 42}, universe="U0")
+print(f"MIME: {tv.mime} | Hash: {tv.content_hash}")
+```
+
+#### TypeScript
+
+```typescript
+import { TypedValue } from "@clm/core";
+
+const tv = TypedValue.fromData({ status: "ready", tokens: 42 }, "application/json", "U0");
+console.log(`MIME: ${tv.mime} | Hash: ${tv.contentHash}`);
+```
+
+#### Rust
+
+```rust
+use clm_rust_core::typed_value::TypedValue;
+use serde_json::json;
+
+let tv = TypedValue::from_data(json!({"status": "ready", "tokens": 42}), "application/json".into(), "U0".into());
+println!("Hash: {}", tv.content_hash);
+```
+
+### 4. Polyglot Release Automation & Consensus Verification
+
+CLM enforces strict 100% SemVer consensus across all three runtime package manifests (`pyproject.toml`, `kernel/clm_rust_core/Cargo.toml`, `kernel/clm_js_core/package.json`) and consumer test harnesses via `tools/release/bump_version.py`:
+
+```bash
+# 1. Verify 100% SemVer consensus across all manifests, lockfiles, and consumer tests
+make release-check
+
+# 2. Synchronize and bump version deterministically across all runtimes
+make bump VERSION=0.0.8
+
+# 3. Query public package registries (PyPI, npm, crates.io) for live publication status
+make verify-published VERSION=0.0.7
+
+# 4. Atomically sync all in-tree manifests with published registry artifacts
+make sync-published VERSION=0.0.7
+```
+
+For extended guides, see [`docs/guides/polyglot-quick-start.md`](docs/guides/polyglot-quick-start.md) and [`docs/guides/web-ui-quick-start.md`](docs/guides/web-ui-quick-start.md).
+
+---
+
+## 🏛️ Core Architecture Overview
+
+CLM organizes computation into six stratified, hermetically isolated layers ($L_0$ to $L_5$), articulating **Storage Resource**, **Data Transport Activities**, **Learning State Changes**, and **Security Perimeter** through **Cordis Calculus**, **Type Lattice Theory**, and **Petri Net Algebra**:
+
+| Layer | Stratum Name | Primary Function | Canonical Spec |
+| :--- | :--- | :--- | :--- |
+| **$L_0$** | **Substrate Primitives** | `MCard`/`PCard`/`VCard` Triad, RFC 8785 canonical JSON, `TypedValue` ($U_0$), `g_time` ($a$, BLAKE3 default), `TypeLattice`, Cordis `Context` & `Fiber` ($\mathcal{L}_{\text{Fiber}}$) | [`docs/spec/20-architecture/`](docs/spec/20-architecture/) |
+| **$L_1$** | **Type Lattice & CPN VM** | All-`MCard` Triad (`TokenMCard`, `PlaceMCard`, `TransitionMCard`), Bounded Place Type Lattice $\mathcal{L}_N = (\bot, \tau_{\text{mid}}, \tau_{\text{exception}}, \top)$ with Tarjan SCC & Dedekind–MacNeille cut completion, `MCardTokenNamespace`, $O(1)$ Noetherian conservation ($x^\top D = 0$) | [`docs/spec/40-behavior/`](docs/spec/40-behavior/) |
+| **$L_2$** | **Storage & Fibers** | Tri-Database isolation (`agent`, `content`, `log`), `DirectoryManifest`, `ChunkManifest`, `StoragePetriNet`, 4-Place `PetriProcessPCard` & 9-op Namespace Protocol, Host Mount (`MCardHostMountAdapter`), Anchored Pruning (`INV-CAS-21`) | [`docs/architecture/kernel-pillars.md`](docs/architecture/kernel-pillars.md) |
+| **$L_3$** | **Dialectic Mesh** | `CommPlaceMCard` & `CommTransitionPCard` ($\pi$-calculus mobility), Satori Protocol, Austin-Searle speech acts ($U_3$), Reticulum P2P mesh | [`docs/architecture/satori-protocol-and-clm-layers-networking-interfacing.md`](docs/architecture/satori-protocol-and-clm-layers-networking-interfacing.md) |
+| **$L_4$** | **Presentation Membrane** | `ViewPlaceMCard` & `NavigationTransitionPCard` (Bounded View Lattice), Pluggable Membrane SPI, `TypedEnvelope` ($U_4$), WebStudio (`mcard-studio`), CLI TUI | [`docs/spec/30-interfaces/presentation-membrane-spi.md`](docs/spec/30-interfaces/presentation-membrane-spi.md) |
+| **$L_5$** | **Epistemic Learning** | `EpistemicPlaceMCard` & `LearningTransitionPCard` (cyclic T-invariants $D_{\text{learn}} \cdot y = 0$), Cordis HMR instinct assimilation, Siphon privilege perimeter & Quarantine Traps | [`docs/architecture/agentic-conversational-programming.md`](docs/architecture/agentic-conversational-programming.md) |
+
+For a single, diagram-heavy tour of the system **as built** — card triad, six-layer stack, L1 Petri engine, L2 Namespace Protocol, L3–L5 fractal nets, defense-in-depth, tri-runtime parity matrix, runtime layer map, and open gaps GAP-18…23 — start with [`docs/architecture/overall-architecture.md`](docs/architecture/overall-architecture.md).
+
+For deep architectural principles and invariants, see [`docs/architecture/six_layers_architecture.md`](docs/architecture/six_layers_architecture.md), [`docs/architecture/architectural-invariants.md`](docs/architecture/architectural-invariants.md), and [`docs/architecture/zero-trust-made-concrete.md`](docs/architecture/zero-trust-made-concrete.md) (Zero Trust Architecture & PKC Quadriad Audit).
+
+---
+
+## 🧪 Testing & Quality Assurance
+
+CLM features a comprehensive stratified test suite across all six layers. The primary developer targets are:
+
+```bash
+# 1. High-speed parallel test fleet (1,677+ tests in ~15s, budget <= 30.0s)
+make test-parallel-fast
+
+# 2. Complete regression test suite (renders CLM SYSTEM VERIFICATION SCORECARD [RUST])
+# Fully supported and verified native on Windows (PowerShell/Git Bash), macOS, and Linux
+make test
+
+# 3. Verify Layer 1 CPN VM execution stages (Stage 1 & Stage 2)
+make test-layer1-stage1
+make test-layer1-stage2
+
+# 4. Verify all 29 Layer Boundary & Hygiene Guards (zero-regression gate, incl. Gate 29)
+make check-boundaries
+
+# 5. Verify all 25 foundational architectural invariants (INV-01 to INV-25)
+make check-invariants
+
+# 6. Rust 2024 compiler and Clippy zero-warning check
+make clippy-check
+
+# 7. Tri-runtime consensus test battery across Python, Rust, and TypeScript
+make test-polyglot-all
+```
+
+> **Windows Native Execution & Cross-Platform Support**: `make test` now works cleanly and natively on Windows (PowerShell, Git Bash, MSYS2) as well as Linux (Ubuntu/Debian, Fedora, RHEL, aarch64/x86_64) and macOS. All 27 layer-by-stage verification suites ($L_0$–$L_5$, 382 tests), all 29 boundary gates, Rust PyO3 native build acceleration (`clm_rust_core.pyd`), dot-slash executable manifest resolution, and tri-runtime consensus batteries pass with 100% green compliance, rendering the `CLM SYSTEM VERIFICATION SCORECARD [RUST]`. Downstream sibling builds (`build-studio-once`), path normalization, and tri-runtime test runners execute without POSIX path, symlink, or missing polyfill errors.
+
+#### 🪟 Running `make test` on Windows
+
+On Windows, `make test` executes directly in PowerShell, Command Prompt, or Git Bash using standard GNU Make:
+
+```powershell
+# Run the complete regression test suite (renders CLM SYSTEM VERIFICATION SCORECARD [RUST])
+make test
+
+# Or run the high-velocity parallel test fleet:
+make test-parallel-fast
+```
+
+The test harness automatically provisions MSVC / PyO3 native build artifacts (`clm_rust_core.pyd`), synchronizes `kernel/scripts/clmEval-rs.exe`, handles Windows path separators, avoids SQLite file lock contention via exponential backoff, and ensures zero POSIX shell quarantine violations (`INV-488`).
+
+> **Historical Sprint Tests**: For the complete catalog of historical sprint verification targets (Sprints 144–244) and the full 35-row Makefile command reference, see [`docs/guides/sprint-test-target-reference.md`](docs/guides/sprint-test-target-reference.md).
+
+---
+
+## 📚 Documentation & Project Evolution
+
+| Knowledge Domain                  | Authoritative Documentation                                                                     | Description                                                                                                                                                                                                                                                                                                                                |
+| :-------------------------------- | :---------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Formal Specifications**   | [`docs/spec/`](docs/spec/)                                                                     | Complete 8-part normative specification suite ($L_0$–$L_5$)                                                                                                                                                                                                                                                                           |
+| **Architecture Canons**     | [`docs/architecture/`](docs/architecture/)                                                     | Six-layer model, Kenotic theory, Zero Trust Quadriad, and tri-runtime execution                                                                                                                                                                                                                                                            |
+| **Overall Architecture**    | [`docs/architecture/overall-architecture.md`](docs/architecture/overall-architecture.md)       | As-built synthesis (Sprints 501, 507–514) with Mermaid diagrams and tables: L0–L5 Petri realization, tri-runtime parity matrix, runtime layer map (855 modules), Gate 29, and open gaps GAP-18…23                                                                                                                                       |
+| **Foundational Theory**     | [`docs/theory/why-clm-exists.md`](docs/theory/why-clm-exists.md)                               | Universal MCard ontology, Kenotic Model, and CHL isomorphism                                                                                                                                                                                                                                                                               |
+| **Historical Lineage**      | [`docs/architecture/lineage-and-inspiration.md`](docs/architecture/lineage-and-inspiration.md) | 50-year chronology: 1969 Logic Frame to Cordis & Koishi.js                                                                                                                                                                                                                                                                                 |
+| **Developer Guides**        | [`docs/guides/`](docs/guides/)                                                                 | 60-second onboarding, Web UI, Headless client, Windows setup                                                                                                                                                                                                                                                                               |
+| **Active Work**          | [`docs/sprints/_active/`](docs/sprints/_active/README.md)                                               | Idle / None in flight (Sprints 521–526 Completed & Graduated: CLM Kernel Fast Paths & Causal Correctness, Gate 30, Baldwin Modularity Algebra; alongside Sprints 515–520 Cross-Runtime Fractal Parity Suite, Sprints 501 & 507–514 Full-Stack `MCard`/`PCard` Duality Suite, Sprints 501–506 Makefile DAG Deduplication Suite, Sprints 495–500 500-Line Module Ceiling Suite, and Sprints 489–494 Cross-Runtime Contracts Suite). |
+| **Thematic Sprint Archive** | [`docs/sprints/`](docs/sprints/)                                                               | Catalog of 526+ completed sprints and master log [`sprint_log.md`](docs/sprints/_index/sprint_log.md) — latest: Tri-Runtime Fast Paths, Baldwin Modularity & Gate 30 Causal Contract Suite (521–526, [`02_petri-net/`](docs/sprints/02_petri-net/)), Cross-Runtime Fractal Parity, Distributed Namespace & Release Readiness Suite (515–520, [`02_petri-net/`](docs/sprints/02_petri-net/)), Full-Stack `MCard`/`PCard` Duality & Universal Collection Namespace Suite (501, 507–514, [`02_petri-net/`](docs/sprints/02_petri-net/)), Makefile DAG Deduplication & Test Batching Suite (501–506, [`07_test-infrastructure/`](docs/sprints/07_test-infrastructure/)), 500-Line Module Compression & Cohesive Decomposition Suite (495–500, [`06_kernel-reorganization/`](docs/sprints/06_kernel-reorganization/)), Runtime Interfaces & Convergence Suite (489–494, [`05_runtime-interfaces/`](docs/sprints/05_runtime-interfaces/)) |
+| **Weekly Changelogs**       | [`docs/changelog/`](docs/changelog/)                                                           | Chronological weekly logs (Current: [`2026-W43.md`](docs/changelog/2026-W43.md) · Monograph: [`2026-10-20-performance-and-organizational-improvements.md`](docs/changelog/2026-10-20-performance-and-organizational-improvements.md)) |
+
+---
+
+## 📄 License & Community
+
+CLM is open-source software licensed under the [MIT License](LICENSE).
+
+- **Issues & Discussions**: [GitHub Issues](https://github.com/xlp0/CLM/issues)
+- **Active Work Tracking**: [`docs/sprints/_active/README.md`](docs/sprints/_active/README.md) (All Sprints 521–526 Completed & Graduated to `02_petri-net/`: CLM Kernel Fast Paths, Baldwin Modularity & Gate 30 Governance; Sprints 515–520 Completed: Cross-Runtime Fractal Parity, Distributed Namespace & Release Readiness Suite; Sprints 501 & 507–514 Completed: Full-Stack `MCard`/`PCard` Duality, Bounded Place Type Lattice, Cordis `PetriProcessPCard` Service Wrappers, Universal Filesystem Namespace & `docs/` Canon Realignment) · [`docs/sprints/13_documentation-reconciliation/README.md`](docs/sprints/13_documentation-reconciliation/README.md) (completed documentation reconciliation, DOC-01 … DOC-07)