Skip to content

guardrail-calculus

A typed Python eDSL that builds a provenance-preserving intermediate representation of a workflow (or a logic puzzle), checks it with an SMT solver during analysis, and can explain every conclusion it reaches.

The solver is used at analysis time only — the long-term goal is to emit deterministic runtime guards that carry no solver dependency.

The layers

The package is split so the foundational substrate can be imported without executing the whole public DSL:

graph TD
    kernel["guardrail_kernel<br/><small>nodes · dimensions · expressions · dsl</small>"]
    dims["guardrail_calculus.dimensions<br/><small>Duration · ClockTime · TimePoint · TimeExpr</small>"]
    facts["guardrail_calculus.facts<br/><small>Prop · Check/Nil/Snoc · SubjectFacts</small>"]
    reasoning["guardrail_solver.reasoning<br/><small>FactGraph · solver · classify · solve_puzzle</small>"]
    public["guardrail_calculus<br/><small>re-exports + builder surface</small>"]

    kernel --> dims
    kernel --> facts
    dims --> facts
    kernel --> reasoning
    dims --> reasoning
    facts --> reasoning
    kernel --> public
    dims --> public
    facts --> public
    reasoning --> public
  • guardrail_kernel is import-safe: it never imports the public package at module load time. It holds the provenance nodes, the dimensional protocols, Predicate/SlotRef, and the local proxy _.
  • dimensions adds the concrete temporal values and the symbolic conditional.
  • facts adds propositions and the type-level chain of labelled checks.
  • reasoning is the explanation DAG, the solver utilities, the forward derivation rules, and puzzle solving.
  • guardrail_calculus itself is re-export plus the builder/authoring API.

See How reasoning works for the explanation graph and the classification model, and the API reference for the documented surface.

Status

The builder/authoring surface (agent / graph / subgraph) is still being shaped by Phases 2–3, so it is intentionally lightly documented here. The kernel, dimensions, facts, and reasoning layers are stable.