mcard 0.1.27

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: SHA-256 hashing, handle registry with history, immutable audit trail output.
• ♻️ 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).
• 🧰 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
./activate_venv.sh          # installs uv & dependencies
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

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.

---

Polyglot Runtime Matrix

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

---

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/            # >450 automated tests
└── requirements.txt / pyproject.toml

---

Documentation

• Product requirements: docs/prd.md
• Architecture overview: docs/architecture.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/

---

Recent Updates (December 2025)

CLM Test Infrastructure Improvements

• Execution Timing: Added timing logs to run-all-clms.ts to identify slow CLMs.
• Floating-Point Tolerance: Numeric comparisons now use configurable tolerance (1e-6) for floating-point precision.
• Input Context Handling: Introduced __input_content__ key to preserve original given values when merging when blocks.

Runtime Fixes

• JavaScript Runtime: Changed runtime: node to runtime: javascript across CLMs; updated code to use target variable.
• Python Input Parsing: All Python implementations now handle bytes, str, and dict inputs with robust parsing.
• Lambda Calculus: Fixed parser to correctly handle parenthesized applications like (\\x.x) y.
• Orchestrator: Fixed run_clm_background to strip file extensions for proper filter matching.

Chapter-Specific Fixes

• chapter_01_arithmetic: All 32 CLMs passing (Python, JavaScript, Lean, multi-runtime).
• chapter_03_llm: Replaced LLM-dependent logic with mock implementations for test stability.
• chapter_05_reflection: Fixed meta-interpreter and module syntax CLMs.
• chapter_06_lambda: Fixed beta reduction and Church numerals parsers.
• chapter_07_network: Updated expected outputs and runtime configurations.

---

Testing

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

# Python Suite
uv run pytest -q                 # Run all tests (~37s)
uv run pytest -q -m "not slow"   # Run fast tests only (~34s)
uv run pytest -m "not network"   # Skip tests requiring LLM/Ollama

# CLM Verification (Python)
uv run python scripts/run_all_clms.py

# JavaScript Suite
npm --prefix mcard-js test

# CLM Verification (JavaScript)
npm --prefix mcard-js run clm:all

---

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.

---

License

This project is licensed under the MIT License – see LICENSE.

For release notes, check CHANGELOG.md.