lemmascript-guard

Compile verified preconditions into live TypeScript boundaries.

LemmaScript proves a function correct only when its //@ requires clauses hold. lemmascript-guard generates a sibling *.guarded.ts module that checks those same clauses at runtime before delegating to the verified implementation. A caller can no longer silently invoke the theorem outside the domain where it applies.

The generated module also exports can.* previews for expected unavailable states and a structured PreconditionError for rejected calls. Generation fails loudly if any clause cannot be enforced—there is no silent true and no partially guarded success.

Read TUTORIAL.md for a guided example and DESIGN_RUNTIME_CONTRACTS.md for the lowering and trust model.

Install

Requires Node.js 22 or newer and LemmaScript 0.6.x.

npm install --save-dev lemmascript lemmascript-guard

Generate a guard next to one verified core:

npx lemmascript-guard src/quota.ts
# → src/quota.guarded.ts

There is one executable: lemmascript-guard.

Example

// quota.ts
export interface Quota {
  remaining: number
}

export function valid(q: Quota): boolean {
  return q.remaining >= 0
}

export function spend(q: Quota, cost: number): Quota {
  //@ requires valid(q)
  //@ requires cost >= 0
  //@ requires cost <= q.remaining
  return { remaining: q.remaining - cost }
}

Use operational values from the generated boundary and types from the source:

import type { Quota } from "./quota.js"
import { spend, can, PreconditionError } from "./quota.guarded.js"

const quota: Quota = { remaining: 5 }

can.spend(quota, 7)       // false: useful for rendering availability
spend(quota, 3)           // { remaining: 2 }
spend(quota, 7)           // throws PreconditionError for spend#2

can.spend is a preview, not enforcement. Code that performs the operation must still call spend; the wrapper checks again at the authority boundary.

Generated behavior

For each exported function present in LemmaScript's extracted verified surface, the generated module:

• evaluates requires clauses in source order;
• stops at the first failed clause;
• throws PreconditionError without calling the core;
• delegates exactly once when every clause holds; and
• exposes the same check path as can.functionName(...).

An error contains fn, clause, deterministic positional clauseId, args, and detail. args and detail are non-enumerable so default error inspection does not print them, but direct access still exposes application inputs and must be treated as sensitive. A positional ID such as spend#2 is stable for unchanged clause order; inserting or reordering clauses changes it.

Generated files are ordinary TypeScript and should be committed. Runtime code imports the generated boundary; internal core-to-core calls remain raw and are covered by the proof.

Supported contract fragment

The 0.1 generator lowers:

• comparisons, arithmetic, booleans, implication, and equivalence;
• field access, array indexing, .length, conditionals, and array literals;
• calls to runtime-reachable same-module exports or value imports;
• bounded forall scans with an implication-shaped range antecedent;
• in membership over arrays, sets, maps, and object keys; and
• the perm multiset-equality builtin.

It reconstructs simple, destructured, default, and rest parameters from the original TypeScript signature. Version 0.1 rejects generic exported functions with a nonzero exit rather than emitting a wrapper that erases their type relationship.

Generation exits nonzero and writes an // UNENFORCED marker when a clause names a ghost-only or otherwise unreachable symbol, uses an unbounded quantifier, or contains an unsupported expression. Do not use the emitted file from a failed generation.

CI and drift

For one core:

npx lemmascript-guard src/quota.ts
git diff --exit-code -- src/quota.guarded.ts

For a LemmaScript project with LemmaScript-files.txt, mark guarded sources with //@ guarded and run the packaged sweep:

./node_modules/lemmascript-guard/check-guarded.sh
git diff --exit-code -- '*.guarded.ts'

The command itself fails on every UNENFORCED clause. The Git diff then proves the committed runtime boundary was generated from the current contracts.

Flagship case study

midspiral/toolgate-lemmascript uses the guard as the admission boundary immediately before effectful agent tools. A verified state transition establishes fresh call IDs, per-tool limits, and total budget; the generated guard ensures an untrusted dispatcher can only enter that transition under its proven preconditions.

ToolGate is intentionally larger than the tutorial: it demonstrates state custody, pre-spend before await, safe rejection mapping, hostile call streams, and CI drift enforcement.

Honest boundary

lemmascript-guard enforces semantic preconditions for well-typed TypeScript calls. It is not structural input validation, a sandbox, an authorization system, or a proof of external effects. Decode untrusted bytes before the guard, keep effectful operations reachable only through the guarded boundary, and keep runtime helper predicates pure.

The trusted base includes LemmaScript extraction and parsing, this generator, JavaScript evaluation semantics for the supported fragment, the original core, and the application's import discipline.

Development

npm install
npm run check
npm run test:package

To exercise a local LemmaScript checkout, build it first and override resolution:

LEMMASCRIPT=../LemmaScript node dist/guard.js path/to/core.ts

License

MIT