<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+" /></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**: 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](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
./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:
```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.

---

## 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](docs/prd.md)
- Architecture overview: [docs/architecture.md](docs/architecture.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/)

---

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

```bash
# 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](BMAD_GUIDE.md).

---

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

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