mcard 0.1.52

MCard: Local-first Content Addressable Storage with Content Type Detection

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. Architectural philosophy is captured in docs/architecture/Monadic_Duality.md.

---

Quick Start (Python)

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 as the sole Python dependency manager. All dependencies are defined in pyproject.toml and locked in uv.lock.

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

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 for build, testing, and npm publishing instructions for the TypeScript implementation.

• mcard-studio: The interactive PWA IDE — see mcard-studio/README.md for setup and architecture.

Quick Start (Quantum NLP)

MCard optionally integrates with lambeq for quantum natural language processing using pregroup grammar:

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

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

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 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/            # >800 automated tests (Python)
└── 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.
• Key Features: Serverless P2P mesh networking, zero-dependency architecture (runs locally without build steps), and rich markdown/media rendering.
• Role: The "Viewer" & "distributable container" for the Personal Knowledge Container (PKC) concept.

---

Documentation

• Product requirements: docs/prd.md
• Architecture overview: docs/architecture.md
• Schema principles: schema/README.md — Empty Schema grounding, verification-first storage, and the core/extension split.
• mcard-js schema reference: 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
• Monad–Polynomial philosophy: docs/architecture/Monadic_Duality.md
• Narrative roadmap & chapters: docs/Narrative_Roadmap.md
• Logging system: docs/LOGGING_GUIDE.md
• PTR & CLM reference: docs/CLM_Language_Specification.md, docs/PCard%20Architecture.md
• Reports & execution summaries: docs/reports/
• Publishing guide: 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 — Comprehensive theory
• Cubical Logic Model.md — Mathematical foundations
• PCard.md — Operative/Applicative duality

---

Recent Updates

Full changelog: CHANGELOG.md

Latest Version: 0.1.52 / 2.1.34 — March 12, 2026

Python (mcard 0.1.52)

• PTR Exception Handling Refinement: Narrowed ~109 broad except Exception blocks across 33 PTR files to specific exception types (yaml.YAMLError, ValueError, TypeError, KeyError, OSError, subprocess.SubprocessError, json.JSONDecodeError, ConnectionError, RecursionError, etc.). 14 intentional broad catches preserved as safety nets.
• Test Results: 221 PTR tests passed, 0 regressions.

TypeScript (mcard-js 2.1.34)

• SqlJsVectorAdapter: Replaced the stub with a fully working sql.js adapter for browser-based vector search. Translates VectorDbStatement methods (run/all/get) into sql.js's prepare → bind → step → getAsObject → free pattern. Includes lastInsertRowid and changes extraction.
• New Tests: 7 integration tests covering DDL, INSERT, SELECT, COUNT, end-to-end createWasmVectorStore, and extension loading.
• Test Results: 821 passed, 23 skipped, 0 failures (52 test files).

Previous: 0.1.51 / 2.1.33 — March 12, 2026

• LLM Runtime Fix: Fixed _extract_prompt not passing test-case context variables to the LLM.
• SQLite Engine Refactor: Decoupled setup_database from connect; added context manager to SQLiteEngine.
• StorageEngine Interchangeability: 162-test cross-engine suite for 3 engines.
• Security: Eliminated SQL injection in SqliteWasmEngine.
• Code Quality: rowToCard() helper, createPage() factory, explicit : any cleanup.

Previous: 0.1.49 / 2.1.30 — January 20, 2026

• 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

# 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

# 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

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

---

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.

For release notes, check CHANGELOG.md.