typed surface

Small contracts.
Clear seams.

The public API is organized around validated data models and replaceable protocols. Choose the implementation that fits your host without changing the domain flow.

Core contracts

ProceduralGraphAgentStateSolverLLMClientRepositoryEvolutionRunner

ProceduralGraph owns graph data and invariants. Solver and LLMClient are structural protocols, so tests and hosts can provide their own implementations. Repository separates durable state from graph operations.

Adapter lifecycle

1. Match the last action to a graph node.
2. Extract the bounded neighborhood and trajectory window.
3. Resolve cached guidance through the injected LLM contract.
4. Pass an updated AgentState to the host solver.

Persistence choices

SQLitePostgresFilesystem (development)sqlite-vec (optional)

SQLite provides WAL-backed local durability and atomic compare-and-swap. Postgres provides pooled transactions and the shared state needed for horizontal service replicas. Filesystem persistence is intentionally development-only.

REST endpoints

GET  /health
GET  /ready
GET  /metrics
GET  /v1/graphs/{id}
POST /v1/graphs
PUT  /v1/graphs/{id}                 If-Match: revision
POST /v1/graphs/{id}/guidance
POST /v1/graphs/{id}/evolve           Idempotency-Key: key
GET  /v1/evolution/jobs/{job_id}
POST /v1/graphs/{id}/snapshot/{tag}   operator role
POST /v1/graphs/{id}/rollback/{tag}   operator role

Errors and concurrency

Errors use a stable envelope with a code and request ID. Graph writes require an If-Match revision token and return a conflict instead of silently overwriting a newer revision. Request bodies, identifiers, retries, and provider output are bounded.