mcard 0.1.58

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.
• 🦆 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.
• 🔄 Shared MIME Registry: A single mime_extensions.json drives content-type detection across both Python and TypeScript — edit one file to update both runtimes, no recompilation needed.

For the long-form narrative and chapter roadmap, see docs/theory/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 scripts/clm/run_clms.py 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/            # >815 automated tests (Python)
├── 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.
• 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/specifications/prd.md
• Architecture overview: docs/architecture/overview.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/theory/Narrative_Roadmap.md
• Logging system: docs/guides/LOGGING_GUIDE.md
• PTR & CLM reference: docs/specifications/CLM_Language_Specification.md, docs/archive/PCard Architecture.md
• Reports & execution summaries: docs/reports/
  • WebSocket Performance Debugging
• Publishing guide: docs/guides/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

---

Concurrency Protection: The SSOT Boundary

⚠️ Critical Architectural Rule: External API calls (WebSocket, HTTP, database connections) must be funneled through a single-process SSOT boundary. Unprotected concurrent access to SQLite files causes OS-level spin-locks that destroy the availability and integrity of memory management.

The fundamental challenge of asynchronous computing is the leap from Additive to Multiplicative Complexity. Static data (like an MCard) grows additively — one hash per content blob. But timing, concurrency, and dynamic execution (e.g., two WebSocket connections racing to update SQLite) cause the state space to grow multiplicatively ($A \times B$), leading to combinatorial explosions that are practically uncomputable.

PTR (Polynomial Type Runtime) solves this by acting as a strict algebraic funnel. It operates as the Single Source of Truth (SSOT) runloop:

1. Intercepts all concurrent, multiplicative events (PCard execution, API calls, WebSocket messages)
2. Serializes them via Kleisli Composition — chaining effectful computations monadically
3. Collapses infinite temporal permutations back into an orderly, additive sequence of discrete MVP Card state transitions

This was empirically validated during the March 14, 2026 WebSocket debugging session: when the Astro SSR server and a standalone WebSocket server attempted to share servermemory.db, it resulted in bare-metal OS spin-locks. The resolution was merging both servers into a single Node.js process, where the event loop acts as the unified Dispatcher (Flux pattern).

In formal terms, the system follows a Mealy Machine model for reactive I/O: output depends on both current state and input, so concurrency at the I/O boundary must be strictly controlled to avoid non-deterministic outputs.

The Rule: The SSOT is the process boundary encompassing the database — not the database file itself. Any architecture that allows multiple uncoordinated processes to access the same SQLite file will eventually lock up.

---

Unified Memory Architecture: Two Types of Handles, One Schema

MCard_TDD implements a structurally coherent memory system using two types of handles, both stored in databases that conform to the same mcard_schema.sql three-table architecture (Card, Handle, Version):

Handle Type	Database	Role	Access Pattern
Content Handles	Xmemory.db (e.g., servermemory.db, browsermemory.db)	Working memory — public, domain-neutral	Read/write via PTR
Execution Handles	execution_logs.db	Event sourcing log — PCard/VCard pre/post pairs	Append-only via PTR

How It Works

• MCard is the memory — content-addressable, immutable, the Turing tape substrate.
• PCard/VCard pre/post pairs are always stored in execution_logs.db using the same schematic format, creating an append-only provenance chain.
• Promotion via PTR: Execution records from execution_logs.db can be pulled into Xmemory.db when needed — but only through the PTR engine using internally tested and authorized functions to ensure integrity.
• Because only one PTR engine instance needs to understand both handle types, complexity is minimized and the attack surface is reduced.

The Execution Log Triple

Every entry in execution_logs.db always contains exactly three records, forming an irreducible execution triple:

#	Entry	Points To	Content
1	Processing Resource	PCard (Concrete Implementation) hash	The hash of the CLM's concrete_impl — identifies which function was executed
2	VCard Precondition ($V_{pre}$)	Input values for this execution task	The actual input parameters, context variables, and enabling guards at the moment of firing
3	VCard Postcondition ($V_{post}$)	Output values or exit condition	On success: the final output values. On failure: the error/exit condition as the postcondition

This triple is atomic — if any of the three entries cannot be written (e.g., due to a crash during execution), the entire execution record is considered incomplete and must not be promoted to Xmemory.db.

Failure semantics: When execution fails, $V_{post}$ is still written — but its content captures the exit condition (error type, stack trace hash, diagnostic context) rather than the expected output. This ensures the provenance chain is never broken, and failed executions are auditable.

CLM as the Unifying Function Description Language

All three entries in the execution log triple are encoded in the syntax of the Cubical Logic Model (CLM), which serves as the unifying function description language across the entire system. A CLM specifies every function through three dimensions:

CLM Dimension	Role in Execution Log	Example
Abstract Specification (abstract_spec)	What the function promises — its goal, input types, and expected semantics	goal: "Add two integers", context: {a: int, b: int}
Concrete Implementations (concrete_impl, plural)	How the function is executed — the Processing Resource hash points to one of potentially multiple implementations (Python, JS, Lean, WASM)	runtime: python, code: "return a + b"
Balanced Expectations (balanced_exp)	Whether the function worked — the handle to the relevant execution logs/traces, linking each test case to its $V_{pre}/V_{post}$ pair in execution_logs.db	test_cases: [{when: {a: 10, b: 20}, then: {result: 30}}]

The Balanced Expectations dimension is the bridge between specification and execution evidence: each test case in balanced_exp corresponds to exactly one execution log triple, and the handle to that triple provides a verifiable link from the CLM source to the provenance chain in execution_logs.db. This makes execution traces navigable from the function description itself.

ContentTypeInterpreter: Polyglot Behavioral Consistency for Function Composition

In MCard_TDD, all things are treated as functions — and all functions have a dual representation:

• Statically as an MCard: the function's source, signature, and content are content-addressed and immutable
• Dynamically as a PCard: the function's execution logic, I/O behavior, and runtime effects

This duality means that content type detection is itself a function that must behave identically across all polyglot runtimes. The ContentTypeInterpreter (TypeScript) and its Python counterpart ContentTypeInterpreter must share the same algorithm profile and external interface/behavior — and any future implementations in Rust, C, WASM, Lean, R, or Julia must conform to this same contract.

Why This Matters for Function Composition

If ContentTypeInterpreter in Python classifies a content blob as application/json but the TypeScript version classifies the same bytes as text/plain, then:

1. Function composition breaks — a PCard pipeline that chains detect → parse → transform will produce different results depending on which runtime executes step 1
2. Handle promotion corrupts — content promoted from execution_logs.db to Xmemory.db may be misinterpreted by downstream consumers in a different runtime
3. Verification becomes non-portable — a VerificationVCard produced by Python PTR cannot be meaningfully replayed by JavaScript PTR if the content type differs

Because we treat ContentTypeInterpreter as a function (MCard for its algorithm, PCard for its execution), the same Petri Net composition rules apply: the output of one transition must be a valid input for the next, regardless of which polyglot runtime fires the transition.

The Shared Algorithm Profile

Interface Method	Python (interpreter.py)	TypeScript (ContentTypeInterpreter.ts)	Contract
detect(content)	detect_content_type(content) → (mime, ext)	detectContentType(content) → {mimeType, extension}	Same MIME for same bytes
register_extension(mime, ext)	register_extension(mime, ext)	registerExtension(mime, ext)	Same registry mutation
is_binary_content(content)	is_binary_content(content) → bool	isBinaryContent(content) → boolean	Same binary threshold
get_extension(mime)	get_extension(mime) → str	getExtension(mime) → string	Same extension mapping

All runtimes load their MIME type data and extension mappings from the single shared mime_extensions.json registry at the repo root — edit one file to update all runtimes.

Conformance Testing

• Python: 34 content-detection tests in tests/test_content_type_detection.py
• TypeScript: 11 content-detection tests in mcard-js/tests/ContentDetection.test.ts
• Cross-runtime parity: The same test vectors (binary signatures, UTF-8 heuristics, MIME mappings) should produce identical classifications in every runtime

Design Rule: Any new ContentTypeInterpreter implementation in a new language must pass the existing cross-runtime test vectors before it can participate in PTR function composition. A type mismatch between runtimes would silently corrupt the entire pipeline — the effects of content manipulation must be consistent to allow for maximum flexibility in function composition.

In DOTS vocabulary: Xmemory.db is the Carrier (data space), execution_logs.db is the Writer log (accumulated evidence), PTR Actions mediate the movement between them, and ContentTypeInterpreter is the Lens that ensures type-level compatibility across the Tight (structural) direction of the double category.

---

Petri Net Execution Scheduler

PTR internally schedules data updates as a Petri Net engine, where the Flux design pattern maps directly to token dynamics:

Petri Net Concept	MCard Implementation	Formal Role
Place	Handle in handle_registry	Named location in state space
Token	Card hash (current_hash)	Content-addressed value at a place
Transition	PCard (CLM specification)	Computable business logic
Firing Rule	PTR Dispatcher	Validates$V_{pre}$, executes Reducer, writes $V_{post}$
Marking	State of all handle_registry entries	Global system state

The Reducer/Writer Pipeline

Execution follows a Kleisli-composed pipeline of monadic operations:

1. Reader (Abstract/Spec): Injects the DSL specification as immutable context
2. Reducer (PCard): Pure function mapping input MCards → output MCards — the transition logic
3. Writer (VCard): Accumulates pre/post verification records — the audit trail in execution_logs.db
4. State (Succession): Updates the global marking ($M \to M'$) via handle_registry

These compose via Kleisli composition into macro-transitions (workflows), ensuring that trust is compositional.

PTR as Meta-Function (Abstract Interpreter)

Following Cousot's Calculational Design of Abstract Interpreters, PTR operates as a meta-function — it can execute and reflect upon all subordinate functions:

$$ \text{Verified Knowledge} = \lim_{n \to \infty} (\alpha_{\text{LLM}} \circ \gamma_{\text{Schema}})^n $$

• Widening ($\alpha$): LLM/semantic generation — produces candidate content
• Narrowing ($\gamma$): Hash-verified schema validation — grounds content against the three-table architecture
• Fixed-point iteration: PTR repeatedly applies $\alpha \circ \gamma$ until convergence

Mealy/Moore Duality

The system exhibits both Mealy and Moore Machine characteristics:

• Mealy (reactive): PCard execution output depends on both current state (MCard) and input context → models dynamic transitions
• Moore (state-driven): MCard output (the content hash) depends only on the content itself → models immutable storage

Together, these form a Petri Net with both input-dependent and state-dependent transitions, unified under the DOTS operadic framework.

Polynomial Type Boundaries

Each function's topological boundary is defined by its VCard pair:

$$ \text{Function Boundary} = (V_{pre}, V_{post}) $$

• $V_{pre}$: Precondition capabilities — the enabling guard on the Petri Net transition
• $V_{post}$: Postcondition verification trace — the certificate of execution
• The polynomial $F(C) = \sum_i (A_i \times C^{B_i})$ maps directly to CLM structure (Abstract × Concrete^Balanced)

These VCard boundaries ensure that each function is bounded, verifiable, and composable — the Polynomial Types cannot escape their topological constraints.

See Also:

• PTR Petri Net Execution Model — Formal mapping of Petri Nets to MVP Cards
• PTR Petri Net Scheduler Architecture — Detailed architecture document
• PTR Petri Net Implementation — Physical implementation mapping
• DOTS → PTR Meta-Language — Theoretical framework

---

Recent Updates

Full changelog: CHANGELOG.md

Current versions: Python mcard 0.1.58 · TypeScript mcard-js 2.1.39

Python Build & Syntax Corrections (v0.1.58 / v2.1.39): 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.57 / v2.1.39): 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 for full details.

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/clm/run_clms.py

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

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

# Run with custom context
uv run python scripts/clm/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_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

---

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.

---

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.