Curate-Ipsum — Progress Log¶

Last updated: 2026-02-09

Project Goal¶

Curate-ipsum is a mutation testing orchestration MCP server that bridges LLM-generated code and formally verified patches. It uses graph-spectral decomposition, belief revision (AGM theory), and a CEGIS/CEGAR synthesis loop to transform mutation testing from a quality metric into the foundation of a verified code synthesis pipeline.

Primary Environment¶

Python 3.11+ on any POSIX-compatible system
Dependencies: py-brs>=2.0.0, pydantic>=2.0, mcp>=1.0.0
Optional: scipy>=1.10, networkx>=3.0 (graph extras), z3-solver, sympy (Phase 5+)

Companion Repositories¶

py-brs (github.com/egoughnour/brs, PyPI: py-brs): AGM-compliant belief revision library. v2.0.0 released with contraction + entrenchment. Import as brs.
curate-ipsum (github.com/egoughnour/curate-ipsum): This repository.

Architecture Overview¶

┌──────────────────────────────────────────────────────────┐
│                      MCP Interface                       │
│                  (42 tools registered)                    │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐         │
│  │  Mutation   │  │  Graph     │  │  Symbolic  │         │
│  │  Parsers    │  │  Spectral  │  │  Execution │         │
│  │  (M1 ✓)    │  │  (M2 ✓)   │  │  (Phase 6) │         │
│  └──────┬─────┘  └──────┬─────┘  └──────┬─────┘         │
│         │               │               │                │
│         ▼               ▼               ▼                │
│  ┌───────────────────────────────────────────────┐       │
│  │         Belief Revision Engine (Phase 4)      │       │
│  │         py-brs: AGM theory, entrenchment      │       │
│  └───────────────────┬───────────────────────────┘       │
│                      │                                   │
│                      ▼                                   │
│  ┌───────────────────────────────────────────────┐       │
│  │         Synthesis Loop (Phase 5)              │       │
│  │         CEGIS + CEGAR + Genetic Algorithm     │       │
│  └───────────────────────────────────────────────┘       │
│                                                          │
└──────────────────────────────────────────────────────────┘

Full vision: architectural_vision.md. Decisions: DECISIONS.md.

Current Status¶

M1: Multi-Framework Foundation ✓ (Complete)¶

AMENDED 2026-02-08: All 5 mutation framework parsers implemented. M1 exit criteria met: “Run any Python mutation tool through single MCP interface.”

Item	Status	File(s)	Notes
MCP server infrastructure	✓	`server.py`	FastMCP-based, 35 tools
Stryker report parsing	✓	`parsers/stryker_parser.py`	JavaScript mutation tool
mutmut parser	✓	`parsers/mutmut_parser.py`	Python mutation tool (SQLite cache)
Run history + PID metrics	✓	`tools.py`	Precision/completeness tracking
Flexible region model	✓	`regions/models.py`	Hierarchical: file → class → func → lines
Framework auto-detection	✓	`parsers/detection.py`	Language + tool detection
Unified parser interface	✓	`parsers/__init__.py`	Routes to correct parser
cosmic-ray parser	✓	`parsers/cosmic_ray_parser.py`	JSON dump + SQLite session DB
poodle parser	✓	`parsers/poodle_parser.py`	JSON mutation-testing-report-schema
universalmutator parser	✓	`parsers/universalmutator_parser.py`	Plain text killed.txt / not-killed.txt

M2: Graph-Spectral Infrastructure ✓ (Complete)¶

AMENDED 2026-02-08: All 9 steps from PHASE2_PLAN.md implemented. 195 tests passing. Committed as d34b411.

Item	Status	File(s)	Notes
Graph models (CallGraph, Node, Edge)	✓	`graph/models.py`	Backend-agnostic, serializable
Call graph extraction (AST)	✓	`graph/ast_extractor.py`	Two-pass: definitions → calls
ASR extractor (LPython)	✓	`graph/asr_extractor.py`	Optional, requires LPython
Tarjan SCC detection	✓	`graph/models.py`	`strongly_connected_components()`
Graph condensation (DAG of SCCs)	✓	`graph/models.py`	`condensation()` method
BFS reachability	✓	`graph/models.py`	`reachable_from()`, `reaches()`
Topological sort	✓	`graph/models.py`	For DAG ordering
DOT export	✓	`graph/models.py`	Graphviz visualization
Dependency graph extraction	✓	`graph/dependency_extractor.py`	Module-level import graphs
Laplacian construction	✓	`graph/spectral.py`	Sparse L = D − A, symmetrized
Fiedler vector computation	✓	`graph/spectral.py`	`eigsh` + dense fallback `→ D-003`
Recursive partitioning	✓	`graph/partitioner.py`	Binary tree of Fiedler bipartitions
Virtual sink/source augmentation	✓	`graph/partitioner.py`	`augment_partition()` `→ D-008`
Hierarchical SCC condensation	✓	`graph/hierarchy.py`	Alternating condense/partition `→ D-005`
Planar subgraph identification	✓	`graph/planarity.py`	Boyer-Myrvold + Kuratowski `→ D-006`
Kameda O(1) reachability	✓	`graph/kameda.py`	2D dominance labels + BFS fallback
MCP tools for graph queries	✓	`server.py`	5 tools: extract, partition, reach, hierarchy, find

M3: Belief Revision Engine ✓ (Complete)¶

AMENDED 2026-02-08: All M3 items implemented. Exit criteria met: “Track belief evolution across synthesis attempts with full provenance.” 32 MCP tools total (8 new M3 tools)

Item	Status	File(s)	Notes
py-brs library (AGM core)	✓	PyPI `py-brs`	v2.0.0 released
Evidence adapter (mutation→belief)	✓	`adapters/evidence_adapter.py`	Mutation results → BRS Evidence
Theory manager	✓	`theory/manager.py`	High-level API, provenance wired
AGM contraction	✓	In py-brs v2.0.0	3 strategies: entrenchment, minimal, full_cascade
Entrenchment calculation	✓	In py-brs v2.0.0	`compute_entrenchment()`
Typed assertion model	✓	`theory/assertions.py`	6 kinds + contradiction detection → D-010
Provenance DAG	✓	`theory/provenance.py`	Append-only causal chain → D-010
Rollback mechanism	✓	`theory/rollback.py`	Checkpoints + undo via provenance DAG
Failure mode analyzer	✓	`theory/failure_analyzer.py`	7 failure modes, heuristic classification → D-011
MCP tools (8 new)	✓	`server.py`	store_evidence, provenance, why_believe, stability, rollback, undo, analyze_failure, world_history

M4: Synthesis Loop ✓ (Complete)¶

AMENDED 2026-02-08: All M4 items implemented. Exit criteria met: “Generate patch that kills previously-surviving mutant, verified correct.”

Item	Status	File(s)	Notes
Synthesis data models	✓	`synthesis/models.py`	Individual, CodePatch, Specification, Counterexample, SynthesisResult
Abstract LLM client	✓	`synthesis/llm_client.py`	ABC + MockLLMClient + prompt builder
Cloud LLM backend	✓	`synthesis/cloud_llm.py`	Anthropic + OpenAI via httpx → D-012
Local LLM backend	✓	`synthesis/local_llm.py`	Ollama HTTP API → D-012
Population management	✓	`synthesis/population.py`	Elite/tournament selection, add/remove
Fitness evaluation	✓	`synthesis/fitness.py`	CE avoidance + spec satisfaction - complexity → D-013
AST-aware crossover	✓	`synthesis/ast_operators.py`	Subtree swap, directed mutation
Entropy manager	✓	`synthesis/entropy.py`	Shannon entropy, diversity injection
CEGIS engine	✓	`synthesis/cegis.py`	Full loop: LLM → GA → verify → CE feedback
MCP tools (4 new)	✓	`server.py`	synthesize_patch, synthesis_status, cancel_synthesis, list_synthesis_runs

M6: Graph Persistence + RAG (Complete)¶

AMENDED 2026-02-09: Graph persistence + RAG layer fully implemented. 70+ new tests, 42 MCP tools total. Storage package with SQLite (primary) + Kuzu (optional) backends, incremental update engine, synthesis persistence, vector store ABC with ChromaDB, and RAG pipeline.

Item	Status	File(s)	Notes
Abstract GraphStore ABC	✓	`storage/graph_store.py`	Factory pattern mirrors D-012 → D-014
SQLite graph store (primary)	✓	`storage/sqlite_graph_store.py`	7 tables, WAL mode, zero deps
Kuzu graph store (optional)	✓	`storage/kuzu_graph_store.py`	Cypher queries, embedded graph DB
Synthesis result persistence	✓	`storage/synthesis_store.py`	JSONL append-only, multi-project
Kameda index persistence	✓	`storage/sqlite_graph_store.py`	O(1) reachability survives restart
Fiedler partition persistence	✓	`storage/sqlite_graph_store.py`	Materialized path encoding
Incremental update engine	✓	`storage/incremental.py`	SHA-256 file hashing → D-015
MCP tools (3 new)	✓	`server.py`	incremental_update, persistent_graph_stats, graph_query
Server wiring	✓	`server.py`	extract_call_graph, compute_partitioning, synthesize_patch persist automatically
Code embedding model	✓	`rag/embedding_provider.py`	sentence-transformers (all-MiniLM-L6-v2, 384-dim)
Vector store ABC	✓	`rag/vector_store.py`	Abstract interface → D-017
ChromaDB backend	✓	`rag/chroma_vector_store.py`	Embedded + HTTP client modes
RAG pipeline	✓	`rag/search.py`	Vector top-k + graph expansion decay
CEGIS + RAG integration	✓	`synthesis/cegis.py`	Optional `rag_pipeline` parameter
MCP tools (3 new)	✓	`server.py`	store_code_embeddings, rag_search, retrieve_context

Phases 5, 7–8: Not Started¶

Verification Backends, Production Hardening. See ROADMAP.md for details.

What’s Next¶

RAG + Embeddings (M6 Follow-Up)¶

Exit criteria: Natural language queries over codebase with graph-backed retrieval.

Key tasks: Code embedding model, vector index, semantic search, text-to-Cypher pipeline.

M5: Verification Backends¶

Exit criteria: Verify patch correctness against specification with proof certificate.

Key tasks: Z3 integration, CEGAR abstraction levels, SymPy path conditions, KLEE container. See ROADMAP.md for details.

Known Limitations & Open Questions¶

LPython optional: ASR extractor requires LPython which is alpha-status. AST extractor is always available. See docs/lpython_klee_feasibility.md. → D-001
~~Fiedler on disconnected graphs: Need to handle disconnected components separately.~~ Resolved in graph/spectral.py via per-component Fiedler. → D-004
~~Planarity NP-hard: Maximal planar subgraph identification is NP-hard in general.~~ Mitigated via iterative edge removal heuristic in graph/planarity.py. → D-006
~~scipy not yet in dependencies~~ Resolved: Added as [graph] optional dependency. → D-007

Test Suite Summary¶

Test File	Count	Covers
`tests/test_m1_regions.py`	25	Region model parsing, containment, overlap
`tests/test_m1_parsers.py`	25	Stryker + mutmut parsing, detection
`tests/test_new_parsers.py`	62	cosmic-ray, poodle, universalmutator parsers
`tests/test_graph_extraction.py`	26	AST extractor, call resolution
`tests/test_brs_integration.py`	15	BRS evidence adapter integration
`tests/test_spectral.py`	41	Laplacian, Fiedler, partitioner, virtual nodes
`tests/test_planarity_kameda.py`	54	Planarity, Kameda reachability, BFS verification
`tests/test_hierarchy_deps.py`	48	Hierarchy, dependency extractor, imports
`tests/test_mcp_graph.py`	26	MCP graph tools end-to-end pipeline
`tests/test_assertions.py`	38	Typed assertions, serialization, contradiction detection
`tests/test_provenance.py`	30	Provenance DAG, event recording, path queries
`tests/test_rollback.py`	12	Rollback, checkpoints, undo operations
`tests/test_failure_analyzer.py`	38	Failure classification, overfitting, contraction suggestions
`tests/test_m3_end_to_end.py`	9	M3 full lifecycle: evidence → assertion → provenance → rollback
`tests/test_synthesis_models.py`	28	Synthesis data models, config validation
`tests/test_llm_client.py`	18	Mock/cloud/local LLM clients, prompt building
`tests/test_genetic_operators.py`	27	Population, fitness, AST operators, entropy
`tests/test_cegis.py`	8	CEGIS engine, cancellation, timeout
`tests/test_m4_end_to_end.py`	11	M4 full pipeline end-to-end
`tests/test_synthesis_store.py`	10	Synthesis store JSONL persistence
`tests/test_sqlite_graph_store.py`	25	SQLite graph store round-trips, queries
`tests/test_kuzu_graph_store.py`	12	Kuzu graph store (skipped if kuzu not installed)
`tests/test_incremental.py`	15	Incremental update engine, change detection
`tests/test_m6_end_to_end.py`	7	M6 full pipeline: persist → query → update
Total	616 passed, 1 pre-existing failure, 1 skipped

File Inventory¶

curate-ipsum/
├── server.py              # MCP server entry point (35 tools)
├── tools.py               # Async test/mutation execution layer
├── models.py              # Pydantic data models (MutationRunResult, etc.)
├── config.toml            # Server configuration
├── pyproject.toml         # Package metadata + dependencies
├── graph/
│   ├── __init__.py        # Public API + optional dependency flags
│   ├── models.py          # CallGraph, GraphNode, GraphEdge, SCC, condensation
│   ├── extractor.py       # Abstract base class for extractors
│   ├── ast_extractor.py   # Python AST-based call graph extraction
│   ├── asr_extractor.py   # LPython ASR-based extraction (optional)
│   ├── dependency_extractor.py  # Module-level import graph extraction
│   ├── spectral.py        # Laplacian + Fiedler vector computation
│   ├── partitioner.py     # Recursive Fiedler partitioning + virtual nodes
│   ├── hierarchy.py       # Alternating condense/partition tree
│   ├── planarity.py       # Boyer-Myrvold planarity + Kuratowski
│   └── kameda.py          # O(1) reachability index (2D dominance)
├── parsers/
│   ├── __init__.py        # Unified parser interface (routes 5 frameworks)
│   ├── detection.py       # Framework + language auto-detection
│   ├── stryker_parser.py  # Stryker JSON report parser
│   ├── mutmut_parser.py   # mutmut SQLite cache parser
│   ├── cosmic_ray_parser.py   # cosmic-ray JSON dump + SQLite parser
│   ├── poodle_parser.py       # poodle JSON mutation-testing-report parser
│   └── universalmutator_parser.py  # universalmutator text file parser
├── regions/
│   └── models.py          # Region, RegionLevel (file/class/func/lines)
├── adapters/
│   └── evidence_adapter.py  # Mutation results → BRS beliefs
├── theory/
│   ├── __init__.py            # Package with submodule listing
│   ├── manager.py             # Theory manager (provenance + rollback wired)
│   ├── assertions.py          # Typed assertion model + contradiction detection
│   ├── provenance.py          # Append-only provenance DAG
│   ├── rollback.py            # Rollback manager + checkpoints
│   └── failure_analyzer.py    # Heuristic failure classification
├── synthesis/
│   ├── __init__.py            # Public API + optional dependency flag
│   ├── models.py              # Individual, CodePatch, Specification, SynthesisResult
│   ├── llm_client.py          # LLMClient ABC + MockLLMClient + prompt builder
│   ├── cloud_llm.py           # Cloud LLM (Anthropic/OpenAI) via httpx
│   ├── local_llm.py           # Local LLM (Ollama) via httpx
│   ├── population.py          # GA population management
│   ├── fitness.py             # Fitness evaluation (CE + spec - complexity)
│   ├── ast_operators.py       # AST crossover + directed mutation
│   ├── entropy.py             # Shannon entropy + diversity injection
│   └── cegis.py               # CEGIS engine (main synthesis loop)
├── storage/
│   ├── __init__.py            # Package init, exports
│   ├── synthesis_store.py     # JSONL persistence for synthesis results
│   ├── graph_store.py         # Abstract GraphStore ABC + factory → D-014
│   ├── sqlite_graph_store.py  # SQLite backend (primary, zero deps)
│   ├── kuzu_graph_store.py    # Kuzu backend (optional, Cypher queries)
│   └── incremental.py         # File hash tracking + delta updates → D-015
├── rag/
│   ├── __init__.py            # RAG package init
│   ├── embedding_provider.py  # EmbeddingProvider ABC + sentence-transformers → D-017
│   ├── vector_store.py        # VectorStore ABC + ChromaDB backend → D-017
│   ├── chroma_vector_store.py # ChromaDB implementation (embedded/HTTP)
│   └── search.py              # RAG pipeline (vector + graph expansion)
├── verification/
│   ├── __init__.py            # Verification package init
│   ├── backend.py             # VerificationBackend ABC → D-016
│   ├── backends/
│   │   ├── __init__.py
│   │   ├── z3_backend.py      # Z3 constraint solving backend
│   │   ├── angr_docker.py     # angr symbolic execution via Docker
│   │   └── mock_backend.py    # Mock verification for testing
│   └── orchestrator.py        # VerificationOrchestrator with CEGAR budget escalation → D-016
├── tests/
│   ├── test_m1_regions.py       # Region model tests
│   ├── test_m1_parsers.py       # Parser tests (Stryker + mutmut)
│   ├── test_new_parsers.py      # cosmic-ray, poodle, universalmutator tests
│   ├── test_graph_extraction.py # AST extractor tests
│   ├── test_brs_integration.py  # BRS integration tests
│   ├── test_assertions.py       # Typed assertions + contradiction detection
│   ├── test_provenance.py       # Provenance DAG tests
│   ├── test_rollback.py         # Rollback + checkpoint tests
│   ├── test_failure_analyzer.py # Failure classification tests
│   ├── test_m3_end_to_end.py    # M3 full lifecycle E2E
│   ├── test_spectral.py         # Laplacian/Fiedler/partitioner tests
│   ├── test_planarity_kameda.py # Planarity + Kameda tests
│   ├── test_hierarchy_deps.py   # Hierarchy + dependency tests
│   ├── test_mcp_graph.py        # MCP graph tool integration tests
│   ├── test_synthesis_models.py   # Synthesis data model tests
│   ├── test_llm_client.py        # LLM client tests
│   ├── test_genetic_operators.py  # GA operator tests
│   ├── test_cegis.py             # CEGIS engine tests
│   ├── test_m4_end_to_end.py     # M4 full pipeline E2E
│   ├── test_synthesis_store.py    # Synthesis JSONL store tests
│   ├── test_sqlite_graph_store.py # SQLite graph store tests
│   ├── test_kuzu_graph_store.py   # Kuzu graph store tests (skip if no kuzu)
│   ├── test_incremental.py        # Incremental update engine tests
│   ├── test_m6_end_to_end.py     # M6 full pipeline E2E
│   ├── test_embedding_provider.py # Embedding provider tests
│   ├── test_vector_store.py       # Vector store ABC + ChromaDB tests
│   ├── test_rag_pipeline.py       # RAG search + graph expansion tests
│   ├── test_verification_backend.py # Verification backend ABC tests
│   ├── test_z3_backend.py         # Z3 backend constraint solving tests
│   ├── test_angr_docker.py        # angr Docker backend tests
│   ├── test_verification_orchestrator.py # CEGAR orchestrator tests
│   └── test_m5_m6_complete.py     # M5 + M6 complete integration tests
├── docs/
│   ├── m1_m3_audit.md     # M1-M3 audit findings
│   └── lpython_klee_feasibility.md  # LPython/KLEE feasibility study
├── README.md              # Project overview + roadmap
├── ROADMAP.md             # Full milestone tracker (M1–M7)
├── CONTEXT.md             # Directory structure + naming conventions
├── DOCS_INDEX.md          # Documentation navigation guide
├── PROGRESS.md            # ← You are here
├── DECISIONS.md           # Architectural decision log (D-001 through D-015)
├── PHASE2_PLAN.md         # Phase 2 implementation plan (complete)
├── architectural_vision.md       # Graph-spectral framework theory
├── synthesis_framework.md        # CEGIS/CEGAR/genetic approach
├── belief_revision_framework.md  # AGM theory + provenance
├── m1_multi_framework_plan.md    # Phase 1 implementation plan (done)
├── brs_integration_plan.md       # BRS ↔ curate-ipsum mapping
├── brs_v2_refactoring_plan.md    # py-brs v2.0.0 plan
├── brs_contract_pr.md            # AGM contraction spec
├── brs_cicd.md                   # CI/CD pipeline docs
├── summary.md                    # Functionality catalog
├── potential_directions.md       # Enhancement ideas
├── synergies.md                  # Tool ecosystem integration
└── inferred_goals.md             # Evidence-based goal hierarchy

Revision History¶

v1.0 (2026-02-08): Initial PROGRESS.md created from comprehensive codebase audit. Phase 1 complete, Phase 2 active.
v2.0 (2026-02-08): Phase 2 (M2) complete — all 9 steps implemented (195 tests). M1 remaining parsers now active focus. Updated architecture diagram, file inventory, test summary, and known limitations.
v3.0 (2026-02-08): M1 ✅ complete (3 new parsers: cosmic-ray, poodle, universalmutator). M3 ✅ complete (assertions, provenance DAG, rollback, failure analyzer, 8 new MCP tools). 468 tests passing. Updated all inventories.
v4.0 (2026-02-08): M4 ✅ complete (synthesis loop: CEGIS + genetic algorithm + LLM client). 560 tests passing. 10 new synthesis files, 5 new test files, 4 new MCP tools.
v5.0 (2026-02-08): M6 🟡 partial (graph persistence: SQLite + Kuzu backends, incremental updates, synthesis persistence). 616 tests passing. 6 new storage files, 5 new test files, 3 new MCP tools (35 total). RAG deferred.
v6.0 (2026-02-09): M5 ✅ complete (verification backend ABC with Z3, angr Docker, mock backends + CEGAR orchestrator). M6 deferred RAG items ✅ complete (Chroma vector store, embedding provider, RAG pipeline, 7 new MCP tools). 700+ tests passing. 9 new verification files, 5 new RAG files, 10 new test files. 42 MCP tools total.