ZIL: Lean4-Based Relational Language for AI-Assisted Code Projects

ZIL is a relational language embedded in Lean 4 that lets developers record and query the relationships between code declarations, requirements, documents, tests, and tasks. A relation is expressed as a subject–relation–object tuple—for example, `lean.Parser.parse ── implements ──▶ requirement.parseInput`—following the model described in Google's Zanzibar paper on authorization systems.

The language supports both facts and rules. Facts are directly registered; for example, `zil_fact node(lean.Parser.parse) ⟶[implements] node(requirement.parseInput)` records that a parser function implements a specific requirement. Rules use Horn-style logic to derive new relations. A rule might say: if a user belongs to a group, and that group can view a document, then the user can view the document. In project contexts, rules can propagate change impact—if module A depends on module B and module B changes, a rule can infer that A's dependents should be reviewed.

A ZIL project stores relationships alongside source code using Lean environment extensions. Developers can then write queries to ask: which declaration implements a given requirement? Which theorems validate a specific component? Which modules depend on a changed file? Which tasks are blocked by an open issue? The same query engine serves developers inspecting code, reviewers assessing change scope, documentation tools, CI systems, and AI assistants trying to understand project structure.

The system supports three trust levels for relationships. Asserted relations are facts directly registered by the developer. GraphDerived relations are inferred by rule application. Certified relations are backed by a Lean proposition and proof term, linking a relationship to a verified property. Each inferred relation can also record the input facts, rule name, and variable bindings, so tools and developers can trace how a relationship was derived.

For persistence and interoperability, ZIL stores facts, rules, schemas, and contracts in the Lean compilation pipeline. When a project is compiled, these entries are captured in .olean files. Tools can then exchange project maps using ZILX/1 snapshots and ZILD/1 deltas, enabling separate systems to work with the same relationship database. The system also supports contracts—records of required declarations, required relations, advertised scope, and completion state—so maintainers and tools share a common description of what a file or task should deliver. The quick start guide points users to six progressive examples (01–06) and a Makefile to run them, making it straightforward to experiment with facts, rules, typed rules, multi-step queries, imported knowledge, and project verification arcs.

ZIL addresses a practical gap in code project organization: connecting code declarations to the requirements, documents, and tasks they serve. By adapting Google's Zanzibar tuple model—designed for authorization systems—to software development, the project creates a bridge between what developers, tools, and AI assistants need to know about a codebase. The relationship model is simple (subject–relation–object) but expressive enough to handle both structural facts (which module depends on which declaration) and derived insights (which components are affected by a change).

The integration with Lean 4 is strategic. Lean already verifies code correctness; ZIL adds a layer of project-wide context that Lean does not track. By storing relationships as Lean environment extensions, ZIL ensures they persist with compiled code and are accessible to any tool that imports the project. This design allows AI assistants, documentation generators, and CI tools to reason about not just whether code is correct, but why it exists and what it connects to.

No comments yet. Be the first to share your thoughts!