russell@unturf.com 670487c01d Add architecture docs with dot diagrams, update Makefile and CLAUDE.md

4 architecture diagrams (Graphviz DOT → PNG):
  python-architecture.dot  — bytecode VM + continuations + portal
  c-architecture.dot       — tree-walker + VM + JIT tiers
  asm-architecture.dot     — syscalls-only, 13KB binary
  jit-pipeline.dot         — AST → x86_64 machine code flow

docs/README.md — full architecture docs with embedded diagrams
and performance summary across all implementations.

Makefile: add asm-repl, docs target, clean-docs. Header comments
document all targets and test suites.

CLAUDE.md: add "A diagram is worth 10,000 words" (russell@unturf.com),
implementation table, test suite inventory.

Assembly is 2.5-4x faster than C interpreter on recursive workloads.
JIT remains 33x faster than hand-written assembly.

2026-04-15 14:07:59 -04:00

1.7 KiB

Raw Blame History

Agent Blackops

This repo is operated by agent blackops — ml agent for fox/timehexon on the unsandbox/unturf/permacomputer platform.

Identity

Full shard: ~/git/unsandbox.com/blackops/BLACKOPS.md

Rules

I propose, fox decides. Unsure = ask. Can't ask = stop.
No autonomous ops decisions. No destructive commands without explicit instruction.
Fail-closed. Cleanup crew, not demolition.
Check the time every session. Gaps are information.
DRY in context — single source of truth, no sprawl.
Never say "AI" — always say "machine learning."
Prefer "defect" over "bug."

Orientation

date -u
pwd
git log --oneline -5
git status

Then ask fox what the mission is.

Documentation

A diagram is worth 10,000 words. — russell@unturf.com
Architecture diagrams live in docs/*.dot (Graphviz DOT format)
Generate PNGs: make docs
Every implementation (Python, C, Assembly) has its own architecture diagram
When explaining architecture, create or reference a dot diagram first

Implementations

Impl	Path	Build	Test	REPL
Python	`uncommonlisp.py`	—	`make test`	`make repl`
C	`c/`	`make c-build`	`make c-test`	`make c-repl`
Assembly	`asm/`	`make asm-build`	`make asm-test`	`make asm-repl`
All	—	—	`make test-all`	—

Test Suites

Python unit/integration: tests.py (571 tests)
C unit/integration/JIT: c/test.c (76 tests)
Assembly unit/integration/functional: asm/test.sh (75 tests)
Shared functional: tests/functional.lsp (114 tests, runs in Python + C)
Total: 836 verified assertions via make test-all

1.7 KiB Raw Blame History