mcard 0.1.49
MCard: Local-first Content Addressable Storage with Content Type Detection
Requires Python: >=3.10

<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

MCard is a local-first, content-addressable storage platform with cryptographic integrity, temporal ordering, and a Polynomial Type Runtime (PTR) that orchestrates polyglot execution. It gives teams a verifiable data backbone without sacrificing developer ergonomics or observability.

---

## Highlights
- 🔐 **Hash-verifiable storage**: Unified network of relationships via SHA-256 hashing across content, handles, and history.
- ♾️ **Universal Substrate**: Emulates the Turing Machine "Infinitely Long Tape" via relational queries for computable DSLs.
- ♻️ **Deterministic execution**: PTR mediates **8 polyglot runtimes** (Python, JavaScript, Rust, C, WASM, Lean, R, Julia).
- 📊 **Enterprise ready**: Structured logging, CI/CD pipeline, security auditing, 99%+ automated test coverage.
- 🧠 **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.
- 🧰 **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 and session-scoped fixtures.

For the long-form narrative and chapter roadmap, see **[docs/Narrative_Roadmap.md](docs/Narrative_Roadmap.md)**. Architectural philosophy is captured in **[docs/architecture/Monadic_Duality.md](docs/architecture/Monadic_Duality.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
uv run pytest -q -m "not slow"  # run the fast Python test suite
uv run python -m mcard.ptr.cli run 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
```

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**: A standalone browser application using `mcard-js` (depends on `mcard-js` package).

### 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

The polyglot consensus tests require compiled binaries for C, Rust, and WASM runtimes. These must be compiled for your target architecture:

```bash
# Create bin directory
mkdir -p chapters/chapter_01_arithmetic/bin

# Compile C binaries (requires gcc)
gcc -o chapters/chapter_01_arithmetic/bin/logic_c chapters/chapter_01_arithmetic/logic.c
gcc -o chapters/chapter_01_arithmetic/bin/logic_advanced_c chapters/chapter_01_arithmetic/logic_advanced.c -lm
gcc -o chapters/chapter_01_arithmetic/bin/sine_chebyshev_c chapters/chapter_01_arithmetic/sine/sine_chebyshev.c -lm

# Compile Rust binaries (requires rustc)
rustc -o chapters/chapter_01_arithmetic/bin/logic_rs chapters/chapter_01_arithmetic/logic.rs
rustc -o chapters/chapter_01_arithmetic/bin/logic_advanced_rs chapters/chapter_01_arithmetic/logic_advanced.rs
rustc -o chapters/chapter_01_arithmetic/bin/sine_chebyshev_rs chapters/chapter_01_arithmetic/sine/sine_chebyshev.rs

# Compile WASM modules (requires rustup with wasm32-wasip1 target)
rustup target add wasm32-wasip1
rustc --target wasm32-wasip1 -o chapters/chapter_01_arithmetic/bin/logic.wasm chapters/chapter_01_arithmetic/logic.rs
rustc --target wasm32-wasip1 -o chapters/chapter_01_arithmetic/bin/logic_advanced.wasm chapters/chapter_01_arithmetic/logic_advanced.rs
```

> **Note**: WASM modules require the `wasm32-wasip1` target (WASI support) for execution via `wasmtime`. The `wasm32-unknown-unknown` target will not work.

For the **JavaScript CLM runner**, install the `wasmtime` CLI:
```bash
curl https://wasmtime.dev/install.sh -sSf | bash
export PATH="$HOME/.wasmtime/bin:$PATH"  # Add to ~/.bashrc for persistence
```

---

## Project Structure (abridged)
```
MCard_TDD/
├── mcard/            # Python package (engines, models, PTR)
├── mcard-js/         # TypeScript implementation & npm package
├── chapters/         # CLM specifications (polyglot demos)
├── docs/             # Architecture, PRD, guides, reports
├── scripts/          # Automation & demo scripts
├── tests/            # >750 automated tests
└── pyproject.toml    # uv-managed dependencies (uv.lock)
```

---

## Documentation
- Product requirements: [docs/prd.md](docs/prd.md)
- Architecture overview: [docs/architecture.md](docs/architecture.md)
- **Schema principles**: [schema/README.md](schema/README.md) — Stable Seeding Meta-Language, Turing Tape Analogy, and the Unification Thesis.
- **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)
- Monad–Polynomial philosophy: [docs/architecture/Monadic_Duality.md](docs/architecture/Monadic_Duality.md)
- Narrative roadmap & chapters: [docs/Narrative_Roadmap.md](docs/Narrative_Roadmap.md)
- Logging system: [docs/LOGGING_GUIDE.md](docs/LOGGING_GUIDE.md)
- PTR & CLM reference: [docs/CLM_Language_Specification.md](docs/CLM_Language_Specification.md), [docs/PCard%20Architecture.md](docs/PCard%20Architecture.md)
- Reports & execution summaries: [docs/reports/](docs/reports/)
- Publishing guide: [docs/PUBLISHING_GUIDE.md](docs/PUBLISHING_GUIDE.md)

---

---

## Platform Vision (December 2025): The Function Economy

Recent theoretical advancements have crystallized the MCard platform into a **universal substrate for the Function Economy**.

### 1. Vau Calculi Foundation: The MVP Card Database as Function Catalog
Using insights from **John Shutt's Vau Calculi**, PCard treats functions as **first-class operatives** cataloged in the MVP Card database.
- **Identity**: Unique SHA-256 hash
- **Naming**: Mutable handles in `handle_registry`
- **Versioning**: Immutable history in `handle_history`

### 2. Symmetric Monoidal Category: Universal Tooling
All DSL runtimes are isomorphic to **Petri Nets** and **Symmetric Monoidal Categories (SMC)**. The **Symmetry Axiom** ($A \otimes B \cong B \otimes A$) guarantees that **one set of tools works for all applications**:
- **O(1) Toolchain**: One debugger, one profiler, one verifier for *all* domains (Finance, Law, Code).
- **Universal Interoperability**: Any CLM can call any other CLM regardless of the underlying runtime (Python, JS, Rust, etc.).

### 3. PKC as Function Engineering Platform
MCard hashes act as **Internet-native URLs for executable functions**.
- **Publish**: Alice (Singapore) creates a function → `sha256:abc...`
- **Resolve**: Bob (New York) resolves `sha256:abc...` → Guaranteed identical function
- **Verify**: Charlie (London) executes with VCard authorization
- **Result**: **$\text{PKC} = \text{GitHub for Executable Functions}$**

> **See Also**:
> - [CLM_Language_Specification.md](docs/CLM_Language_Specification.md) — Comprehensive theory
> - [Cubical Logic Model.md](docs/WorkingNotes/Hub/Tech/Cubical%20Logic%20Model.md) — Mathematical foundations
> - [PCard.md](docs/WorkingNotes/Permanent/Projects/PKC%20Kernel/PCard.md) — Operative/Applicative duality

---

## Recent Updates

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

### Latest Version: 0.1.49 / 2.1.30 — January 20, 2026

Please refer to the changelog for details on recent updates including:
- **MCard Studio UI Refinement**: Implemented comprehensive Dark/Light theme switching with persistent state. Refactored entire UI codebase to use semantic CSS variables for consistent styling across all components and renderers (CLM, Markdown, Calendar).
- **Dependency Management**: Standardized on `uv` as the sole Python dependency manager (`pyproject.toml` + `uv.lock`). Removed legacy `requirements.txt`, `requirements-dev.txt`, and `setup.py`.
- **Binary Compilation**: Removed pre-compiled binaries (`chapters/chapter_01_arithmetic/bin/`) to support local compilation for multi-architecture compatibility (MacOS ARM64 / Linux x86-64).
- **Bug Fix**: Fixed `search_by_string()` to properly search within BLOB content using `CAST(content AS TEXT)`.
- **Directory Alignment**: `mcard-js` structure now mirrors Python (`src/model/hash`, `src/model/validators`, root utils).
- **Store Refactoring**: `MCardStore` aligns strictly with SQL schema (v8).
- **Refactoring**: Extracted server operations to `services.py` and reorganized CLMs into `system/services/`.
- **Configuration**: Parameterized CLM ports using environment variables (`.env`).
- **Fixes**: CSV detection, CLM Loader imports, and WebSocket Server builtins.

## 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**.

#### Python

```bash
# Run all CLMs
uv run python scripts/run_clms.py

# Run by directory
uv run python scripts/run_clms.py chapters/chapter_01_arithmetic
uv run python scripts/run_clms.py chapters/chapter_08_P2P

# Run single file
uv run python scripts/run_clms.py chapters/chapter_01_arithmetic/addition.yaml

# Run with custom context
uv run python scripts/run_clms.py chapters/chapter_08_P2P/generic_session.yaml \
    --context '{"sessionId": "my-session"}'
```

#### JavaScript

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

# Run by directory/filter
npm --prefix mcard-js run clm:all -- chapter_01_arithmetic
npm --prefix mcard-js run clm:all -- chapters/chapter_08_P2P

# Run single file
npm --prefix mcard-js run demo:clm -- chapters/chapter_01_arithmetic/addition_js.yaml
```

### Chapter Directories

| Directory | Description |
|-----------|-------------|
| `chapter_00_prologue` | Hello World, Lambda calculus, and Church encoding — 11 CLMs |
| `chapter_01_arithmetic` | Arithmetic operations (Python, JS, Lean) — 27 CLMs |
| `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 |

---

## Contributing
1. Fork the repository and create a feature branch.
2. Run the tests (`uv run pytest`, `npm test` in `mcard-js`).
3. Submit a pull request describing your change and tests.

We follow the BMAD (Red/Green/Refactor) loop – see [BMAD_GUIDE.md](BMAD_GUIDE.md).

---

## Future Roadmap

### Road to VCard (Design & Implementation)

Based on the **MVP Cards Design Rationale**, 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:**
- [ ] **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.
- [ ] **CLI Auth**: Update `run_clms.py` to accept `--auth <vcard_hash>` and mount the private keystore.
- [ ] **Certificate Generation**: Implement the `VerificationVCard` schema and generation logic in `CLMRunner`.

---

### 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).