dag-typesafe

Deterministic type safety via directed acyclic graphs for reasoning language models.

Analyze any repo's public API surface, extract a typed node registry, compose validated execution DAGs from natural language, and compile them into native pipeline code with GraphSentry-style (artifact, certificate) verification at every node boundary.

Category

Code Scaffolding & Templates

Core Concepts

Three layers compose into a single architecture:

1. Typed Node Registry — the repo's public functions/classes extracted as typed nodes with JSON Schema input/output contracts. The LLM selects from this registry; it never generates arbitrary code.

2. DAG Plan — a language-neutral execution graph where nodes reference registry entries and edges are schema-validated. No cycles, all inputs satisfied, all types compatible.

3. Certificates — each node emits an (artifact, certificate) pair. Certificates are deterministic predicates evaluated from logged evidence. Failed certificates halt the pipeline with diagnostic context. Based on GraphSentry (Li et al., 2026).

Commands

Parse $ARGUMENTS to determine which command to run:

analyze

Extract a typed node registry from the current repository.

python3 ~/.claude/skills/dag-typesafe/scripts/analyze.py [--language python|typescript|auto] [--output dag-registry.json]

1. Detect repo language(s) from file extensions and config files
2. Run the appropriate extractor(s) from extractors/
3. Walk the AST for public API surface only (exported functions, public classes, API endpoints)
4. Convert type annotations to JSON Schema
5. Output dag-registry.json at repo root

compose

Generate a DAG plan from natural language using the typed registry.

The compose phase is endpoint-agnostic — it works with any OpenAI-compatible API (OpenRouter, Groq, Subq Code, local models) or in-session via Claude Code.

In-session mode (default): Build a structured prompt from the registry and task description, then use the current Claude Code session to generate the DAG plan.

Headless mode: Set DAG_LLM_BASE_URL and DAG_LLM_API_KEY environment variables to point at any OpenAI-compatible endpoint.

python3 ~/.claude/skills/dag-typesafe/scripts/compose.py "task description" --registry dag-registry.json [--output dag-plan.json] [--provider session|openai]

1. Load registry from dag-registry.json
2. Build structured prompt constraining LLM to node selection and parameterization
3. Generate DAG plan conforming to schemas/dag-plan.schema.json
4. Validate the plan (type compatibility, no cycles, all inputs satisfied)
5. Generate certificate predicates for each node
6. Output dag-plan.json

compile

Compile a validated DAG plan into native executable code.

python3 ~/.claude/skills/dag-typesafe/scripts/compile.py dag-plan.json [--target python|typescript] [--output pipeline.py]

1. Read validated dag-plan.json and dag-registry.json
2. Topologically sort nodes
3. Generate native pipeline code via inline code generation
4. Wrap each node call in schema validation (Pydantic .model_validate() / Zod .parse())
5. Inject certificate predicate evaluation at every node boundary
6. Output executable pipeline file with zero runtime dependencies beyond standard validation libs

validate

Type-check an existing DAG plan against a registry.

python3 ~/.claude/skills/dag-typesafe/scripts/validate.py dag-plan.json --registry dag-registry.json

Checks: cycle detection, edge type compatibility, required input satisfaction, certificate predicate well-formedness, registry reference integrity.

registry

Inspect, filter, and query the typed node registry.

python3 ~/.claude/skills/dag-typesafe/scripts/registry.py [--filter "pattern"] [--show-schemas] [--stats]

Schemas

All schemas live in schemas/ as JSON Schema (draft 2020-12):

• dag-plan.schema.json — DAG plan format (nodes, edges, metadata)
• registry.schema.json — typed node registry format
• certificate.schema.json — GraphSentry certificate format

Read these schemas before generating or validating any DAG artifacts.

Extractors

Language-specific type extractors in extractors/:

Extractor	Source Types	Output
python_extractor.py	Pydantic BaseModel, dataclass, TypedDict, function annotations	JSON Schema
typescript_extractor.py	Zod schemas, interfaces, type aliases, function signatures	JSON Schema

Each extractor walks the AST, identifies public API surface, and converts type definitions to JSON Schema for the registry. Internal/private symbols are excluded.

Code Generation

The compiler generates pipeline code inline (no external templates). Both Python and TypeScript targets produce complete executable files with:

• Certificate/CertificateError classes
• Topologically sorted node execution
• Per-node certificate emission and predicate evaluation
• Predicate expression sandboxing (AST-validated safe subset only)

LLM Provider Configuration

For headless/CI use, configure via environment variables:

export DAG_LLM_BASE_URL="https://openrouter.ai/api/v1"  # or Groq, Subq, local
export DAG_LLM_API_KEY="your-key"
export DAG_LLM_MODEL="anthropic/claude-sonnet-4-20250514"  # model identifier

When these are unset, compose mode generates a structured prompt for in-session use.

Research Basis

This skill synthesizes patterns from:

• GraphSentry (Li et al., 2026) — certificate-driven typed DAGs, contract-checked graph surgery
• ChopChop (Nagy et al., POPL 2026) — semantic constrained decoding via coinductive realizability
• PlanCompiler (prnvh, 2026) — LLM confined to typed node registry selection
• PlanAI (Provos, 2026) — Pydantic-typed DAG orchestration with automatic routing
• Agint (Chivukula et al., 2025) — type floors (text→data→spec→code) in agentic graph compilation

Full source list: references/research-sources.md