Metadata-Version: 2.4
Name: mcard
Version: 0.1.68
Summary: MCard: Local-first Content Addressable Storage with Content Type Detection
Author-email: Ben Koo <koo0905@gmail.com>
Project-URL: Homepage, https://github.com/xlp0/MCard_TDD
Project-URL: Source, https://github.com/xlp0/MCard_TDD
Project-URL: Tracker, https://github.com/xlp0/MCard_TDD/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dateutil>=2.9.0.post0
Requires-Dist: SQLAlchemy>=1.4.47
Requires-Dist: aiosqlite>=0.17.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: chardet>=5.1.0
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: wasmtime>=39.0.0
Requires-Dist: websockets>=12.0
Requires-Dist: result>=0.17.0
Requires-Dist: cryptography>=44.0.3
Requires-Dist: zeroconf>=0.148.0
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: scipy>=1.15.3
Requires-Dist: base58>=2.1.1
Provides-Extra: xml
Requires-Dist: lxml>=4.9.0; extra == "xml"
Provides-Extra: duckdb
Requires-Dist: duckdb>=1.0.0; extra == "duckdb"
Provides-Extra: qnlp
Requires-Dist: lambeq>=0.4.2; extra == "qnlp"
Requires-Dist: torch>=2.0.0; extra == "qnlp"
Provides-Extra: observability
Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation>=0.41b0; extra == "observability"
Dynamic: license-file

<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License" /></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="ruff" /></a>
  <a href="https://github.com/xlp0/MCard_TDD/actions/workflows/ci.yml"><img src="https://github.com/xlp0/MCard_TDD/actions/workflows/ci.yml/badge.svg" alt="Build Status" /></a>
</p>

# MCard and PKC: An Agentic OS for The PKM Paradigm Shift

MCard is the foundational storage layer of the **Personal Knowledge Container (PKC)** — an Agentic Operating System designed to facilitate a paradigm shift in Knowledge Management. Moving beyond centralized, passive data stores, PKC empowers local communities to **operationally own their data asset infrastructures**.

Through a local-first, content-addressable storage platform with cryptographic integrity, it provides a verifiable data backbone. Governed by a polynomial runtime (PTR) and guided by universally shared gamified scripts like the **ABC curriculum**, it removes learning barriers so anyone can utilize robust, polyglot execution without sacrificing developer ergonomics or observability.

---

## Highlights

- 🔐 **Hash-verifiable storage**: Unified network of relationships via SHA-256 hashing across content, handles, and history.
- 🆔 **Kenotic Identity Primitives**: Decentralized Identifiers (DIDs) and Soul Bound Tokens (SBTs) bound to a Sovereign Tri-Database, scaling seamlessly from local SQLite files into Browser PWA IndexedDB partitions.
- ♾️ **Universal Substrate**: Emulates the Turing Machine "Infinitely Long Tape" via relational queries for computable DSLs.
- 🤖 **Continuous Autonomous Optimization**: Integrates local OpenClaw agents operating on configurable heartbeat intervals to continuously refine logic, types, and architecture autonomously.
- ♻️ **Deterministic execution**: PTR mediates **8 polyglot runtimes** (Python, JavaScript, Rust, C, WASM, Lean, R, Julia).
- 🧩 **Meta-Circular Type System**: Purely native type-checking via a Minimum Preloaded Type Set (Propositions-as-Types), integrating **Dependent Type Theory** and **Type Universes** to safely parse dynamic constraints and remove reliance on language-specific type primitives.
- 🌳 **Content Addressable Function-Number Duality Namespace**: The hash of the Root Type CLM (`type.yaml`) serves as the universal namespace anchor — the ground truth for uniqueness of content. All primitive types are recursively derived dependencies of this root, ensuring functional and content consistency across all Functions (causal relations) and Numbers (static content images).
- 🔧 **CLM as Dependency Orchestrator**: CLM operates like `Make` — it primarily manages dependencies and runs on top of any executable kernel, including kernels explicitly implemented to run CLM itself (meta-circular evaluation).
- 🐚 **Meta-Circular Shell Evaluator**: Developed a pure shell-based evaluator (`clmEval`) that leverages `yq` and `shasum` to execute the CLM prep → exec → post pipeline entirely via CLI, enabling the script to evaluate its own CLM specification in a closed meta-circular loop.
- 📊 **Enterprise ready**: Structured logging, CI/CD pipeline, security auditing, 99%+ automated test coverage. Continuous static analysis using `vulture` for Python and `ts-prune` for TypeScript dead code elimination.
- 🧠 **AI-native extensions**: GraphRAG engine, optional LLM runtime, and optimized multimodal vision (`moondream`).
- ⚛️ **Quantum NLP**: Optional `lambeq` + PyTorch integration for pregroup grammar and quantum circuit compilation.
- 📐 **Visual Architecture**: Interactive Mermaid diagrams bridging conceptual OS theory directly to Sovereign Tri-Database CI/CD implementation.
- 🏗️ **Implementation Clarity**: Systematic 7-document implementation suite (`docs/implementation/00_INDEX.md`) follows a logical dependency chain — from Data-Function Duality (§01 foundational theory) through architecture-to-code mapping (§02), PocketFlow integration (§03), component specs (§04), testing strategy (§05), to the definitive implementation roadmap (§06). All content organized with Four-Database Topology alignment and Token Arithmetics governance telemetry.
- 🧰 **Developer friendly**: Rich Python API, TypeScript SDK, BMAD-driven TDD workflow, numerous examples.
- 📐 **Algorithm Benchmarks**: Sine comparison (Taylor vs Chebyshev) across Python, C, and Rust.
- ⚡ **High Performance**: Optimized test suite (~37s) with runtime caching, Python AST `lru_cache` memory bounds, and static Node.js runner scripts resolving without dynamic I/O overhead.
- ⚙️ **Meta-Circular Evaluator**: The core PTR engine is distilled into a strict `eval/apply` functional pipeline, stripping away bloated Category Theory abstractions to ensure the simplest possible mathematical verification loop.
- 🧽 **Tabula Rasa Distillation**: The core engine completely eschews redundant Python Object-Oriented wrappers (like hardcoded Flow Builders, Polyglot Bridgelets, and Lens RPC protocols) in favor of defining architectures exclusively via mathematical PetriNet topologies evaluated directly by the isolated sandbox.
- 🛡️ **Robust Validation Stability**: Dynamic Model Fallbacks seamlessly locate available locally-hosted AI inference APIs (`Ollama`) resolving test disparities out of the box, bound by strictly defined mathematical payload types across Python constraints and TypeScript TS2322 invariant coercions.
- 🦆 **DuckDB Engine**: Optional columnar OLAP storage backend — same `StorageEngine` interface, ideal for analytical workloads and Parquet I/O.
- 📋 **Single Source of Truth Schema**: Both SQLite and DuckDB engines load schema exclusively from canonical SQL files (`mcard_schema.sql`, `mcard_vector_schema.sql`) — zero hardcoded CREATE TABLE statements.
- 🔄 **Bi-Directional Topological Sync**: Pure Handle Space parity mapping recursively natively across Rust and Python runtimes perfectly maintaining SSOT bounds.
- 🔄 **Shared MIME Registry**: A single [`mime_extensions.json`](mime_extensions.json) drives content-type detection across both Python and TypeScript — edit one file to update both runtimes, no recompilation needed.
- ⏱️ **Centralized Operational Constants**: All timing literals (PTR timeouts, LLM defaults, RAG embedding delays, signaling server intervals) unified in `config_constants.py` with full TypeScript parity — zero hard-coded timeouts remain in runtime code.
- 🔗 **Explicit VCard Wrapping**: Fully formalized VCard-PCard binding via `wrapped_pcard_hash` parameter injection. VCard instantiation now leverages a PCard-based Factory Pattern (`PCard.create_vcard()`), strictly coupling Subscriber (Pre) and Dispatcher (Post) witnesses to their origin PCards globally.

For the long-form narrative, gamified learning paths (the ABC curriculum), and chapter roadmap, see **[docs/theory/04_curriculum/Narrative_Roadmap.md](docs/theory/04_curriculum/Narrative_Roadmap.md)**. For the overarching OS metaphor and foundational principles of agentic infrastructure ownership, see **[docs/theory/02_architecture/PKC_Operating_System.md](docs/theory/02_architecture/PKC_Operating_System.md)** and **[docs/architecture/00_Architecture_Overview.md](docs/architecture/00_Architecture_Overview.md)**.

---

## Quick Start (Python)

```bash
git clone https://github.com/xlp0/MCard_TDD.git
cd MCard_TDD
make setup-dev              # creates .venv with uv, installs all deps + pre-commit
make project-check          # validates Python, mcard-js, and mcard-studio
uv run pytest -q -m "not slow"  # run the fast Python test suite
uv run python scripts/clm/run_clms.py chapters/chapter_01_arithmetic/addition.yaml
```

### Development Setup

This project uses **[uv](https://github.com/astral-sh/uv)** as the sole Python dependency manager. All dependencies are defined in `pyproject.toml` and locked in `uv.lock`.

```bash
# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create venv and install all dependencies (including dev)
make setup-dev
# Or manually:
uv venv --prompt MCard_TDD
uv sync --all-extras --dev

# Run commands via uv
uv run pytest           # run tests
uv run ruff check mcard/  # lint
uv run python script.py   # run any script
```

### Configuration

- Copy `example.env` to `.env` for local development.
- `example.env` is the canonical template; `.env.example` remains as a legacy-compatible copy.
- The studio app uses `mcard-studio/example.env` for its own local `.env` seed.
- Environment precedence is: CLI overrides → process environment → `.env` → `example.env` defaults.
- Shared config defaults are defined in `config/app_config.json` and consumed by Python, TypeScript, and studio runtime helpers.

Create and retrieve a card:

```python
from mcard import MCard, default_collection

card = MCard("Hello MCard")
hash_value = default_collection.add(card)
retrieved = default_collection.get(hash_value)
print(retrieved.get_content(as_text=True))
```

### Quick Start (JavaScript / WASM)

See **[mcard-js/README.md](mcard-js/README.md)** for build, testing, and npm publishing instructions for the TypeScript implementation.

- **mcard-studio**: The interactive PWA IDE — see [mcard-studio/README.md](mcard-studio/README.md) for setup and architecture.

### Quick Start (Quantum NLP)

MCard optionally integrates with **[lambeq](https://cqcl.github.io/lambeq/)** for quantum natural language processing using pregroup grammar:

```bash
# Install with Quantum NLP support (requires Python 3.10+)
uv pip install -e ".[qnlp]"

# Parse a sentence into a pregroup grammar diagram
uv run python scripts/lambeq_web.py "John gave Mary a flower"
```

**Example output** (pregroup types):

```
John: n    gave: n.r @ s @ n.l @ n.l    Mary: n    a flower: n
Result: s (grammatically valid sentence)
```

The pregroup diagrams can be compiled to quantum circuits for QNLP experiments.

---

## Polyglot Runtime Matrix

| Runtime    | Status | Notes                                                      |
| ---------- | ------ | ---------------------------------------------------------- |
| Python     | ✅     | Reference implementation, CLM runner                       |
| JavaScript | ✅     | Node + browser (WASM) + Full RAG Support + Pyodide         |
| Rust       | ✅     | High-performance adapter & WASM target                     |
| C          | ✅     | Low-level runtime integration                              |
| WASM       | ✅     | Edge and sandbox execution                                 |
| Lean       | ⚙️   | Formal verification pipeline (requires `lean-toolchain`) |
| R          | ✅     | Statistical computing runtime                              |
| Julia      | ✅     | High-performance scientific computing                      |

> **⚠️ Lean Configuration**: A `lean-toolchain` file in the project root is **critical**. Without it, `elan` will attempt to resolve/download toolchain metadata on *every invocation*, causing CLM execution to hang or become unbearably slow.

### Compiling Native Binaries

For detailed instructions on compiling the required C, Rust, and WASM binaries for the polyglot tests, please see the **[Compiling Native Binaries Guide](docs/guides/COMPILING_BINARIES.md)**.

---

## Project Structure (abridged)

```
MCard_TDD/
├── mcard/            # Python package (engines, models, PTR)
├── mcard-js/         # TypeScript SDK — 3 interchangeable storage engines, PTR, RAG
├── mcard-studio/     # [Submodule] Astro + React PWA — artifact IDE with VCard events
├── LandingPage/      # [Submodule] Static-first P2P Documentation & Landing Portal
├── chapters/         # CLM specifications (polyglot demos)
├── docs/             # Architecture, PRD, guides, reports
├── scripts/          # Automation & demo scripts
├── tests/            # 923+ automated tests (Python)
├── Makefile          # Unified dev commands (lint, test, clm-run, build)
├── mime_extensions.json  # Shared MIME-type registry (Python + TypeScript)
└── pyproject.toml    # uv-managed dependencies (uv.lock)
```

### Submodule Organization

This repository orchestrates two key frontend applications as submodules, each serving a distinct role in the MCard ecosystem:

#### 1. mcard-studio (`/mcard-studio`)

**The Interactive IDE for Eventual Consistency & Eventual Correctness.**
A **Progressive Web App (PWA)** built with **Astro** and **React**. It serves as the primary interface for creating, editing, and executing MCards and CLMs.

- **Tech Stack**: Astro, React, Zustand, Monaco Editor, Anime.js/GSAP, Mermaid.
- **Key Features**: Four-store persistence (`servermemory.db`, `browsermemory.db`, `execution_logs.db`, filesystem), dual-mode CLM execution (browser-first JS → server fallback), VCard event pipeline with result sealing, inline rename/upload/create, version history with time-travel, native AI assistant (Ollama), 30+ file type renderers.
- **Role**: The "Editor" & "Runtime" environment for developers and power users.
- **Test Results**: 372 tests passed (37 test files).

#### 2. LandingPage (`/LandingPage`)

**The Public Portal & Knowledge Container.**
A **static-first** modular web application designed for decentralized distribution. It focuses on P2P communication, documentation rendering, and interactive 3D visualizations.

- **Tech Stack**: Vanilla JS Modules, WebRTC (No signaling server), Three.js, KaTeX, Mermaid, ZITADEL (OIDC Authentication).
- **Key Features**: Serverless P2P mesh networking, zero-dependency architecture (runs locally without build steps), rich markdown/media rendering, and interactive authenticated pedagogical games (Monopoly, Chess, Go) with ZITADEL SSO integration.
- **Role**: The "Viewer" & "distributable container" for the Personal Knowledge Container (PKC) concept.

---

## Documentation

- **📖 Master Index:** [docs/index.md](docs/index.md) — AI-optimized documentation entry point (BMAD `document-project` output)
- **📋 Project Overview:** [docs/project-overview.md](docs/project-overview.md) — Executive summary, tech stack, multi-part structure
- **🌳 Source Tree Analysis:** [docs/source-tree-analysis.md](docs/source-tree-analysis.md) — Annotated directory structure
- Product requirements: [docs/specifications/01_product_requirements.md](docs/specifications/01_product_requirements.md)
- Architecture overview: [docs/architecture/README.md](docs/architecture/README.md) — Three Pillars (CLM, PTR, VCard) + Function-Number Duality
- Theory canon: [docs/theory/README.md](docs/theory/README.md) — Foundations, architecture, runtime, curriculum (14 articles)
- **Schema principles**: [schema/README.md](schema/README.md) — Empty Schema grounding, verification-first storage, and the core/extension split.
- **`mcard-js` schema reference**: [mcard-js/schema/README.md](mcard-js/schema/README.md) — Practical explanation of `mcard_schema.sql` and `mcard_vector_schema.sql`.
- **DOTS vocabulary**: [docs/WorkingNotes/Hub/Theory/Integration/DOTS Vocabulary as Efficient Representation for ABC Curriculum.md](docs/WorkingNotes/Hub/Theory/Integration/DOTS%20Vocabulary%20as%20Efficient%20Representation%20for%20ABC%20Curriculum.md)
- Narrative roadmap & chapters: [docs/theory/04_curriculum/Narrative_Roadmap.md](docs/theory/04_curriculum/Narrative_Roadmap.md)
- Logging system: [docs/guides/LOGGING_GUIDE.md](docs/guides/LOGGING_GUIDE.md)
- PTR & CLM reference: [docs/specifications/02_clm_language_specification.md](docs/specifications/02_clm_language_specification.md), [docs/archive/PCard Architecture.md](docs/archive/PCard%20Architecture.md)
- Implementation roadmap: [docs/implementation/06_Implementation_Phases.md](docs/implementation/06_Implementation_Phases.md)
- Reports & execution summaries: [docs/reports/](docs/reports/)
  - [WebSocket Performance Debugging](docs/reports/WebSocket_Performance_Debugging.md)
  - [Petri Net Implementation](docs/architecture/Petri_Net_Implementation.md) — Physical implementation mapping

## Platform Vision & Architecture

The historical foundations and architecture of MCard_TDD center structurally around the **Data-Function Duality**—where passive data and active software functions resolve completely symmetrically within the exact same conditionally upgradable geometric memory space.

By mechanically evaluating operations across the 4-step `prep → exec → post → await` Petri Net schedule, the execution pipeline explicitly enacts **Euler's Four-Square Identity**, maintaining perfect geometric norm conservation between inputs, functional transformations, and resulting output topologies.

This mathematically restricts memory and side-effects from tearing out of scope via perfect **Algebraic Closure**, fundamentally grounding MCard_TDD analytically as a strict **Purely Functional Operating System**.

These operational structures are detailed extensively inside the **[Architecture Overview](docs/architecture/00_Architecture_Overview.md)** and the **[PTR Meta-Circular Runtime](docs/architecture/03_Pillar2_PTR_Meta_Circular_Runtime.md)** suites.

> - [Euler's Four-Square Closure](docs/theory/01_foundations/Euler_Four_Square_Closure.md) — Demonstrable Proof of Algebraic Integrity.
> - [DOTS → PTR Meta-Language](docs/WorkingNotes/Hub/Theory/Integration/The%20Operational%20Meta-Language%20-%20From%20DOTS%20to%20PTR.md) — Theoretical framework

---

## Recent Updates

> **Full changelog:** [CHANGELOG.md](CHANGELOG.md)

**Current versions**: Python `mcard` 0.1.71 · TypeScript `mcard-js` 2.1.54

**BMAD Documentation Refactor: The Kenotic Kernel & CRDT Integration (April 27, 2026)**: Executed a targeted surgical audit of the documentation suite to formalize the **Tri-Tier PTR Architecture**. Elevated the shell-native `clmEval` to its rightful place as the **Zeroth Tier (Shell-Native) Kenotic Kernel**, proving that the Symmetric Monoidal Category (SMC) transitions hold mathematically true down to the lowest POSIX OS level. Additionally, wove the **Content Addressable Schema** into the architecture docs as the fundamental mechanism for maintaining data consistency and enabling Conflict-Free Replicable Data Types (CRDTs) across distributed multi-agent meshes.

**Meta-Circular Augment Refactoring & Petri Net Flow Formalization (April 22, 2026)**: Decoupled the monolithic "augment" operation into a strict two-step Petri Net sequence (`load_file` and `insert`), mathematically ensuring pure state-passing boundaries between operations. Formalized `load_file` and `insert` as built-in native operations registered directly in the PythonRuntime `DEFAULT_OPERATIONS` dictionary, removing arbitrary inline Python code, and synced `clm_reserved_words.yaml` to include the new operators under the Kenotic grammar dictionary. The `load_file` operation was also upgraded to natively ingest binary file byte-streams. Also, developed `scripts/flowCubed.py`, a new execution harness that natively evaluates Petri Net structures via the PTREngine, and patched the URI resolver (`mcard/ptr/core/resolver.py`) to correctly parse relative `file:` schemas to safely resolve local structures without URI path truncation.

**Governance Analytics & Bootstrap Synchronization (April 22, 2026)**: Replaced legacy "5-E Measurement" framework traces across all 9 `clm/bootstrap_phases/` YAML definitions traversing `00` through `07`. Synced all `five_e_metrics` natively into our mathematical bounds tracked by Token Arithmetics: `possibility_magnitude` ($\mathcal{M}$), `governance_narrowing` ($\mathcal{N}$), `epiplexity_yield` ($\mathcal{E}$), and `product_dependency_count` ($\Pi$). Scoured lifecycle bounds identifying loose terminology (`PREP -> EXEC -> POST`, `T_prep`), refactoring identical strict topological bounds `Stage 1 (PREP)`, `Stage 2 (EXEC)`, `Stage 3 (POST)`. Lastly, deleted `07_phase_h_five_e_measurement.yaml`, replacing it with `07_phase_h_governance_analytics.yaml` natively bridging Phase H directly into tracking topologies in `docs/implementation/06_Implementation_Phases.md`. Ran the entire 42-level identity and execution sequence verification natively via `tests/bootstrap/` ensuring identical Python/YAML pipeline resolution.

**Legacy Core Deprecation: CLMRunner & Kenotic Networking (April 22, 2026)**: Successfully deprecated and purged the legacy `mcard/ptr/runner.py` in favor of the strict PTREngine lifecycle boundaries, reducing the underlying code volume and strictly enforcing the "Zero-State" Tabula Rasa assumption. Deleted the intrinsic networking stack (`mcard/ptr/network/`) enforcing the Kenotic architectural principle that all I/O boundary executions must be strictly handled through explicit User-Space PCards rather than buried kernel integrations. Completely refactored testing borders (rewriting gatekeeper assertions directly via `PCard.can_fire`) mitigating legacy test noise and optimizing the codebase layout.

**Implementation Documentation Harmonization & Phase A.1/B Native Code (April 22, 2026)**: Authored the `08_Phase_B_Schema_Injection.md` defining the multi-modal injection pipeline, handle registry population, and T01–T03 integration bounds. Exhaustively sanitized the 10-document implementation suite by enforcing strict terminological boundaries—specifically renaming generic “Phase” execution wrappers into "Stage 1 (PREP)", "Stage 2 (EXEC)", and "Stage 3 (POST)" to eliminate namespace collision with the macro A-H roadmaps. Synchronized testing bounds by explicitly mapping the `T00.1`–`T00.4` Genesis Identity tests into the core validation sequence. Furthermore, completed the native Phase A.1 code (`mcard/bootstrap/clm_hooks.py`) by generating rigorous `Ed25519` CSPRNG keys natively enforcing geometric parity with `did:key:z6Mk...` multi-codec prefixes via the `base58` package. Bound these identical logic bounds aggressively to testing architecture under `test_t0_1_identity_genesis.py`, verifying Tabula Rasa isolation patterns safely executing to 100% specification parity.

**Genesis Identity Bootstrap & API Stabilization (April 21, 2026)**: Formalized the bootstrapping procedure for the Agentic OS, establishing the transition from a Tabula Rasa state to a provisioned sovereign identity layer via a new 10-step bootstrap lifecycle (`00a_phase_a_genesis_identity.yaml`). Implemented the corresponding `07_Genesis_Identity_Bootstrap.md` implementation guide to document identity bounds and boot certification limits. Additionally, fortified the native FastAPI boundary layer (`mcard/api.py`) by isolating synchronous storage engine calls safely inside `asyncio.to_thread` execution wrappers, structurally resolving latent asynchronous 500 runtime TypeErrors during concurrent HTTP invocations.

**Polyglot Type Parity & Asynchronous Stabilization (April 21, 2026)**: Integrated `ts-rs` into `mcard-core` to establish a mathematically sound, self-generating type contract across the Rust workspace and the TypeScript boundaries autonomously. Authored `common_data_types.rs` in `mcard-core`, equipping graphical components (e.g. `Vector3`, `MeshDescriptor`) with unified schema definitions exported as canonical `.ts` structures. Additionally introduced `zod` as the central validation layer across `mcard-js` and `mcard-studio` to block structurally compromised data upstream. Addressed core memory/blocking bottlenecks during payload parsing by migrating `Loader.ts` to memory-conserving Async Generators (`loadFileToCollectionStream()`) for backpressure ingest, and leveraging `Comlink` WebWorkers in `mcard-studio` to push heavy schema validation entirely off the React main thread.

**Prologue Chapter Systematic Renumbering & Canonical CLM Sequence (April 21, 2026)**: Completed the comprehensive reorganization of `chapters/chapter_00_prologue/` into a logically sequenced 18-CLM canonical curriculum (01–18). Established a pedagogical progression from meta-circular foundations (01) through Turing-tape semantics (02–09) to sovereign identity workflows (10–18). Renamed files for lexical sortability: `01_meta_circular_ptr.yaml`, `02_turing_tape_tri_database.yaml` through `09_petri_net_workflow.yaml`, then identity suite `10_kenotic_identity_issuance.yaml` through `18_identity_bootstrap.yaml`. Updated `README.md` and created `_VCARD_MANIFEST_SCHEMA.md` establishing canonical envelope and DID test vector specifications for all identity CLMs. All cross-references synchronized across documentation suites.

**Clojure Convergence Documentation Propagation (April 20, 2026)**: Propagated the new Clojure/Datomic integration research from the WorkingNotes theory hub into the canonical documentation layers. Added a new `0.2 Prior Art: The Clojure Convergence` section to `docs/architecture/02_Theoretical_Foundations.md`, connecting Hickey's value/identity/time separation, HAMT structural sharing, and Datomic's immutable-fact model directly to the MCard tri-database. Extended `docs/specifications/03_data_architecture.md` with `1.5 Lineage: From Datomic to MCard`, mapping Datomic concepts to MCard storage semantics, contrasting Datomic Cloud / XTDB / MCard, and outlining migration paths for existing immutable-fact deployments. Updated `docs/implementation/00_INDEX.md` with a new lineage section linking implementers to the four companion articles on De-Complecting Knowledge, Transducers, spec/Malli/CLM, and Datomic/XTDB/MCard.

**Two-Tier Application Architecture & OS Boundary Formalization (April 20, 2026)**: Formalized the core MCard storage model around the UNIX Privilege Boundary metaphor, structurally isolating the pure system engine from scale-free application logic. Explicitly categorized the Four-Database topology (Kenotic Root + Tri-Database) as the **Privileged Kernel Space**, mapping generative operations and PWA logic to execute securely inside **Restricted App Space** via `VCard` syscalls. Integrated external Application Package Distribution via `app_store.db`, allowing natively shared CLM PCards without bloating individual agent Tri-Databases. Connected PCard resolution to UNIX resource optimization logic — executing a shared MCard acts as an infinitely scalable Copy-on-Write `fork()` operation bridging external registry boundaries.

**React and ESM Module Resolution Fixes (April 20, 2026)**: Resolved critical `vite` build errors and ESM import regressions inside the `mcard-studio` PWA. Migrated away from deprecated default exports in `animejs` v4, refactoring `useGovernanceTelemetry.ts` and `AnimeJsEngine` to use direct `animate(targets, {...})` parameters. Handled duplicate `React` module imports within `NavigationSidebar.tsx` resolving frontend rendering crash loops.

**Implementation Documentation Reorganization & Status Update (April 20, 2026)**: Reorganized the 7-document `docs/implementation/` suite to follow a logical dependency chain: Theory (§01 Data-Function Duality) → Mapping (§02 Architecture-to-Code) → Patterns (§03 PocketFlow Integration) → Specs (§04 Component Specs) → Testing (§05 Testing & Validation) → Roadmap (§06 Implementation Phases). Updated `06_Implementation_Phases.md` with comprehensive evidence-based status dashboard (923 Python tests, 131 CLM files, Rust SDK status) — Phases A–D complete, Phase E ~70%, Phase F ~55%, Phase H ~40%. All internal cross-references across 9 files and external references in `CHANGELOG.md` updated to new numbering.

**Agentic OS Governance Formalization & Token Arithmetics (April 20, 2026)**: Completed a comprehensive documentation propagation establishing governance as a **structural consequence** of the MCard architecture — not an add-on feature. Formalized the Token Arithmetics framework synthesizing Petri Net tokens (state-enabling markers) and Cryptoeconomic proofs (causal evidence) through algebraic type theory: **Sum Types** ($A + B$, branching entropy), **Product Types** ($A \times B$, topological dependencies), and **Exponent Types** ($B^A$, combinatorial possibility spaces). Defined four quantitative governance metrics — **Possibility Magnitude** ($\mathcal{M} = |B|^{|A|}$), **Governance Narrowing** ($\mathcal{N}$), **Epiplexity Yield** ($\mathcal{E}$), and **Product Dependency Count** ($\Pi$) — integrated across 12 documents spanning architecture (§1.7 Inherent Governance, §03 Token Arithmetics), specifications (§04 §2.5 Formal Vocabulary, §05 §1.1.1 ABC Governance Vocabulary), and implementation (Phase H: Governance Analytics, PTRSharedStore governance fields, Governance Plane Tests, PCard Sandwich as Governance Pipeline).

**Multi-Modal Viewers & Generative Synthesis (April 19, 2026)**: Completed Phase F.2 integration, establishing rich multi-modal artifact rendering and strictly offline Generative Synthesis. Implemented native `AudioViewer`, `VideoViewer`, and `Model3DViewer` inside the Studio PWA using HTML5 APIs and `@react-three/fiber`. Developed purely algorithmic Generative Interceptors within `ChatbotPanel`—bypassing heavy external API-keys by deterministically synthesizing authentic `.png` diffusion mockups and 44.1kHz `.wav` PCM oscillator payloads entirely inside the browser. This mathematically proves the end-to-end multi-modal data pipeline (Prompt → Algorithm Generation → Data Blob → VCard Registry → Viewer Engine Render) without compromising MCard's strict offline, Local-First Sovereign constraints.

**TypeScript Runtime Kenotic Decoupling & OPN Parity (April 19, 2026)**: Completed the architectural parity between the `mcard-js` TypeScript implementation and the `mcard` Python runtime by formalizing the OPN-based `PTREngine` execution flow. By cleanly extracting the Sandbox, Certifier, and Gatekeeper verification boundaries, the TS runtime completely mirrors the formally verified Petri Net constraints. Mathematical Evaluation traces (`witnessPrecondition`, `witnessPostcondition`, `sandwich`) are formally preserved in a `VCardSandwich.ts` builder to correctly map proofs across both boundaries identically.

**MCard Kernel Modularization & Data-Driven Ecosystem (April 19, 2026)**: Finalized the transition of the MCard kernel computing engine toward a purely modular, schema strict execution boundary. Formally expunged all hardcoded networking logic (`p2p_session.py`, `signaling_server.py`, `discovery.py`), honoring the Kenotic Principle by deferring P2P orchestration dynamically out to user-space network topology CLMs. Stabilized the polyglot integration suite through a globally shared dynamic registry parsing runtime mappings natively from `schema/runtime_types.json` and strict validation fallbacks via `schema/mcard_system_config.yaml`—safely centralizing timeouts, allowed sandbox globals, and engine extensions completely independently of Python logic files. Finally, eradicated arbitrary SQLite loop-trigger application crashes across the framework natively merging `CREATE TRIGGER` bounds centrally into the explicit `schema/mcard_schema.sql` definitions ensuring flawless DuckDB and SQLite polyglot loading synchronicity. All 836+ local unit tests uniformly pass under rigorous Data-Function parity architectures safely bounding execution state completely inside the declarative space.

**Petri Net PTR Execution Engine (April 19, 2026)**: Implemented first-class Petri Net composition for concurrent PCard execution, realizing the specification's "Concurrent Function Scheduler" (04_execution_engine §2). New modules: `petri_net.py` (Place/Transition/Marking/PetriNet dataclasses with sink-aware deadlock detection and Coloured Petri Net typed places), `net_engine.py` (ThreadPoolExecutor-based concurrent firing with compensating actions), and `resolver.py` (recursive PCard resolution via content hash, CLM handle, file URI, and trust-gated URL). `CategoryCombinators` now produces PetriNet topologies via `compose_net()`/`split_net()`/`augment_net()`, `PCardFlow.to_petri_net()` bridges action-routing DAGs to formal nets, and `PTREngine.execute_net()` auto-detects composite PCards for graph-based execution. 876 tests (+47), 0 regressions.

**Architecture Formalization & CHL Temporal Integration (April 19, 2026)**: Conducted a profound unification of the underlying Operational OS logic, firmly rooting "Vibe Coding" and Edge CI/CD within the Curry-Howard-Lambek (CHL) Isomorphism. By mechanically mapping Design Time (Lambek/Future), Compile Time (Howard/Present), and Execution Time (Curry/Past) to deterministic Cubical Logic semantics, the architecture ensures complete, fine-grained control over how new LLM-driven knowledge evolves. Fully integrated Mathematical Galois Connections ($\alpha \dashv \gamma$) and Operadic Calculus across the architecture documentation suite, guaranteeing eventual consistency computationally bounded by pure CRDT properties.
**Dynamic Library Function Invocation (April 24, 2026)**: Introduced the `invoke_library` operation to the PTREngine across Python and JavaScript. This enables CLMs to specify and execute external library functions purely by declaring module and function signatures, packing variables dynamically from context, natively evaluating test execution boundaries (`balanced_expc`), and removing the need for explicit logic implementations in YAML payloads.

**CLM Syntax Standardisation (April 24, 2026)**: Formally standardized the CLM YAML schema across all specification documents and test files. The schema now strictly mandates `abstract_spec` (with `context`, `goal`, `success_criteria`), `concrete_impl` (with `inputs`, `process`, `outputs`), and `balanced_expc` (with `test_cases` containing `given`, `when`, `then`). Baseline polyglot execution tests for Python and JavaScript were implemented to perfectly mirror this schema requirement.

**Phase E.2.a PTR Engine Formalization & VCard Sandwich Parity (April 19, 2026)**: Finalized the Python Phase E.2.a implementation mapping the PTR Execution Engine natively to the Three-Plane Sovereign Architecture markers (`_prep`, `_exec`, `_post`). Enforced the VCard Sandwich data patterns ensuring strict execution telemetry nesting and correctness bounds evaluation. Restructured `PTRSharedStore` enforcing the pure Four-Database Topology, aligning topological CRDT lattice-join limits matching Strong Eventual Consistency (SEC) validations smoothly across polyglot operations natively without dependency bleed. Resolved legacy regression unit tests and stabilized isolated local inference dependencies (`qwen3:0.6b`).

**Unified Categorical Hierarchy: `MCard → PCard → VCard` (April 19, 2026)**: Refactored the class hierarchy from a flat fork to the architecturally mandated linear chain (`MCard → PCard → VCard`), aligning the Python model with the Monad → Functor → Applicative categorical hierarchy and the Currying Formula `VCard(PCard(MCard)) = Result`. VCard now overrides PCard's `_validate_and_parse()` as the canonical *guard* (precondition) layer, gracefully accepting JSON VCard Sandwich, YAML, and non-dict content. VCard instances inherit PCard's CLM triad accessors, SMC algebraic combinators (`.then()`, `.and_also()`, `.swap()`), and Petri Net boundary specs — eliminating code duplication while preserving full backward compatibility (829 tests, 0 regressions).

**Phase D Orchestration & Pure Functional OS Formalization (April 17, 2026)**: Completed Phase D of the execution roadmap. Established robust dependencies mapping `AuditVerifier` inside Python and JS engines natively tracking mathematical Hoare logic sandwich execution boundaries. Formally proved system architecture complies strictly with Pure Functional Operating System paradigms via `docs/theory/Euler_Four_Square_Closure.md` dictating algebraic preservation across the 4-phase computation geometry.

**Native Rust Adaptive Intelligence Routing — Phase E.3 (April 17, 2026)**: Successfully mapped the Local-First Sovereign Fallback limits directly into the native Rust Executor (`rsCubed`). Implemented the `IntelligenceRouter` natively relying exclusively on synchronous `ureq` execution constraints, structurally dodging Async ecosystem bloat. Bound exact execution trace spans directly from the Rust engine into `execution_log.db`, successfully capturing `[EXECUTION_WARNINGS]` during offline edge node (`qwen3:0.6b` via Ollama) fallback logic executions natively mapping the Python/JS architectures gracefully.

**Deterministic LLM Executions & Token Exhaustion Fixes (April 16, 2026)**: Stabilized Live LLM inference test suites across both the Node (`mcard-js`) and Python (`mcard`) environments, protecting deterministic assertions against both token exhaustion and entropic hallucination constraints. Fixed `AdaptiveFallback.test.ts` failure by bumping logic fallbacks to `max_tokens: 4096` bypassing `qwen3:0.6b` early termination bugs. Resolved `test_clm_execution` non-determinism in Python by explicitly suppressing evaluation randomness (`temperature: 0.1` inside `question_answer.clm`) satisfying mathematical validations.

**WASM & ESM Studio Integration Parity (April 16, 2026)**: Resolved fatal Astro `buildEnd` hooking issues targeting `detect_content_type` Rust endpoints natively. Repackaged local `mcard-wasm` workspaces natively with `wasm-pack build --target bundler` replacing outdated Node-specific limits. Fixed missing workspace linkage bounds in `mcard-studio`'s configuration pipeline to correctly ingest file-level native dependencies natively testing Vitest compatibility accurately.

**Automated Tests Execution & Loader Enhancements (April 16, 2026)**: Drastically enhanced the execution performance and stability of the filesystem loader and the test CI/CD pipelines. Implemented heuristic optimizations to the `file_io` directory scanner, programmatically excluding extreme-scale dependency repositories (`node_modules`, `venv`, `build`) from recursively exhausting validation operations. Resolved fatal SQLite `disk I/O error` failures triggered during heavy test concurrency by safely purging lingering `.db-wal` / `.db-journal` sidecars. Hardened the `cli.py` polyglot suite discoverer, enforcing parity with the Makefiles to ensure offline experimental fixtures prefixed with underscores (`_`) remain correctly excluded from test builds.

**Native Qwen3 (0.6B) LLM Integration (April 16, 2026)**: Executed a comprehensive workspace migration transitioning the foundational local-first offline Inference models from Gemma4 over to Qwen3 (0.6B). Synthetically updated all structural binding pointers natively hardcoded into the Python architecture (`ollama.py`, `runtime.py`), the JavaScript GraphRAG validation pipeline (`Config.ts`), and explicitly across all central Cubical Logic Model specifications. Local machine testing suites and auto-fallback routing workflows now seamlessly invoke `qwen3:0.6b` via Ollama orchestration.

**Pristine Repository Cleanup & Test Stability (April 16, 2026)**: Maintained rigorous project working directory hygiene by establishing a pristine root state, safely removing stale AI/IDE metadata directories and leftover cache artifacts. Resolved integration test flakiness in `Q_A.yaml` by enforcing explicit formatting instructions in the prompt, successfully verifying that qwen3:0.6b mathematical output parsing reliably aligns with deterministic `result_contains` assertions. Enforced data volume purity by removing stray `triadic_small.db` databases and wiring Chapter 04 Triadic loaders strictly into the primary `content_memory.db` matrix. Patched the cross-runtime continuous integration Makefile to aggressively exclude nested `/test_data/` payload directories from executing as phantom test scripts, whilst officially shifting dependent network interaction test harnesses (`sync_client.yaml`, `sync_server.yaml`) entirely to manual suite integration via logical file prefixing.

**Local-First Sovereign AI & Adaptive Intelligence Routing (April 16, 2026)**: Formalized the architecture ensuring MCard_TDD relies upon local-first, native inference loops to secure absolute cognitive autonomy. The execution suite was overhauled to weave an `IntelligenceRouter` dynamically routing LLM workflow states across three environments depending on active availability: Online APIs, Overlay VPN community instances, or complete offline Local-First inference engines (e.g. Gemma4). Episodic planning memory logs are mathematically isolated and trapped locally within `data/execution_log.db`, entirely circumventing logic leakage to the cloud. PocketFlow's resilience handling natively triggers this automatic offline edge-model failover when external APIs become unreachable. The foundational topological map (`seed_clm_playbook.yaml`) and operational fallback validators (like `tell_a_joke.yaml`) were migrated into the strict central `clm/` directory — bridging cross-runtime verification cleanly between the polyglot JS (`jsCubed`) and Python (`pyCubed`) execution environments.

**Tri-Database Directory Configurability & Portability (April 15, 2026)**: Explicitly documented the configurable nature of the Tri-Database directory (`agent_identities.db`, `content_memory.db`, `execution_log.db`) across all four core specification documents. While the default path is `./data/` for development and testing convenience, the directory is **fully configurable** via `config_constants.DEFAULT_DB_PATH` (Python) or runtime configuration (JavaScript/TypeScript). This enables portable deployments across diverse environments—production servers (`/var/lib/mcard/data/`), containerized deployments (`/app/data/`), user home directories (`$HOME/.mcard/data/`), or ephemeral storage—without architectural changes. The Kenotic Root (`meta_functionality.db`) maintains the reference to the active Tri-Database path.

**Polyglot Runtime Executor Specification (April 15, 2026)**: Explicitly documented the CLM runtime triggering mechanism across all four core specification documents (Product Requirements, CLM Language, Data Architecture, Execution Engine). Established that `scripts/pyCubed.py` (Python PTR) and `scripts/jsCubed` (JavaScript PTR)—plus future `{lang}Cubed` executors—trigger CLM execution by reading the shared `meta_functionality.db` from the project root and resolving database paths relative to the same directory. This architecture enables a single `MCard_TDD` project to seamlessly host Python, JavaScript, Rust, Go, Lean, and future language runtimes under unified Four-Database Topology configuration.

**Specification Suite Architectural Review & Four-Database Topology Formalization (April 15, 2026)**: Completed comprehensive system architect review of the entire MCard product specification suite (7 documents + seed CLM YAML), identifying and resolving logical conflicts and conceptual holes. Key fixes: (1) Formalized **Four-Database Topology** terminology—Kenotic Root (`./meta_functionality.db`) + Tri-Database (`data/*`)—resolving the "3 databases vs 4 databases" inconsistency; (2) Clarified **VCard dual roles**—as data (MCard with cryptographic proofs) and as execution boundary (Precondition/Postcondition wrappers); (3) Added **REPL execution pattern** section to execution engine spec with Head Reduction (→h) and Head Expansion (↝); (4) Distinguished **ABC Curriculum** (temporal workflow: Assumption→Behavior→Confirmation) from **CLM A×C×B triad** (structural dimensions); (5) Enhanced cross-references between architecture and specification docs; (6) Updated seed CLM YAML with `four_database_topology` stanza. All 7 specification documents now maintain rigorous architectural consistency.

**CLM Test Suite Stabilization & Model Migration (April 14, 2026)**: Standardized the CLM test vocabulary by canonicalizing `balanced.scenarios` → `balanced.test_cases` across all 5 identity CLMs in `chapter_00_prologue`, fixing silent test skipping. Migrated the default Ollama model from `gemma3:latest` to `qwen3:0.6b` across entire codebase (Python + TypeScript). Hardened both CLI directory scanners to exclude `test_data/`, `__pycache__/`, and `node_modules/` from recursive CLM discovery, preventing fixture data from being parsed as CLM specs. Fixed LLM runtime JSON serialization crashes and prompt pollution. Increased `max_tokens` to `4096` for thinking-model compatibility.

**Decoupling Bootstrap Native Logic Executions (April 14, 2026)**: Completed the architectural transition of the PKC ecosystem's bootstrap and topological schemas by securely migrating dynamic Python procedural logic out of inline YAML structures into `mcard/bootstrap/clm_hooks.py`. Hardened dependency proxying native injection, bypassing import restrictions and isolating topological logic declaratively. Abstracted `mcard-cli` system generation data-structures by substituting hard-coded databases with global integration via `BootstrapSettings` subclass topology instantiation dynamically routed.

**PKC Bootstrapper Formalization & Inception Constraint (April 11, 2026)**: Established the Inception Constraint within the PKC ecosystem, ensuring code execution strictly requires topology validation (`meta_functionality.db`) upon PTREngine initialization. Standardized the topological graph parsing to target `seed_clm_playbook.yaml` by default via the newly decoupled `KernelBootstrapper`. Automated full T0-T5 boot certification flows.

**Async-First Architecture & Flow Composition (April 04, 2026)**: Brought native async execution paths and composable flows to the PTR.

- Python
  - Async wrappers: `AsyncPTREngine` with async DB prefetch (`CardCollection.aget/aadd`), sandbox (`aexecute`), and verifier (`averify_clm_consistency`).
  - CLI: `--async` flag to run CLM files via `AsyncPTREngine.run_file_async()`.
  - Flow composition: `FlowNode`, `flow_from_spec()`, `PTREngine.run_flow()` and `run_flow_file()`.
  - CLI: New `flow` subcommand to execute declarative flow YAMLs.
- TypeScript
  - Shared Store: `src/ptr/core/SharedStore.ts` for parity with Python `PTRSharedStore`.
  - PTREngine: Added retry helper (`executeWithRetry`), batch APIs (`executeBatch`, `executeBatchParallel`).
  - Flow composition: `src/ptr/core/Flow.ts` with `PCardFlow`, `FlowNode`, `flowFromSpec`, and helpers.
  - Tests: Adjusted real-HTTP integration test timeout; all JS tests pass locally (56 files, 883 tests).

Docs: `docs/implementation/06_Implementation_Phases.md` updated — Async-First (Task 10) and Flow Composition (Task 11) marked complete.

**PTREngine Arrow Interface & VCard Sandwich Parity (April 03, 2026)**: Completed the formal PTR refactoring across both Python and JavaScript, achieving exact API parity. Introduced `PTREngine` as the canonical Arrow execution primitive with `runWithSandwich()`, `arr()`, `compose()`, `first()`. Added VCard Sandwich static methods (`witnessPrecondition`, `witnessPostcondition`, `sandwich`) for boundary verification proofs. Enforced the Kenotic Principle by deprecating kernel-level networking modules (`NetworkRuntime`, `SignalingServer`, `P2PChatSession`) in favor of user-space PCard workloads (`chapters/networking/`). Added `make clm-run` targets for executing all CLM chapters across both runtimes. Python: 407 tests, JS: 884 tests, 0 failures.

**Autonomous Mesh Discovery & Identity Validation (April 02, 2026)**: Fully implemented mDNS "Friendly Network" peer discovery in both the Python and JavaScript runtimes. The single-boot `launch` command now natively spins up the node, API, Studio, and zero-conf sniffer all in one process. GTime triplet execution traces now correctly extract and cryptographically bind the authentic user identity (`did:key:xxxx`) pulled dynamically from the Studio UI's native IdentityStore rather than using environment variables. All parity tasks completed.

**PTR Security Hardening — Bandit Remediation (March 31, 2026)**: Systematic remediation of all Medium and High severity findings from Bandit static analysis across 19 files. Introduced `mcard/utils/url_safety.py` — a centralized `safe_urlopen()` helper that validates URL schemes (`http`/`https` only) before opening, replacing raw `urllib.request.urlopen` calls in 7 modules. Migrated XML parsing to `defusedxml.ElementTree` (with stdlib fallback) to prevent XXE/billion-laughs attacks. Eliminated `shell=True` subprocess calls in the signaling server by converting to safe array-based invocations. Fixed weak MD5 usage in network cache key generation with `usedforsecurity=False`. All 770 Python tests pass with 0 High / 0 Medium Bandit findings.

**Config Unification, Canonical Env Templates, and Smoke Cleanup (March 28, 2026)**: Centralized shared configuration defaults in `config/app_config.json` with parity across Python, TypeScript, and studio runtime helpers; standardized the root `example.env` / legacy `.env.example` contract plus `mcard-studio/example.env`; documented environment precedence and CI seeding; and quieted boot-time ingest warnings during smoke runs while preserving the startup summary and the standalone websocket server path.

**Binary File Size Limit Increase (v0.1.64 / v2.1.47)**: Raised the maximum binary file size from 50 MB to 150 MB across all runtimes (Python, TypeScript, Studio), enabling ingestion and preview of larger PDF, video, and other binary assets. Updated `MAX_FILE_SIZE`, `MAX_ARTIFACT_SAVE_BYTES`, `MAX_BINARY_PREVIEW_BYTES`, and problematic-file thresholds in 7 files.

**Polyglot Runtime Stabilization & CLM Pipeline (v0.1.63 / v2.1.46)**: Stabilized the cross-environment execution pipeline for Cubical Logic Models (CLMs) across Python, Node.js, and Rust/WASM. Improved Python interpreter resolution in the JS SDK, added first-class Node.js runtime support, and implemented automatic server-side delegation for Node-dependent browser CLMs. Fixed gatekeeper evaluations and test assertions across all 13 prologue CLMs, achieving 100% test pass rates in both the CLI and Studio environments.

**Pedagogical Game Integration via ZITADEL SSO**: Added authenticated views for Chess, Go, and Monopoly to `LandingPage`, using ZITADEL OIDC to protect game state boundaries and user identity mapping as part of the broader ethnographic scaling research implementations.

**Identity System Authentication Update (v0.1.62 / v2.1.45)**: Implemented a complete credential-based identity authentication system in `mcard-studio`, replacing the previous passwordless registration flow with server-side PBKDF2 password hashing and timing-safe login verification.

**Polyglot Runtime & WASM Integration Fixes (v0.1.60 / v2.1.43)**: Fixed critical missing `--experimental-wasm-modules` environment flags in Python subprocess integration, rectified `module://` protocol resolution for cross-environment testing, and enforced `importlib` dynamic module bootstrapping in NodeJS. Patched Rust/TypeScript content-type string detection parity bugs and Python 3.9 `__future__` typing incompatibilities.

**Python Build & Syntax Corrections (v0.1.59 / v2.1.42)**: Fixed `mcard` syntax, namespace, and import dependency compilation errors across `improved_logging.py`, `card_collection.py`, and `logging_config.py`. Restored 100% test build health.

**Storage Layer Deduplication (v0.1.58 / v2.1.42)**: Comprehensive refactoring to centralize card operations into `AbstractSqlEngine` (TypeScript) and simplify connection paths via `resolve_db_path()` (Python). Eliminated over 250 lines of duplicate code across the 4 TypeScript SQL engines, standardized dialect handling (SQLite `TEXT` vs DuckDB `VARCHAR`), and fixed a latent foreign key bug in handle renaming. All functionality remains fully backward compatible.

**🏗️ Major Project Restructuring (v0.1.56 / v2.1.38)**: Four-phase structural overhaul — root files relocated to proper directories, documentation reorganized (32 flat files → 7 subdirectories), scripts reorganized (19 files → 6 subdirectories), Python tests restructured (28 files → 5 subdirectories), TypeScript engine implementations moved to `storage/engines/` with barrel re-exports, factory pattern migration (`SqliteNodeEngine.create()`), test database cleanup, and `.gitignore` hardening. Runtime behavior is unchanged; all 849 TS tests and 767 Python tests pass.

Recent milestones also include DuckDB as an alternative storage engine, shared MIME registry (`mime_extensions.json`), PTR exception narrowing (109 broad catches → specific types), SqlJs vector adapter for browser-based vector search, and ContentTypeInterpreter event-loop starvation fix. See [CHANGELOG.md](CHANGELOG.md) for full details.

## Testing

> **Note:** All commands below should be run from the project root (`MCard_TDD/`).

### Unit Tests

```bash
# Python
uv run pytest -q                 # Run all tests
uv run pytest -q -m "not slow"   # Fast tests only
uv run pytest -m "not network"   # Skip LLM/Ollama tests

# JavaScript
npm --prefix mcard-js test -- --run

# Browser (MCard Studio)
npm --prefix mcard-studio run test:unit -- --run
```

### CLM Verification

Both Python and JavaScript CLM runners support three modes: **all**, **directory**, and **single file**.

#### Unified (Makefile)

```bash
make clm-list       # List all available CLM chapter files
make clm-run-py     # Run all chapters through Python PTR
make clm-run-js     # Run all chapters through JavaScript PTR
make clm-run        # Run both runtimes sequentially
```

#### Python

```bash
# Run single file
uv run python -m mcard.ptr.cli run chapters/chapter_01_arithmetic/addition.yaml

# Run single file in test mode (human-readable output)
uv run python -m mcard.ptr.cli run chapters/chapter_01_arithmetic/addition.yaml --test

# Run all CLMs in a directory
uv run python -m mcard.ptr.cli run chapters/chapter_01_arithmetic --test

# Run with custom context
uv run python -m mcard.ptr.cli run chapters/chapter_08_P2P/generic_session.yaml \
    --context '{"sessionId": "my-session"}'

# List available CLMs
uv run python -m mcard.ptr.cli list

# Check runtime status
uv run python -m mcard.ptr.cli status --verbose
```

#### Flow Execution (Python)

```bash
# Execute a declarative flow YAML against a target
uv run python -m mcard.ptr.cli flow sample_pcards/flows/sample_flow_js.yaml \
  --target sha256:my_target --inputs '{"param": 1}'

# Async execution path (delegates sync code via thread pool)
uv run python -m mcard.ptr.cli flow sample_pcards/flows/sample_flow_js.yaml \
  --target sha256:my_target --inputs '{"param": 1}' --async
```

#### JavaScript

```bash
# Run all CLMs
npm --prefix mcard-js run clm:all

# Run single file
npx tsx mcard-js/src/ptr/node/cli.ts run chapters/chapter_01_arithmetic/addition_js.yaml --test

# Run all CLMs in a directory
npx tsx mcard-js/src/ptr/node/cli.ts run chapters/chapter_01_arithmetic --test

# List available CLMs
npx tsx mcard-js/src/ptr/node/cli.ts list

# Check runtime status
npx tsx mcard-js/src/ptr/node/cli.ts status
```

### Chapter Directories

| Directory                 | Description                                                  |
| ------------------------- | ------------------------------------------------------------ |
| `chapter_00_prologue`   | Hello World, Lambda calculus, identity basics, and Church encoding — 13 CLMs |
| `chapter_01_arithmetic` | Arithmetic operations (Python, JS, Lean) — 27 CLMs          |
| `chapter_02_handle`     | Handle operations and dual retrieval                         |
| `chapter_03_llm`        | LLM integration (requires Ollama)                            |
| `chapter_04_load_dir`   | Filesystem and collection loading                            |
| `chapter_05_reflection` | Meta-programming and recursive CLMs                          |
| `chapter_06_lambda`     | Lambda calculus runtime                                      |
| `chapter_07_network`    | HTTP requests, MCard sync, network I/O — 5 CLMs             |
| `chapter_08_P2P`        | P2P networking and WebRTC — 16 CLMs (3 VCard)               |
| `chapter_09_DSL`        | Meta-circular language definition and combinators — 10 CLMs |
| `chapter_10_service`    | Static server builtin and service management — 3 CLMs       |
| `chapter_11_cicd`       | Quality checks (Python, JS, Studio, unified) — 4 CLMs       |
| `networking`            | Kenotic PCard workloads (mDNS, signaling) — 2 CLMs          |

---

## Contributing

1. Fork the repository and create a feature branch.
2. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the normalized workflow and project-wide validation commands.
3. Submit a pull request describing your change and tests.

---

## Future Roadmap

### Road to VCard (Design & Implementation)

Based on the **MVP Cards Design Thesis** (`LandingPage/pkc-docs/MVP Cards — Design Thesis for Sovereign Knowledge Networks.md`), a VCard (Value Card) represents a boundary-enforced value exchange unit that often contains sensitive privacy data (identities, private keys, financial claims). Unlike standard MCards which are designed for public distribution and reproducibility, VCards require strict confidentiality.

**Design Requirements & Rationale:**

1. **Privacy & Encryption**: VCards cannot be stored in the standard `mcard.db` (which is often shared or public) without encryption. They must be stored in a "physically separate" container or be encrypted at rest.
2. **Authentication Primitive**: A VCard serves as a specialized "Certificate of Authority" — a precondition for executing sensitive PTR actions.
3. **Audit Certificates**: Execution of a VCard-authorized action must produce a **VerificationVCard** (Certificate of Execution), which proves the action occurred under authorization. This certificate is also sensitive.
4. **Unified Schema**: While the storage *location* differs, the *data schema* should remain identical to MCard (content addressable, hash-linked) to reuse the rigorous polynomial logic.

**Proposed Architecture:**

* **Dual-Database Storage**:
  * `mcard.db` (Public/Shared): Stores standard MCards, Logic (PCards), and Public Keys.
  * `vcard.db` (Private/Local): Stores VCards, Encrypted Private Keys, and Verification Certificates.
* **Execution Flow**:
  `execute(pcard_hash, input, vcard_authorization_hash)`
  1. **Gatekeeper**: PTR checks if `vcard_authorization_hash` exists in the Private Store (`vcard.db`).
  2. **Zero-Trust Verify**: Runtime validates the VCard's cryptographic integrity and permissions (Security Polynomial).
  3. **Execute**: If valid, the PCard logic runs.
  4. **Certify**: A new `VerificationVCard` is generated, signed, and stored in `vcard.db`, linking the Input, Output, and Authority.

**TODOs:**

- [x] **Infrastructure**: Implement `PrivateCollection` (wrapper around `vcard.db`) in Python and JavaScript factories.
- [ ] **Encryption Middleware**: Add a transparent encryption layer (e.g., AES-GCM) for the Private Collection to ensure Encryption-at-Rest.
- [x] **CLI Auth**: Update `run_clms.py` to accept `--auth <vcard_hash>` and mount the private keystore.
- [x] **Certificate Generation**: Implement the `VerificationVCard` schema and generation logic (`VCard.sandwich()` in both runtimes).

---

### Logical Model Certification & Functional Deployment

Use of the **Cubical Logic Model (CLM)** as a "Qualified Logical Model" is strictly governed by principles derived from Eelco Dolstra's *The Purely Functional Software Deployment Model* (the theoretical basis of Nix).

A CLM is not merely source code; it is a candidate for certification. It only becomes a **Qualified Logical Model** when it possesses a valid **Certification**, which is a cryptographic proof of successful execution by a specific version of the Polynomial Type Runtime (PTR).

**The Functional Certification Equation:**

$$
Observation = PTR_{vX.Y.Z}(CLM_{Source})
$$

$$
Certification = Sign_{Authority}(Hash(CLM_{Source}) + Hash(PTR_{vX.Y.Z}) + Hash(Observation))
$$

**Parallels to the Nix Model:**

1. **Hermetic Inputs**: Just as a Nix derivation hashes all inputs (compiler, libs, source), a CLM Certification depends on the exact **PTR Runtime Version** and **CLM Content Hash**. Changing the runtime version invalidates the certificate, requiring re-qualification (re-execution).
2. **Deterministic Derivation**: The "build" step is the execution of the CLM's verification logic. If the PTR (the builder) is deterministic, the output (VerificationVCard) is reproducible.
3. **The "Store"**: The `mcard.db` acts as the Nix Store, holding immutable, content-addressed CLMs. The `vcard.db` acts as the binary cache, holding signed Certifications (outputs) that prove a CLM works for a given runtime configuration.

This ensures that a "Qualified CLM" is not just "code that looks right," but **"code that has logically proven itself"** within a specific, physically identifiable execution environment.

---

## License

This project is licensed under the MIT License – see [LICENSE](LICENSE).

For release notes, check [CHANGELOG.md](CHANGELOG.md).
