# valgebra-planning
> Plans of tool calls for agents, proven well-typed for every output the tool contracts admit.
Plans of tool calls for agents, proven well-typed for every output the tool contracts admit. A tool's MCP inputSchema and outputSchema are read by valgebra-jsonschema into valgebra's sets; a program of calls and type tests is accepted only where every value it passes on is proven inside the argument it fills. A program written elsewhere, by hand or by a language model, is verified the same way, link by link.
# Getting started
# valgebra-planning
**Plans of tool calls for agents, proven well-typed for every output the tool contracts admit.**
A plan is a program of calls and type tests on values, in the sense of strong planning under nondeterministic outcomes: it is accepted only where each value it passes to a tool is proven inside that tool's argument, whatever values inside their output schemas the tools return. A program proposed elsewhere, by hand or by a language model, is verified the same way, link by link. [valgebra-jsonschema]() reads each tool's MCP `inputSchema` and `outputSchema` into [valgebra]()'s sets, and valgebra decides every inclusion a program rests on.
```
from valgebra_planning.contracts import read_contract, read_task
from valgebra_planning.critic import critique
def tool(name, takes, returns):
"""Return the contract of a tool listed with these properties, every one required."""
return read_contract(
{
"name": name,
"inputSchema": {"type": "object", "properties": takes, "required": [*takes]},
"outputSchema": {"type": "object", "properties": returns, "required": [*returns]},
}
)
ORDER = {"type": "string", "pattern": "^ord_[0-9]+$"}
REFUND = {"type": "string", "pattern": "^rfd_[0-9]+$"}
tools = {
"find_order": tool("find_order", {"order_id": ORDER}, {"status": {"enum": ["open", "paid"]}}),
"refund": tool(
"refund", {"order_id": ORDER, "status": {"const": "paid"}}, {"refund_id": REFUND}
),
}
task = read_task("refund an order", {"order_id": ORDER}, REFUND)
# A program a model proposed: it refunds whatever order the lookup returns.
checked = critique(
"c1 = find_order(order_id=order_id)\n"
"c2 = refund(order_id=order_id, status=c1.status)\n"
"return c2.refund_id\n",
tools,
task,
)
print(checked.accepted)
print(checked.notes[0])
```
```
False
refuted: c1.status <= refund.status; 'open' lies outside; test `if c1.status in refund.status:` and make the call in that branch
```
```
pip install valgebra-planning # Python 3.11 or later
pip install "valgebra-planning[mcp]" # with a live MCP server's tools, and the proxy
```
Every inclusion a program rests on is a link, and each reads proven, refuted, with a value that breaks it where one is found, or undecided where valgebra cannot tell, which never counts as proven. A program is accepted when every link is proven and no path stops. [How it works]() builds this from a tool's contract up, with a diagram for each step.
Start with [the command line](), [a model's program checked]() or [the recipes](); [the method]() is what every answer means.
The site serves [`llms.txt`](), a manifest of its pages, and [`llms-full.txt`](), their full text, for a reader that is not a browser. The developer pages under `docs/dev/` are not published: [how a version reaches PyPI](), and [the rules for every text]().
# Using valgebra-planning
How to plan the tasks of a tool library, or check a program written for one, from the command line. What each answer means is [the method]()'s.
## A library
A library is a directory (`valgebra_planning/library.py` reads it):
| file | holds |
| --- | --- |
| `tools.json` | a server's `tools/list` result: `{"tools": [...]}`, each tool its `name`, `inputSchema`, and the `outputSchema` and `annotations` it declares; `"trusted": true` where the server's annotations are trusted |
| `tasks.json` | `{"tasks": [...]}`, each task a `name`, the JSON Schema of each value the agent starts with in `inputs`, the JSON Schema of the `goal`, and the rules it is held to: `errors` (any tool may fail), `policies` and `flows` by name, `types`, the file of observed calls its semantic types are mined from |
| `policies.json` | `{"policies": [...]}`, each an automaton over calls (`valgebra_planning/policy.py`): `initial`, the `bad` states no path may reach, the `pending` states no path may end in, and the `transitions` |
| `flows.json` | `{"flows": [...]}`, each a flow rule (`valgebra_planning/flows.py`) |
| a file `types` names | `{"calls": [...]}`, each an observed call: `tool`, `arguments`, `result`; a tool listed without an `outputSchema` gets one shaped from its results there, an assumption every binding resting on it names |
A tool without an `outputSchema` can be called, and nothing it returns can fill another call's argument: its result is a set no argument is proven to hold. `examples/parcels` is a library holding every file.
## Plan
```
uv run valgebra-planning plan examples/parcels --task "return a parcel"
```
prints the program for each task (every task when no `--task` is given; `--task` repeats), whether it is strong or weak, how many of its links valgebra proves, each link not proven, each value a weak program's stops leave uncovered, and each binding resting on a mined type. With `--json` it prints one JSON document, a list holding a row per task. The exit status is 1 when a task gets no program.
## Critique a program written elsewhere
```
uv run valgebra-planning critique examples/parcels --task "return a parcel" program.py
```
reads `program.py`, the Python an agent writes against typed tool APIs (`valgebra_planning/critic.py` states what it reads), verifies every link under the rules the task names, and prints each link not proven with the value that refutes it and what to change: the test that makes a call safe, the call a policy needs first, the source a flow rule trusts, the error block a call needs. A binding crossing two types the task's observed calls tell apart is a note, and decides nothing. The exit status is 0 when the program is accepted, 1 when it is not, and 2 when the reader refuses its text.
## Stubs for a model
```
uv run valgebra-planning stubs examples/parcels
```
prints the library's tools as Python stubs, after a preamble stating the language a program uses: one function a tool, every argument by name, its docstring holding the tool's input and output schemas. Hand them to a model to write a program against, then `critique` it; in Python, `valgebra_planning.codemode.repair` runs that loop with any callable as the model.
## Check a library
```
uv run valgebra-planning check examples/parcels
```
lists every specification in the library that holds vacuously, as [the method]() defines them: a goal no value or every value meets, a policy transition that never fires, a policy that can never be violated, a flow rule that lets nothing or everything through, a rule no task is held to. A finding valgebra leaves undecided is marked so. The exit status is 1 when it finds one.
## Compare two privilege policies
```
uv run valgebra-planning privileges old.json new.json
```
reads two privilege policies in Progent's format, `{"tool": [[priority, effect, condition, fallback], ...]}`, and prints for each tool the new one names whether it narrows the old one, expands it, with a call it newly allows, or is left undecided. The exit status is 0 only when every tool narrows. In Python, `valgebra_planning.privilege.as_policy` turns a policy into one the planner, the verifier and the runner hold a program to.
## A live server
With the `mcp` extra (`uv sync --extra mcp`, or `pip install "valgebra-planning[mcp]"`), `--server` reads the tools from a live MCP server instead of `tools.json`: a URL connects over Streamable HTTP, anything else is a command starting a server over stdio. The command is split as a POSIX shell splits it, on Windows as well: a backslash escapes the character after it, so a path holding one, or a space, goes in single quotes, as `shlex.quote` writes it.
```
uv run valgebra-planning plan examples/parcels --task "return a parcel" \
--server "uv run python tests/parcel_server.py"
uv run valgebra-planning run examples/parcels --task "settle a parcel" \
--inputs '{"tracking": "AB123456789IT"}' --server "uv run python tests/parcel_server.py"
```
`run` plans the task over the server's tools and runs the program against the server (`valgebra_planning/servers.py`): each call is a `tools/call`, its `structuredContent` the value it returns, an `isError` result, a protocol error or a request for input a tool error, and the run fails closed on any argument record, policy step or result outside its contract. It prints how the run ended, and the cause of a break (the server, an assumption, or the program), and exits 1 unless it returned a value with no break. `tests/parcel_server.py` serves the example's tools over stdio.
## A proxy in front of a server
```
uv run valgebra-planning proxy --server "uv run python tests/parcel_server.py" --library examples/parcels
```
serves an MCP server over stdio, in front of `--server`, that lists its tools as they are and answers a call only after holding it to the tool's contract, to every policy and flow rule the library defines, and, the call made, its result to the output schema (`valgebra_planning/proxy.py`). A broken check answers the call with a tool error naming it, and the call never reaches the server, or its result the agent. The error names each failure's path and code, as `run_id: string_pattern_mismatch`, and never the value: a key the tool's schemas do not declare is written `*`, so no part of a refused result reaches the agent through the error. A refused call leaves every policy where it was. A flow rule reads provenance from values: an argument equal to a value a source tool returned is taken as that tool's, an assumption. Under `only` an argument equal to no value its sources returned is refused, and so is a value from a task input, since a proxy sees no task. A call the server answers by asking for input is answered with a tool error, and the request is not forwarded. An agent connects to the proxy as to any stdio server, and no agent changes.
## Limits
- With `--server`, the tasks, policies, flow rules and observed calls are still the library's files.
# Code mode
How a program a model writes in Python against typed tool stubs is proven before it runs and run so that the proof holds, and what the proxy holds for an agent whose program is never seen. The same steps have [a command line](); what a link means is [the method]()'s.
## Stubs, critique, run
Run from the repository root:
```
import asyncio
import shlex
import sys
from pathlib import Path
from valgebra_planning.codemode import feedback, stubs
from valgebra_planning.critic import critique
from valgebra_planning.library import read_library
from valgebra_planning.planner import plan
from valgebra_planning.program import render
from valgebra_planning.servers import connect, run_on_server
library = read_library(Path("examples/parcels"))
settle = library.problem("settle a parcel")
prompt = stubs(library.tools) # what a model writes against
first = critique(
"c1 = find_parcel(tracking=tracking)\n"
"c2 = book_return(parcel_id=c1.parcel.parcel_id, state=c1.parcel.state,"
" weight_g=c1.parcel.weight_g)\n"
"return c2.label_id\n",
library.tools,
settle.task,
)
print(first.accepted)
print(feedback(first))
# A second proposal, written as the critique asks: here the planner's own program.
second = critique(render(plan(library.tools, settle.task).program), library.tools, settle.task)
print(second.accepted)
async def ran():
# The command is split as a POSIX shell splits it, so the interpreter's path is quoted.
async with connect(shlex.join([sys.executable, "tests/parcel_server.py"])) as client:
inputs = {"tracking": "AB123456789IT"}
return await run_on_server(second.program, library.tools, settle.task, inputs, client)
result = asyncio.run(ran())
print(result.broken, result.value.startswith("lbl_"))
```
```
False
refuted: c1.parcel.state <= book_return.state; 'returned' lies outside; test `if c1.parcel.state in book_return.state:` and make the call in that branch
refuted: c1.parcel.weight_g <= book_return.weight_g; 26325 lies outside; test `if c1.parcel.weight_g in book_return.weight_g:` and make the call in that branch
True
() True
```
The first program passes a parcel's state and weight to `book_return` untested, and valgebra refutes both links with a value the parcel's schema admits and the argument refuses; each critique names the test that makes the call safe. A field read without the test showing its key, as `c1.parcel.note` where the parcel's schema leaves `note` optional, is refuted with a record lacking it, and its critique names the key test, `if "note" in c1.parcel:`. The second program tests both and covers every other state, and every link is proven. `codemode.repair` runs the same loop with any callable from the last critique to a program as the model.
## What makes the proof hold
The program that runs is the program proven. `valgebra_planning/run.py` interprets the `Block` the critic read, with no `exec` of the model's text: it checks each argument record against the tool's input set before the call, each policy's step, and each result against the output set after it, and it fails closed on the first that breaks. So `if x in tool.argument:`, `retry(...)` and `stop(...)` mean what the critic proved only in this runner.
This is the plan-then-execute and code-then-execute pattern (Beurer-Kellner et al. 2025): the program is fixed before a tool's output is read, so no text a tool returns can choose a call. CaMeL (Debenedetti et al. 2025) holds the same order with capabilities on values; here each link is an inclusion of sets valgebra decides, and a flow rule is checked over the program's references, which name the call a value came from.
Code orchestration that executes model-written code in a sandbox (Anthropic's programmatic tool calling, Cloudflare's Code Mode, smolagents' `CodeAgent`) runs the code as written, and the sandbox bounds what it reaches; no proof precedes the run. The two read the same contracts: the stubs here are written from each tool's published `inputSchema` and `outputSchema`.
## The proxy, for an agent whose program is not seen
`valgebra-planning proxy` stands in front of a server for an agent written elsewhere, and holds each call as it comes. What it holds is of two kinds.
- **Contract and policy checks hold against any author of the call.** The argument record against the tool's input set, each policy's step, and the result against the output set are decisions over the values themselves: an argument outside the input set is refused whatever produced it, a model steered by injected text included.
- **Flow rules hold against no attacker that adapts.** A proxy sees values, not references, so it reads provenance by equality: an argument equal to a value an untrusted tool returned is taken as that tool's. A value the model upper-cases, encodes or cuts equals none it was returned and passes. A defense an attacker can steer through the model's output is judged against an attacker who adapts to it (Nasr et al. 2025), and this one stops none that does. A flow rule is a guarantee over a program the critic checked, where provenance is a reference, and a heuristic in the proxy.
The proxy serves one agent over stdio, and a call its server answers by asking for input is answered with a tool error ([limits]()).
## Limits
- **The language computes nothing.** A program calls, tests, loops and returns; it has no arithmetic and no aggregation, so "the mean of the values the calls returned" is not a program here. A computation over the returned values, after every call is made, is not proposed until a consumer needs one.
- **The runner is the only interpreter.** A program proven here and run anywhere else, a sandbox included, carries none of the checks above.
# Recipes
Each recipe is one task done end to end in Python, over tool listings already in hand as a server's `tools/list` returns them, and each says what it cannot do. Each block runs as written and prints the text that follows it. The same steps have [a command line](), and what each answer means is [the method]()'s.
## A model's program, checked before it runs
A model writing a program against a library's tools passes what one call returns to the next, and nothing about the model makes each value fit the argument it fills. `critique` asks valgebra every link the program rests on, for every value the tools' output schemas admit, and names each link not proven with the test that makes the call safe; `feedback` is the text to hand back to the model. A program it accepts runs with `run`, each call a function standing for the server:
```
from valgebra_planning.codemode import feedback
from valgebra_planning.contracts import read_contract, read_task
from valgebra_planning.critic import critique
from valgebra_planning.planner import plan
from valgebra_planning.program import render
from valgebra_planning.run import run
ORDER_ID = {"type": "string", "pattern": "^ord_[0-9]+$"}
TOOLS = [
{
"name": "find_order",
"inputSchema": {
"type": "object",
"properties": {"order_id": ORDER_ID},
"required": ["order_id"],
},
"outputSchema": {
"type": "object",
"properties": {
"status": {"enum": ["open", "paid", "shipped"]},
"total_cents": {"type": "integer", "minimum": 0},
},
"required": ["status", "total_cents"],
},
"annotations": {"readOnlyHint": True},
},
{
"name": "refund",
"inputSchema": {
"type": "object",
"properties": {
"order_id": ORDER_ID,
"status": {"const": "paid"},
"amount_cents": {"type": "integer", "minimum": 1},
},
"required": ["order_id", "status", "amount_cents"],
},
"outputSchema": {
"type": "object",
"properties": {"refund_id": {"type": "string", "pattern": "^rfd_[0-9]+$"}},
"required": ["refund_id"],
},
},
{
"name": "escalate",
"inputSchema": {
"type": "object",
"properties": {"order_id": ORDER_ID},
"required": ["order_id"],
},
"outputSchema": {
"type": "object",
"properties": {"ticket_id": {"type": "string", "pattern": "^tkt_[0-9]+$"}},
"required": ["ticket_id"],
},
},
]
contracts = {tool["name"]: read_contract(tool) for tool in TOOLS}
task = read_task(
"refund an order",
{"order_id": ORDER_ID},
{"type": "string", "pattern": "^(rfd|tkt)_[0-9]+$"},
)
proposed = critique(
"c1 = find_order(order_id=order_id)\n"
"c2 = refund(order_id=order_id, status=c1.status, amount_cents=c1.total_cents)\n"
"return c2.refund_id\n",
contracts,
task,
)
print(proposed.accepted)
print(feedback(proposed))
repaired = critique(
"""
c1 = find_order(order_id=order_id)
if c1.status in refund.status:
if c1.total_cents in refund.amount_cents:
c2 = refund(order_id=order_id, status=c1.status, amount_cents=c1.total_cents)
return c2.refund_id
else:
c3 = escalate(order_id=order_id)
return c3.ticket_id
else:
c3 = escalate(order_id=order_id)
return c3.ticket_id
""",
contracts,
task,
)
checked = repaired.verification
print(repaired.accepted, checked.count("proven"), "of", len(checked.links), "links proven")
server = {
"find_order": lambda order_id: {"status": "paid", "total_cents": 2500},
"refund": lambda order_id, status, amount_cents: {"refund_id": "rfd_9"},
"escalate": lambda order_id: {"ticket_id": "tkt_4"},
}
print(run(repaired.program, contracts, task, {"order_id": "ord_7"}, server).value)
print(render(plan(contracts, task).program))
```
```
False
refuted: c1.status <= refund.status; 'open' lies outside; test `if c1.status in refund.status:` and make the call in that branch
refuted: c1.total_cents <= refund.amount_cents; test `if c1.total_cents in refund.amount_cents:` and make the call in that branch
True 9 of 9 links proven
rfd_9
c1 = escalate(order_id=order_id)
return c1.ticket_id
```
The first program refunds whatever order the lookup returns. valgebra refutes both links it rests on: an `open` order lies outside `refund`'s `status`, and a total of `0` outside its `amount_cents`. The second tests each value into the argument it fills and escalates every other order, so every link is proven, and `run` checks each argument record and result again as the calls are made. `codemode.repair` runs the same loop with any callable from the last critique to a program as the model ([code mode]()).
**The goal is the specification.** `plan` finds the shallowest program whose every path returns inside the goal, and for this task that is to escalate every order: a goal admitting a ticket admits a program that only ever opens one. A goal of refunds alone leaves an `open` or a `shipped` order, and a paid one totaling `0`, no program, and the planner returns the second program with a stop where it escalates: a weak program, whose stops name those values. The critic reads the language `codemode.stubs` states and refuses any other construct by its line, with `ProgramError`.
## A server that answers outside its contract
A proof holds over the tool contracts, so a server returning a value its own output schema refuses is the case a run must not pass on. `run` checks each result before binding it and ends the run at the first that breaks, so no later call reads the value; `blame` names whose break it is:
```
from valgebra_planning.contracts import read_contract, read_task
from valgebra_planning.critic import critique
from valgebra_planning.run import blame, run
STATUS = {"enum": ["open", "paid", "shipped"]}
find_order = read_contract(
{
"name": "find_order",
"inputSchema": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
"outputSchema": {
"type": "object",
"properties": {"status": STATUS},
"required": ["status"],
},
}
)
contracts = {"find_order": find_order}
task = read_task("an order's status", {"order_id": {"type": "string"}}, STATUS)
checked = critique("c1 = find_order(order_id=order_id)\nreturn c1.status\n", contracts, task)
server = {"find_order": lambda order_id: {"status": "refunded"}}
ended = run(checked.program, contracts, task, {"order_id": "ord_7"}, server)
print(checked.accepted, ended.value)
print(ended.refused)
print(blame(ended, contracts, proven=checked.accepted))
```
```
True None
find_order returned a value outside its contract (status: union_error)
find_order broke the output schema its server declares
```
The refusal names the field and valgebra's code, never the value: a result outside its contract reaches no reader through the message that refuses it.
A proven program breaks at run time only where something it rests on fails, here the server's own output schema; an argument record, a policy or a returned value breaking in a proven program is a defect to report. With `enforce=False` the run records every break and goes on: a diagnosis of what a server returns, not a guard.
**A run is not a proof.** It checks the values one run sees, and the next run's server may answer otherwise. An annotation that lies, a `readOnlyHint` on a tool that writes, breaks no check a run can see.
## A refund over a bound, approved first
A rule about the order of calls is a policy: an automaton over a program's calls whose guards are sets of argument records (`valgebra_planning/policy.py`). The verifier follows every path of a program through it, and a path that may reach a bad state is a link that is not proven:
```
from valgebra_planning.codemode import feedback
from valgebra_planning.contracts import read_contract, read_task
from valgebra_planning.critic import critique
from valgebra_planning.policy import read_policy
from valgebra_planning.run import run
def tool(name, arguments, result):
"""Return the contract of a tool listed with these properties, every one required."""
return read_contract(
{
"name": name,
"inputSchema": {"type": "object", "properties": arguments, "required": [*arguments]},
"outputSchema": {"type": "object", "properties": result, "required": [*result]},
}
)
ORDER_ID = {"type": "string", "pattern": "^ord_[0-9]+$"}
CENTS = {"type": "integer", "minimum": 1}
REFUND_ID = {"type": "string", "pattern": "^rfd_[0-9]+$"}
contracts = {
"find_order": tool("find_order", {"order_id": ORDER_ID}, {"total_cents": CENTS}),
"approve_refund": tool("approve_refund", {"order_id": ORDER_ID}, {"approval_id": {}}),
"refund": tool(
"refund", {"order_id": ORDER_ID, "amount_cents": CENTS}, {"refund_id": REFUND_ID}
),
}
task = read_task("refund an order", {"order_id": ORDER_ID}, REFUND_ID)
approved_first = read_policy(
{
"name": "a refund over 100.00 is approved first",
"initial": "start",
"bad": ["violated"],
"transitions": [
{"from": "start", "tool": "approve_refund", "to": "approved"},
{
"from": "start",
"tool": "refund",
"arguments": {"properties": {"amount_cents": {"minimum": 10001}}},
"to": "violated",
},
],
}
)
PROGRAM = """
c1 = find_order(order_id=order_id)
c2 = refund(order_id=order_id, amount_cents=c1.total_cents)
return c2.refund_id
"""
unapproved = critique(PROGRAM, contracts, task, policies=[approved_first])
print(feedback(unapproved))
APPROVED = PROGRAM.replace("c2 = refund", "c3 = approve_refund(order_id=order_id)\nc2 = refund")
print(critique(APPROVED, contracts, task, policies=[approved_first]).accepted)
server = {
"find_order": lambda order_id: {"total_cents": 25000},
"approve_refund": lambda order_id: {"approval_id": "apr_1"},
"refund": lambda order_id, amount_cents: {"refund_id": "rfd_9"},
}
ran = run(
unapproved.program, contracts, task, {"order_id": "ord_7"}, server, policies=[approved_first]
)
print(ran.refused)
```
```
undecided: policy a refund over 100.00 is approved first holds; this path reaches a bad state of the policy or ends in a pending one: make the call it requires where it requires it, or leave out the call it forbids
True
a refund over 100.00 is approved first: refund reached violated
```
The refund takes whatever total the order holds, which may or may not exceed the bound, so the bad state is reached possibly and the link is undecided; a refund of a constant above the bound reaches it surely, and the link is refuted. A program calling `approve_refund` first is proven for every total. Run with the policy, the runner steps it on each call before the call is made, so the unapproved refund of 250.00 never reaches the server. `plan(..., policies=[...])` makes no call that breaks a policy, and finds the approved program itself.
**A policy carries no value from one call to another.** It reads that some approval came first, not that it approved this order: a program approving one order and refunding another passes it. That one call takes the value another returned is a flow rule's, below.
## A notice to the address on file
A value the user wrote, or a page a tool fetched, may hold an address an attacker chose. A flow rule with `only` holds a sink argument to the values its named sources return (`valgebra_planning/flows.py`): every other origin, a task input or a constant included, reaches the sink only inside the rule's endorsed set, and here the rule endorses none. The planner makes no binding that breaks it, and the critic refutes one:
```
from valgebra_planning.contracts import read_contract, read_task
from valgebra_planning.critic import critique
from valgebra_planning.flows import read_flow
from valgebra_planning.planner import plan
from valgebra_planning.program import render
ORDER_ID = {"type": "string", "pattern": "^ord_[0-9]+$"}
EMAIL = {"type": "string", "pattern": "^[^@]+@[^@]+$"}
NOTICE_ID = {"type": "string", "pattern": "^ntc_[0-9]+$"}
contracts = {
spec["name"]: read_contract(spec)
for spec in (
{
"name": "find_order",
"inputSchema": {
"type": "object",
"properties": {"order_id": ORDER_ID},
"required": ["order_id"],
},
"outputSchema": {
"type": "object",
"properties": {"email": EMAIL},
"required": ["email"],
},
},
{
"name": "notify",
"inputSchema": {
"type": "object",
"properties": {"email": EMAIL, "text": {"type": "string"}},
"required": ["email", "text"],
},
"outputSchema": {
"type": "object",
"properties": {"notice_id": NOTICE_ID},
"required": ["notice_id"],
},
},
)
}
# `reply_to` is an address the user's message gave.
task = read_task("notify an order's customer", {"order_id": ORDER_ID, "reply_to": EMAIL}, NOTICE_ID)
on_file = read_flow(
{
"name": "notices go to the address on file",
"sources": ["find_order"],
"sink": "notify.email",
"only": True,
}
)
print(render(plan(contracts, task).program))
print(render(plan(contracts, task, flows=[on_file]).program))
proposed = critique(
'c1 = notify(email=reply_to, text="refunded")\nreturn c1.notice_id\n',
contracts,
task,
flows=[on_file],
)
print(proposed.notes[0])
```
```
c1 = notify(email=reply_to, text=order_id)
return c1.notice_id
c1 = find_order(order_id=order_id)
c2 = notify(email=c1.email, text=order_id)
return c2.notice_id
refuted: flow notices go to the address on file: reply_to from reply_to reaches notify.email; pass a value from a source the rule trusts, or test it into the rule's endorsed set first
```
Without the rule the shortest program sends the notice to the address the message gave; with it the planner looks the order up first. An identifier the program did not retrieve is the integrity leak of Sah et al. 2026, and the critic refutes it before the run.
**Types are the specification.** The planner fills `text` with the order's identifier, since `text` admits any string and the identifier is a string the agent holds: a slot whose schema admits any string takes any string. **Provenance is a reference here, and an assumption in the proxy.** The critic reads where each value of a program came from; `valgebra-planning proxy` sees no program, reads a value's source by its equality with what a source returned, and holds against no attacker that adapts ([the proxy]()).
## A privilege policy update
A privilege policy in Progent's format (Shi et al. 2025) maps each tool to its rules, `[priority, effect, condition, fallback]`, effect `0` allowing and `1` forbidding, so the calls it allows a tool are a set. Whether an update narrows a policy is an inclusion between two such sets, every rule and argument at once; an expansion comes with a call the new policy allows and the old one denies:
```
from valgebra_planning.privilege import describe, read_privileges, updates
OLD = {
"refund": [[1, 0, {"amount_cents": {"type": "integer", "maximum": 10000}}, 0]],
"notify": [[1, 0, {"email": "^[a-z.]+@example\\.com$"}, 0]],
}
NEW = {
"refund": [[1, 0, {"amount_cents": {"type": "integer", "maximum": 50000}}, 0]],
"notify": [
[1, 1, {"email": "^ops@"}, 0],
[2, 0, {"email": "^[a-z.]+@example\\.com$"}, 0],
],
}
for update in updates(read_privileges(OLD), read_privileges(NEW)):
print(describe(update))
```
```
notify: narrowing
refund: expansion, allowing {"amount_cents": 15968}
```
A narrowing can be applied without asking, and an expansion needs approval, as Progent has it. `valgebra-planning privileges old.json new.json` prints the same lines and exits 0 only when every tool narrows, so a policy file under review gates its own change ([compare two privilege policies]()); `privilege.as_policy` holds a program to a policy as the planner, the verifier and the runner hold any other.
**A condition reads only the arguments a call passes,** as Progent's check does, so a call leaving `amount_cents` out meets every bound on it. A rule asking the user, fallback `2`, is read as denied, and so is every call to a tool a policy names no rule for.
## A policy that cannot fire
A policy whose transition names a tool the library does not hold is never violated, so every program passes it: a check that passes without testing what its author meant is vacuous (Kupferman and Vardi 1999). `vacuities` finds each such specification in a library, every one a set question:
```
from valgebra_planning.contracts import read_contract, read_task
from valgebra_planning.library import Library, Problem
from valgebra_planning.policy import read_policy
from valgebra_planning.vacuity import vacuities
ORDER_ID = {"type": "string", "pattern": "^ord_[0-9]+$"}
contracts = {
name: read_contract(
{
"name": name,
"inputSchema": {
"type": "object",
"properties": {"order_id": ORDER_ID},
"required": ["order_id"],
},
"outputSchema": {"type": "string"},
}
)
for name in ("approve_refund", "refund")
}
approved_first = read_policy(
{
"name": "a refund is approved first",
"initial": "start",
"bad": ["violated"],
"transitions": [
{"from": "start", "tool": "approve_refund", "to": "approved"},
{"from": "start", "tool": "refunds", "to": "violated"},
],
}
)
task = read_task("refund an order", {"order_id": ORDER_ID}, {"type": "string"})
library = Library(
contracts, (Problem(task, policies=(approved_first,)),), {approved_first.name: approved_first}
)
for finding in vacuities(library):
print(f"{finding.where}: {finding.finding} [{finding.certainty}]")
```
```
policy a refund is approved first, transition 1 (start -> violated): names refunds, no tool [proven]
policy a refund is approved first: no transition that can fire reaches a bad or pending state [proven]
```
`valgebra-planning check` prints these findings for a library directory, an undecided one marked so, and exits 1 when it finds one ([check a library]()). A value drawn from a schema is tried first, a member found proving a set inhabited, and valgebra is asked only where none is.
**Vacuous is not wrong.** A guard meeting some argument records but not the ones its author meant, a bound written in euros over an argument in cents, is not vacuous and is not flagged. A guard over an argument the tool does not name is flagged only where the input schema sets `additionalProperties: false`: an open record may carry any other key, so the guard meets one.
# Release notes
## Versioning, and what counts as a break
The version follows [Semantic Versioning](). Below `0.1.0` there is no minor number to carry a break, so every `0.0.x` release may break, and its notes say where. A break is a public name removed or changed, a program accepted that is now refused or the reverse, or a command's output or exit status changed for a case it already answered; the public names are each module's `__all__` ([the Python API]()). Each release takes valgebra's and valgebra-jsonschema's newest `0.0.x`, and the ranges it requires say which.
# Changelog
All notable changes to valgebra-planning are recorded here. The format follows [Keep a Changelog](), and the project follows [Semantic Versioning]().
## [Unreleased]()
### Security
- A refusal names each failure's path and valgebra's code for it, never the value. The proxy's refusals and the runner's messages formatted up to 120 characters of the argument record, result or returned value they refused, so a result outside its contract reached the agent through the tool error that refused it. A key the tool's schemas do not declare is the value's own text and is written `*`: `get_run returned a value outside its contract (ok: bool_type)`.
## [0.0.5]() - 2026-11-21
A security release: four ways 0.0.4 proved a wrong program are closed, each under Security. The verifier reads a field below any value a program holds where valgebra proves it present, at any depth, and asks a question on a loop's item of every item of its array. It requires valgebra 0.0.31, and the parcels and bench studies read every count 0.0.4 recorded.
### Added
- A page follows a program of tool calls from the question it rests on to its verdicts, with a diagram for each step: the question each of the three packages answers, the set the verifier carries for each value, the three verdicts a link takes, where a program comes from and where it runs, and what it does not cover.
- The critique of a field read without the test showing its key, where the link carries a record lacking the key or valgebra leaves its presence undecided, names the key test to add: `if "note" in c1.parcel:`, and the read in its branch.
### Changed
- The documentation site is built by Zensical, Material for MkDocs' maintained successor, from `mkdocs.yml` as written under `zensical build --strict`: its own search, the redirects from each page's former address, `llms.txt` and `llms-full.txt`, the Mermaid diagrams and the API reference through the mkdocstrings Python handler. No page moves.
- The package requires valgebra 0.0.31 or later, which relates a meet of records as the one record it is. A loop's item an array's `allOf` narrows is proven inside the argument it feeds, as its field and its optional field are, where each read `undecided`, and a field the root's `allOf` requires of a nested object is held. A result field one member may carry outside the argument is refuted rather than `undecided`. The parcels and bench studies read no difference.
### Removed
- `Contract.optional`. The verifier reads a field below any value a program holds where valgebra proves it present, so a list of the optional fields along a result's guaranteed objects names fewer than it reads, and nothing reads the list. Without it, `inferred` is the tenth positional parameter of `Contract`, where it was the eleventh.
### Fixed
- The verifier reads any field below a value the program holds, at any depth, where valgebra proves every value held there an object holding its key: a loop item's field under a test showing its key, a field below an optional one under both tests, a task input's field under its test, and an item's field past the third level from the call's result. Each was a value the program does not hold.
- A field a record's declared schema leaves optional and its root requires, as an `allOf` may, is asked of the root, and never refuted on a value the declared schema admits and no result carries. A field whose presence valgebra leaves undecided reads undecided, not refuted.
- A flow rule reads a value as the verifier reads it, a field read below an item included.
- A loop over an array whose `items` refers into a resource with an `$id` of its own reads undecided; the verifier raised `Unsupported`.
- A key that is no Python identifier, or is a keyword, as `a-b` or `class`, is written as a subscript, `x["a-b"]`, in a rendered program, a link's claim and a critique, so each reads back; it was joined with a dot, which no reader reads.
- The argument record of a call whose input schema relates its arguments refutes only on a record valgebra proves the values the program holds carry jointly, or where each argument is a constant or a whole result or input, no two the same. A record no call makes, as one pairing two fields a result keeps equal, was reported as a counterexample.
- A run reading a field the value it holds lacks ends with the read named as a broken check, `Refusal.check` `read`, with `enforce` or without; it raised `KeyError`.
- A link on a field whose declared schema another keyword narrows, as an `allOf`, is asked of the value the field belongs to: such a field bound inside its argument is proven, and a value only the declared schema admits, which no result carries, is never reported as a counterexample.
- A value a test narrowed a field of is asked in its belief, its set met with each field tested: a field, a presence and an argument record are refuted only on a value the program may hold there. Under `if r.n in (1,):`, a read of `r.f` that every member with `n` 1 keeps inside its argument was refuted on a member with `n` 2, which the test excluded.
- A question a loop's item set leaves open, whether the item carries a field or lies with its field inside an argument, is asked of the value holding the array: an item an `allOf` beside the array's `items` keeps inside the argument is never refuted on a value no item takes, and is proven where valgebra decides the array. A value refutes an item only where valgebra proves an item carrying it in an array of a value the program may hold, on a value drawn or given for that value.
- A loop over an array whose items the walk reads no single `items` for, as under `prefixItems`, an `allOf` or a `$ref` beside another keyword, or reads a set valgebra does not prove, takes each item as any value and asks every question on it of the array. The first was refuted as no array of one item schema, a program every run of which passes; the others read undecided. The loop's body and every step after it are walked either way, so a link there is reported.
### Security
- A loop's item binds its name alone. A field of a value the program held under that name before the loop, a result or a task input, was read in the body as the item's field, so a program passing an item's field outside a tool's argument was proven where the item declares the field wider or not at all.
- A task naming an input as a tool is refused: `verify`, `critique`, `plan`, `run` and `read_library` raise `ValueError` naming it. Such an input's value read as that tool's result, so a key test on it held the tool's optional fields with the tool's schemas, and a flow rule with `only` naming the tool as its source let it reach the sink: a program passing a value outside a tool's argument, or breaking the rule, was accepted.
- An argument whose name ends in `?` is read as written in the record a relation-dependent input schema and a policy are asked of. valgebra's dict display reads a trailing `?` as an optional field of the name without it, so a relation on such an argument, as `dependentRequired`, went unchecked, and the verifier proved a call the input schema refuses.
- A result slot the walk listing slots reads is kept only where valgebra proves the whole output schema's set inside it. The walk resolves a `$ref` from the document's root, so a field inside a resource with an `$id` of its own, referring into that resource, read another schema's set, and a binding of it was proven inside an argument its values lie outside. A field and an item read below a value are held to the same proof.
## [0.0.4]() - 2026-11-19
A release of the dependency range: the planner is 0.0.3's, and every published count is the one 0.0.3 recorded, read again on valgebra 0.0.30 and valgebra-jsonschema 0.0.3.
### Changed
- The package requires valgebra 0.0.30 and valgebra-jsonschema 0.0.3 or later, with no upper bound on either: a release of either installs beside this package the day it is published, with no release of this package.
### Fixed
- The live-server example on the code mode page quotes the interpreter's path, so it runs on Windows, and the command line's `--server` and `connect` state how a command is split: as a POSIX shell splits it, on Windows as well, so a path holding a backslash or a space is quoted.
## [0.0.3]() - 2026-11-18
A cell of many overlapping ranges is decided again, as 0.0.1 decided it, and the cut keeps the cells 0.0.2 decides.
### Fixed
- A part of a cell is asked first as the meet its cell holds with the new predicate, as 0.0.1 asked it, and as its kind with every predicate it lies inside or outside only where valgebra leaves that meet undecided. Asked in the second spelling alone, as 0.0.2 asks it, a cell of many overlapping integer ranges was a meet too wide for valgebra to decide: valplan's numbers task of 128 tools cut into 43,458 cells, 42,989 undecided, in 287 s, and cuts into 507, none undecided, in 6 s, as on 0.0.1. The MCP reference servers' cut keeps 64 cells, 29 undecided, as on 0.0.2.
## [0.0.2]() - 2026-11-18
The cut a plan searches is the library's, whatever order it lists its tools in, and valgebra decides more of it; the user guide is published.
### Added
- The user guide is published at [https://ppigazzini.github.io/valgebra-planning/](), with `llms.txt` and `llms-full.txt` for a reader that is not a browser, and the Python API read from the package's docstrings.
- A recipes page does six tasks end to end in Python over one tool library: a model's program checked and run, a server answering outside its contract, a policy, a flow rule, a privilege update and a policy that cannot fire.
### Changed
- A part of a cell is asked of valgebra as its kind, each predicate it lies inside, and the complement of each it lies outside but for one a predicate inside it already excludes, where it was the meet built cut by cut. The set is the same, and valgebra decides more of them: the MCP reference servers' cut keeps 64 cells, 29 undecided, where it kept 96, 61 undecided.
- Schemas that compile to one validator, a description, a title or a default apart, are one predicate, where each spelling was one: the reference servers' 106 predicates are 37 sets, and their cut asks valgebra 507 relations where it asked 3,044.
- The package's `Documentation` link and the README's links go to the published guide. Each page's address is its topic, `/command-line/` and `/method/`, and an address the site has served before answers with a page that sends the reader on.
- The package requires valgebra 0.0.29 and below 0.0.30, and valgebra-jsonschema 0.0.2 and below 0.0.3, whose releases change no answer of valgebra 0.0.28 and valgebra-jsonschema 0.0.1.
### Fixed
- The cut a plan searches is the same however a library lists its tools: its predicates are cut in the order of their names. Split in listing order, the cells valgebra leaves undecided moved with that order: the seven MCP reference servers' 106 predicates gave 97, 127 or 130 cells in three orders, and give 96, 61 of them undecided, in every order now, asking valgebra 3,035 relations where the order the census used asked 3,082.
## [0.0.1]() - 2026-11-17
### Added
- `read_contract` reads an MCP tool's `inputSchema` and `outputSchema`, through valgebra-jsonschema, as argument and result slots, an optional output field held apart behind a key test and an output that is not an object as one slot; `read_task` reads a task's inputs and goal.
- `plan` searches a strong program of calls and type tests over the cells of every slot, input and goal, or a weak one whose stops name the values they leave; a tool the goal cannot be reached through is dropped first. `predicates` returns the list the cells are cut from.
- `verify` asks valgebra every link of a program alone, reading neither the cells nor the search: each is proven, refuted with a value outside it, or undecided.
- `critique` reads a program written in Python against `stubs`, verifies it and names, for each link not proven, the test, the order, the source or the error block it needs; `repair` runs that loop with any callable as the model.
- A program is held to tool errors and to retries of read-only or idempotent tools, to policies read as automata over calls (`policy`), to flow rules over where a value came from (`flows`), to semantic types mined from observed calls (`mining`), and to privilege policies in Progent's format (`privilege`). `vacuities` lists the specifications of a library that hold vacuously.
- `run` runs a program failing closed on every argument record, policy step and result, and `blame` names the cause of a break; `run_on_server` runs it against a live MCP server, a call that asks for input failing as a tool error.
- `serve` puts an MCP proxy over stdio in front of a server, holding every call to the contracts, policies and flow rules: its contract and policy checks hold whatever wrote the call, and its flow rules read provenance by equality of values.
- The command line `valgebra-planning`: `plan`, `critique`, `stubs`, `check`, `privileges`, `run` and `proxy`.
- Each public module's names are its `__all__`, listed on the API page.
- The package requires valgebra 0.0.28 and below 0.0.29 and valgebra-jsonschema 0.0.1 and below 0.0.2, since a `0.0.x` minor of either is a breaking release here, and Python 3.11 or later; the `mcp` extra takes the MCP SDK 2.3 and below 3.
- Measured on this release, each figure in [the results page](): on the parcel library's eight tasks every link of every program is proven, 3 of 3 to 24 of 24, and on synthetic libraries of 8 to 256 tools the cut holds 5 predicates and 12 cells at every size.
# Explanation
# How it works
A program of tool calls is accepted where valgebra proves every value it passes inside the argument it fills, and every rule it is held to, for every output the tools' schemas admit, and where no path of it stops. This page builds that sentence from a tool's contract up; [the method]() states each part in full.
## The question a program rests on
An agent calls a tool, reads a field of the result and passes it to the next tool. The first tool's output schema bounds what the field may hold; the second's input schema says what the argument takes. The call is safe for every answer the first tool may give exactly when the first set lies inside the second: an inclusion between two sets. A run tries one value of the first set; the inclusion covers all of them.
`find_order` returns a `status` in `{"open", "paid"}`, and `refund` takes a `status` in `{"paid"}`. `{"open", "paid"}` does not lie inside `{"paid"}`, and `"open"` is the value that shows it: a program passing the status straight on is refuted on it, before any call is made, as [the home page's example]() prints.
## Three packages, one question each
```
flowchart TD
listing["a tool listing:
MCP inputSchema and outputSchema"] --> companion["valgebra-jsonschema
reads each schema as a set"]
companion --> contracts["contracts: a slot per argument
and per field a result guarantees"]
program["a program, from the planner,
a model or a person"] --> verifier
contracts --> verifier["the verifier walks the program
with the set each value lies in"]
verifier -->|"is this set inside that one?"| valgebra["valgebra
decides the inclusion"]
valgebra -->|"subset, not_subset
or undecided"| verifier
verifier --> links["one link per inclusion:
proven, refuted or undecided"]
```
Each package owns one meaning, and none guesses at another's:
| question | owner |
| --- | --- |
| what a JSON Schema keyword admits | [valgebra-jsonschema]() |
| what a set holds, and whether one lies inside another | [valgebra]() |
| which value reaches which argument, on which path, under which rule | valgebra-planning |
valgebra answers an inclusion `subset`, `not_subset` or `undecided`. A relation it cannot decide stays undecided here: it can cost a program, and it never admits a wrong one.
## A program is a plan over outputs it does not choose
A tool's output is the one thing a program does not choose: the output schema bounds it, and any value inside may come back. A plan for such a world is a program of calls and tests, and it is strong when every path ends with the goal reached, whatever the outcomes (Cimatti et al. 2003). A test is an observation (Bertoli et al. 2006): on each branch the program knows more about the value it tested.
```
flowchart TD
start(["order_id in ^ord_[0-9]+$"]) --> find["c1 = find_order(order_id=order_id)
c1.status in {open, paid}"]
find --> test{"c1.status in refund.status?"}
test -->|"then: c1.status in {paid}"| refunded["c2 = refund(order_id=order_id, status=c1.status)
{paid} inside {paid}: proven"]
refunded --> done(["return c2.refund_id
^rfd_[0-9]+$ inside the goal: proven"])
test -->|"else: c1.status in {open}"| stop(["stop(c1.status)
no tool takes an open order"])
```
The planner finds this program itself, and every link of it is proven. It is not strong: the `else` path stops, and the stop names what it leaves uncovered, an order whose status is `"open"`, which no tool of the library refunds.
```
from valgebra_planning.contracts import read_contract, read_task
from valgebra_planning.planner import plan
from valgebra_planning.program import render
from valgebra_planning.verify import verify
def tool(name, takes, returns):
"""Return the contract of a tool listed with these properties, every one required."""
return read_contract(
{
"name": name,
"inputSchema": {"type": "object", "properties": takes, "required": [*takes]},
"outputSchema": {"type": "object", "properties": returns, "required": [*returns]},
}
)
ORDER = {"type": "string", "pattern": "^ord_[0-9]+$"}
REFUND = {"type": "string", "pattern": "^rfd_[0-9]+$"}
tools = {
"find_order": tool("find_order", {"order_id": ORDER}, {"status": {"enum": ["open", "paid"]}}),
"refund": tool(
"refund", {"order_id": ORDER, "status": {"const": "paid"}}, {"refund_id": REFUND}
),
}
task = read_task("refund an order", {"order_id": ORDER}, REFUND)
found = plan(tools, task)
print(render(found.program))
print("strong:", found.strong, "| uncovered:", [(u.ref, u.examples) for u in found.uncovered])
for link in verify(found.program, tools, task).links:
print(f"{link.where or 'top':5}{link.verdict:9}{link.claim}")
```
```
c1 = find_order(order_id=order_id)
if c1.status in refund.status:
c2 = refund(order_id=order_id, status=c1.status)
return c2.refund_id
else:
stop(c1.status)
strong: False | uncovered: [('c1.status', ('open',))]
top proven order_id <= find_order.order_id
then proven order_id <= refund.order_id
then proven c1.status <= refund.status
then proven return c2.refund_id <= goal
```
## What the verifier carries: a set per value
The verifier walks a program once, holding for each value the set it lies in at that point: its belief there (Bertoli et al. 2006).
- **A call's result** enters as the tool's output set, a loop's item as its array's item set.
- **A test** narrows the value it tests: to the meet with the tested set on its `then` branch, and to the meet with the complement on its `else` branch.
- **A field** below a value is read where valgebra proves every value held there an object holding its key: the schema requires it, a test `if "note" in c1.parcel:` shows it, or another keyword of the record's schema requires it (Castagna 2023).
At each step that rests on an inclusion, the verifier adds a link and asks valgebra:
| a program | rests on |
| --- | --- |
| passes a value to an argument | the value's set inside the argument's |
| writes a constant into an argument | the constant a member of the argument's set |
| calls a tool whose input schema relates its arguments | the record of the arguments inside the input set |
| returns a value | the value's set inside the goal |
| passes a value a flow rule watches to its sink | the value's set inside the endorsed set |
| ends a path under a policy | no bad or pending state of the policy reached |
## Three verdicts, one link at a time
```
flowchart TD
link["a link: a value inside an argument"] --> own{"valgebra,
on the value's set"}
own -->|subset| proven(["proven"])
own -->|"not_subset
or undecided"| drawn{"a witness the
program may hold?"}
drawn -->|"yes, carried in the link"| refuted(["refuted"])
drawn -->|no| whole{"valgebra, on the whole
value, under the tests"}
whole -->|subset| proven
whole -->|not_subset| refuted
whole -->|undecided| undecided(["undecided"])
```
- **Proven**: valgebra proves the inclusion for every value the contracts and the tests on the way admit.
- **Refuted**: valgebra proves some such value lies outside, or a concrete value it proves the program may hold there lies outside; the link carries that value where there is one.
- **Undecided**: neither. The program is not accepted, and the link says so rather than guessing.
A field's declared schema may admit more than its record allows, as where an `allOf` narrows it, so the last question is asked of the value the field belongs to, and a loop's item of the value holding its array. A program is accepted, `Verification.proven`, when every link is proven and no path stops.
## Where a program comes from, and where it runs
```
flowchart TD
subgraph before["before any call"]
task["a task:
its inputs and its goal"] --> planner["the planner
searches the cells"]
model["a language model"] -->|"Python against
typed stubs"| critic["the critic verifies
and names each fix"]
critic -->|"a critique"| model
end
planner --> accepted["a program,
every link proven"]
critic -->|accepted| accepted
subgraph during["as each call is made"]
runner["the runner checks
each call of the program"]
proxy["the proxy checks each call
of an agent no program governs"]
end
accepted --> runner
runner --> servers["the MCP servers"]
proxy --> servers
```
- **The planner** cuts every slot, input and goal into cells, the minterms of their predicates within each kind of JSON value, and searches calls and tests over them, shallowest program first, then a weak one whose stops name what they leave uncovered.
- **The critic** verifies a program written elsewhere and returns each link not proven, the value refuting it and what to change: the test that makes a call safe, the call a policy needs first, the error block a call needs. A language model proposes and a sound critic checks (Kambhampati et al. 2024); `repair` hands each critique back until a program is accepted or the rounds run out. [Code mode]() is that loop.
- **The runner** calls the tools a program names and checks each step as it is made. A proof holds over the contracts, so the case a run must not pass on is a server answering outside its own contract: the run ends, closed, naming the check.
- **The proxy** stands in front of an MCP server for an agent no program governs, and answers a call breaking a check with a tool error naming it.
## A proof and a run
| | checks | when |
| --- | --- | --- |
| `verify`, `critique` | every value the contracts admit | before any call |
| `run` | the values of one run: each argument record, result, policy step and the returned value | as each call is made |
| the proxy | each call an agent makes: its arguments, its result, the policies and the flow rules | as each call is made |
A run that breaks no check shows the values it met. A verified program holds for every value the contracts admit, and a run beside it shows the servers keep those contracts.
## Rules beyond types
A program is held to more than the types its values carry, each rule asked as sets the same way ([the rules]()):
- **Errors.** Where any tool may answer with an error, a call is retried only where its tool's annotations say it is read-only or idempotent; any other call needs an error block.
- **Policies.** An automaton over the calls, whose guards are sets of argument records: a path that surely reaches a bad state, or ends in a pending one, an obligation left open, is refuted, and one that possibly does is undecided.
- **Flows.** A value from a source the rule names reaches its sink only inside the set the rule endorses. With `only` the rule holds every other origin instead: the sink takes a value from its sources on every path, and anything else only inside the endorsed set.
## Where it sits
CaMeL (Debenedetti et al. 2025) runs a model's plan in an interpreter that records where each value came from and checks a policy before each call; FIDES (Costa et al. 2025) labels each value's integrity and confidentiality in the planner; Progent (Shi et al. 2025) allows each tool's calls by a privilege policy. Each checks a call as the agent makes it. valgebra-planning asks the integrity half of those questions of the whole program before it runs, as flow rules and privilege policies over sets, for every output the contracts admit; its runner and proxy ask them again of each call made.
## What it does not cover
- **The types are the specification.** A slot whose schema admits any string takes any string: distinct patterns, enums and ranges are what make a proof mean what its author wants.
- **Effects are the policies'.** A call can act on the world, and no effect is modeled beyond the calls a policy reads.
- **A gap is reported, never filled.** A relation valgebra leaves undecided, a keyword the companion cannot read, a stop no tool covers: each is named where it falls.
The full list is [the limits]().
# Method
What each part holds a program to, in full: the contracts a program is read against, the verifier, the cells and the planner, the rules beside the types, the critic, a run, and the limits. [How it works]() covers the same ground in brief, with a diagram for each step.
## Contracts as slots
An agent fills each argument of a call from a value it holds, so a tool is read as slots (`valgebra_planning/contracts.py`): one per property of its MCP `inputSchema`, a required name no property declares included, and one per field its `outputSchema` guarantees, nested to three levels, beside the whole result. valgebra-jsonschema compiles each slot against the tool's own schema as root, and an older draft reads as it means. The walk listing the slots reads `properties`, `required`, `items` and a bare `$ref` itself, resolving a reference from the document's root, so a slot it yields is kept only where valgebra proves the whole schema's set inside it; a field it reads otherwise takes any value, and so does an item of an array it reads otherwise or not at all, a question on the item then asked of the array. The verifier reads any field below a value the program holds, at any depth, where valgebra proves every value held there an object holding its key (Castagna 2023): the record's schema requires it, or a test showing the key, `if "note" in c1.parcel:`, narrows the record to the values holding it, or the schema of the record's root requires it, as an `allOf` may of a key its object leaves optional. The field read lies in what its record's schema declares for the key, an upper bound of its values. A field valgebra proves some value lacks, with no test narrowing a field on the way, reads refuted, and one whose presence valgebra leaves undecided reads undecided. A task holds the slots of each value the agent starts with, read as a result's are, and the set its goal is. A value's source is read by its name, as a flow rule names its sources by input or by tool alike, so a task names no input as a tool: `verify`, `critique`, `plan`, `run` and `read_library` raise `ValueError` on one.
Where the input schema relates its arguments, through `oneOf`, `dependentRequired` or any keyword beside `type`, `properties`, `required` and `additionalProperties`, a call is accepted only once the whole argument record is proven inside the input set, each argument under its name as written, a trailing `?` included. The record is asked as the product of its arguments' sets, which holds every record the call can make, so a proof stands. Two arguments read from one value may move together, so the product refutes only where each argument is a constant or a whole result or input, no two the same, with no field of it tested on the way; otherwise a record refutes only where valgebra proves the values the program holds carry it jointly, and the link is undecided where none does.
## The verifier
A program is calls, then one ending: a return, a stop, or a branch on whether a value lies in a tool's argument or in listed constants (`valgebra_planning/program.py`). A call binds each argument to a value the program holds or to a JSON constant written into it. Its text reads as Python.
The verifier (`valgebra_planning/verify.py`) walks a program with the set each value lies in, narrowed by intersection or complement at every branch, and asks valgebra each inclusion the program rests on: a value inside the argument it fills, the record where the arguments are related, the returned value inside the goal. Each link reads proven, refuted or undecided, and a refuted or undecided one carries a value outside the inclusion where the examples given or the values drawn from the value's own schema hold one. A concrete member is a proof, so such a value refutes an undecided link. A field's declared schema may admit more than its record allows, as where an `allOf` narrows it, so a link on a field its declared set does not prove is asked of the value the field belongs to: whether the field lies inside on every such value carrying it. That value is asked in its belief, its own set met with each field of it a test on the way narrowed, so its answer is exact both ways, and a value drawn for the field is reported only where valgebra proves a value of that belief carries it there. A constant's link is decided by membership alone, the constant being its own counterexample where it lies outside. The verifier reads neither the cells nor the search.
A loop, `for item in ref:` over an array, is walked once for an arbitrary item of the array's item set, the item and its fields read as a result's are, a test showing a key included. The item's name holds the item alone, never a field of a value the program held under that name before. The item set is what the array declares in `items`, which another keyword of the array may narrow, so a question it leaves open is asked of the value holding the array: whether every item the body's tests admit carries the field, or lies inside. Where the walk reads no single `items`, as under `prefixItems`, an `allOf` or a `$ref` beside another keyword, the item set is every value, and each question is asked of the array so; the loop's body and every step after it are walked either way. A value refutes a link on an item only where valgebra proves an item carrying it in an array of a value the program may hold, proven on a value drawn or given for that value with such an array in place of its own. Nothing crosses iterations, since what the body calls is scoped to its iteration and a body never returns, so the one walk holds for every item.
## The cells
Every slot, input and goal is a predicate on JSON values, and the cells are their minterms within each of the seven kinds of JSON value (`valgebra_planning/cells.py`): predicate abstraction (Graf and Saidi 1997) over the minterms of an effective Boolean algebra (D'Antoni and Veanes 2017). Each predicate is exactly a union of cells, so an inclusion between cells implies the inclusion between predicates.
A part of a cell is dropped only where valgebra proves it empty, inhabited where a concrete value lies in it or valgebra refutes its emptiness, and kept as undecided otherwise: an undecided cell can cost a program, never admit a wrong one. A part is asked as the meet its cell holds with the new predicate or its complement, and where valgebra leaves that undecided, as its kind, each predicate it lies inside and the complement of each it lies outside but for one a predicate inside it already excludes. The two spell one set, and each is decided where the other is not: the second holds the complement of a predicate a cell lies outside by a relation, which some meets of arrays of records need, and the first holds only the predicates it was cut by, which keeps a cell of many overlapping ranges within what valgebra decides. Schemas valgebra compiles to one validator, a description or a default apart, are one predicate, since equal validators denote one set. Relations between two predicates, each asked once, settle most cuts. The concrete values are the edges of common bounds, every listed value, draws from each schema and objects merged from those draws, since an open record meets another where a value carries both their keys. The predicates are cut in the order of their names: which meets valgebra leaves undecided depends on the order the cut splits by and draws in, so a fixed order makes a library's cells the same however it lists its tools.
Before any cell is cut, the planner keeps only the tools a program can reach the goal through: callable, every required argument meeting a value the agent may hold, and mattering, a result meeting the goal or an argument of a tool that matters (SyPet, Feng et al. 2017). A value no argument and no goal can hold is left out, with its reference.
## The planner
A state maps each value the agent holds to its cells (`valgebra_planning/planner.py`). A call is enabled when each required argument has a value whose cells lie inside the argument's. A guarded call branches on a value that only overlaps an argument, calls the tool on the narrowed value in one branch and goes on in the other; a second overlapping argument is guarded inside it. A program is strong when every path returns a value whose cells lie inside the goal's: strong planning under nondeterministic outcomes (Cimatti et al. 2003), a branch being an observation (Bertoli et al. 2006). The search deepens on the calls and tests along a path, so the first strong program is a shallowest one. Where none exists, one search at the full bound lets a branch stop once its sibling returns, and each stop names the values it leaves uncovered.
A call whose result no later step reads is dropped, since a call can act on the world, and a branch whose two sides then read the same is collapsed.
## Rules a program is held to
Each rule is checked the same way by the planner, which makes no call breaking it, and by the verifier, which adds a link for it.
- **Errors** (`errors`). Any tool may answer with an error. A call may be retried only where the tool's annotations say it is read-only or idempotent, a strong cyclic solution ending under fairness (Daniele et al. 2000); any other call needs an error block, `try:`/`except ToolError:`, since retrying it may act twice. A call made again in its error block on the values it was given is a retry written out, and held as one. A retry's link lists what it rests on: the tool's errors transient within the runner's 8 attempts, and the annotations, a hint the server gives, unless the library marks the server trusted. A multi round-trip request is the client's loop around one call and leaves the plan unchanged.
- **Policies** (`valgebra_planning/policy.py`). An automaton over a program's calls whose guards are valgebra sets over the argument record. Along each path a guard is taken surely, possibly or never, and a path surely reaching a bad state is refuted, possibly undecided. A loop's body may run any number of times, so the states a policy may be in when it starts are taken to a fixpoint, the states being finite. A policy reads one program's calls in order and carries no value from one call to another. A transition may read an annotation hint, `destructiveHint` or another, on any tool setting it; the policy's link then lists the hints it reads as an assumption. A pending state is an obligation: a path may pass through it and must not end in it, as a booking owes a notice. Every path of a program ends, a loop's after any number of items, so a pending state is decided before the run, where a monitor reading a prefix cannot decide it (Bauer et al. 2011); the runner reads it when the run ends. A bad state is never left.
- **Flows** (`valgebra_planning/flows.py`). A value from an untrusted source reaches a sink argument only inside the rule's endorsed set, and with `implicit` no sink call runs under a test on such a value or in a loop over an array from such a source: the integrity half of CaMeL (Debenedetti et al. 2025), FIDES (Costa et al. 2025) and Progent (Shi et al. 2025), decided over sets. With `only`, the rule holds every origin but its sources, so a sink takes a value from a named tool or input on every path, and a literal or another tool's value only inside the endorsed set: an identifier the program did not retrieve, the integrity leak of Sah et al. 2026, is refuted before the run.
- **Mined types** (`valgebra_planning/mining.py`). Slots holding one observed value are one semantic type (APIphany, Guo et al. 2022), and a value fills an argument only where their types agree. A mined type is an assumption: the verifier reads none, and a plan names each binding that rests on one.
- **Inferred outputs** (`valgebra_planning/mining.py`). A tool listed without an `outputSchema` gets one shaped from its results in the observed calls: each kind seen, an object's keys every observed one holds required, nothing narrower guessed. It is an assumption as a mined type is: every link resting on it lists it beside valgebra's verdict, the plan names each binding that rests on it, and a run refuses a result outside it, naming it.
- **Privileges** (`valgebra_planning/privilege.py`). A privilege policy in Progent's format (Shi et al. 2025) is a set of calls per tool: each allowing rule's condition, minus every rule tried before it, the first rule matching deciding and every other call denied. Whether an update narrows a policy is an inclusion between two such sets, which valgebra decides or refutes with a call one allows and the other does not, every rule and argument at once. As an automaton whose bad state a call outside its tool's set reaches, the policy holds a program like any other.
## The critic
`valgebra_planning/critic.py` reads a program written elsewhere, in the Python an agent writes against typed tool APIs, verifies it under the rules the task is held to and returns a critique: each link not proven, the value refuting it, and what the author can change, the test that makes a call safe for a binding, the call a policy needs first, the source a flow rule trusts, the error block a call needs. A language model proposes, a sound critic checks (Kambhampati et al. 2024). Mined types decide nothing here either: a binding crossing two types the observed calls tell apart is a note, and the program is accepted on its links alone.
`valgebra_planning/codemode.py` gives the tools as typed Python stubs for a model to write against, each docstring holding the tool's own input and output schemas, since a pattern or a bound has no Python type; and `repair` hands each critique back to the model for the next proposal, until a program is accepted or the rounds run out, any callable being the model.
## Specifications that hold vacuously
A check that passes without testing what its author meant is vacuous (Kupferman and Vardi 1999), and `valgebra_planning/vacuity.py` finds each kind a library can hold, every one a set question: a goal no value meets or every value meets; an input, an argument record or a result no value meets; a policy transition naming no tool, or whose guard no argument record of its tool meets, and a policy no transition that can fire takes to a bad state; a flow rule naming no tool or argument, or whose endorsed set meets nothing its sink takes, or holds all of it; a policy or rule no task is held to. Values drawn from a schema are tried first, a member found proving a set inhabited; valgebra is asked only where none is, and a question it leaves undecided is reported as undecided.
## Running a program
`valgebra_planning/run.py` calls the tools a program names and checks each step as it is made: the argument record against the tool's input set, each policy's step, the result against the output set and the returned value against the goal. It fails closed: the first broken check ends the run before the call is made, the result bound or the value returned, and `Run.refused` names it. A proof of a program holds over the contracts, so a tool answering outside its own contract is the case a run must not pass on. With `enforce=False` the runner records every break and goes on, a diagnosis rather than a guard. `blame` names why a run broke: a proven program breaks only where something it rests on fails, a server returning outside the output schema it declares, a schema inferred from observed calls not holding, an error outlasting a retry's attempts; an argument record, a policy or a returned value breaking in a proven program is a defect to report, and in an unproven one its own unproven link. A lying annotation and a wrong mined type break no check a run can see. `valgebra_planning/proxy.py` holds the same checks as an MCP server in front of another, for an agent no program governs: each call is answered with a tool error naming the check it breaks, and each failure's path and code but never the value or a key the schemas do not declare, so a refused result reaches the agent through no error; a refused call steps no policy, and a flow rule reads a value's source from equality with what a source tool returned, an assumption. With `only` that is the grounding gate of Sah et al. 2026: an argument equal to no value its sources returned is refused, and a value from a task input with it, since a proxy sees no task.
## Limits
- **Types are the specification.** A slot whose schema admits any string, as an unasserted `format` does, takes any string; distinct schemas, patterns, enums and ranges are what make a plan mean what it should, and mined types narrow what observations support.
- **What is not modeled.** Side effects beyond the calls a policy reads; a field or an item inside a resource with an `$id` of its own that refers into that resource, which the walk resolves from the document's root and so reads as any value, a gap the companion's reader of the whole schema closes; a field whose record's `properties` do not declare it, which takes any JSON value, as one an `anyOf` alone declares; and a program the planner writes holds no constant, tests no key and loops over no array. A program written elsewhere may do all three, and each is checked like any value.
- **No Python door.** A tool is read from the JSON Schema its server publishes, never from a Python function's annotations. Where a call travels as JSON, the MCP SDK, FastMCP and the OpenAI Agents SDK publish that schema from the same annotations, so a second reading adds no tool, and it disagrees with the published one where Python's equality is kept: valgebra's `Literal[1]` refuses `1.0`, which `{"const": 1}` holds, so a program proven over one reading can be refuted over the other. A tool called with Python values, a tuple, a dataclass or a `datetime`, lies outside the seven kinds of value `json.loads` returns that the cells partition (`KINDS` in `valgebra_planning/cells.py`), and would need an abstraction over valgebra's whole universe, not a reader. Refused until a consumer calls tools with Python values under no published JSON Schema.
- **No verify-before-retry.** A call made again on a value read again after its error is not judged a retry: whether it repeats the first rests on what the read shows, which only a postcondition the library declares could say (Mansoor et al. 2026), and none is read. So when a call that is not idempotent fails, its path goes on without it, through another call or to a stop.
- **A stop is not a question.** Each weak plan of the parcel library stops on a value a tool returned, a parcel's state or country. Asking the user for one inside the set the next call takes would put a value they make up where the tool's must be: the integrity leak a flow rule with `only` refutes. A stop on a task input says the task admits inputs no tool takes, which its input schema fixes before any run.
- **A stop is not replanned.** The cells are exact for every argument set, so a run's value in a stopped cell meets no argument the search did not try: a plan from the run's values gains only past the depth bound, which a larger bound gives, or where valgebra left a cell undecided. From every stop of the parcel library, its values held as constants, no plan exists at depth 8. A resumed segment would also have to start from the run's policy states and keep each held value's origin, or a flow rule would no longer see it.
- **A policy carries no value between calls.** A rule about one parcel across two calls is read as one about any two, so a program approving one parcel and booking another passes a rule that a booking follows its own parcel's approval. That one call takes the value another returned is a flow rule with `only`; a policy instance per value, the parametric monitoring of Roşu and Chen 2012, is not read, and a proxy reads no pending state: MCP 2026-07-28 has no session, and a proxy sees no end of a task.
- **A call is given no input.** A server may answer a call by asking for input: an elicitation, a sampling, its roots, or an interaction it waits on, MCP 2026-07-28's `input_required`. The runner and the proxy give none and forward none, so the call fails as a tool error, which an error block takes or which ends the run. A value a user or a model supplied there would reach the call held to no contract the program was proven against, the leak a stop answered by a user would be.
- **One client, over stdio.** The proxy serves the agent that starts it, and its flow rules read the values of that one process. A client reaching servers over Streamable HTTP alone cannot put it in front of one, and a proxy served over HTTP has no session to key provenance by: MCP 2026-07-28 leaves state across calls to handles a server mints as tool arguments, which would change the signatures the proxy lists. Refused until a client reaching servers over HTTP alone, with tools that write and text it does not trust, needs it.
- **Search bounds.** Six calls and tests a path by default, and the first 16 bindings of a call.
# Results
Every count below is a row of a study file, and the command beside it fails when this code no longer produces it. Times depend on the machine and are not recorded.
## Parcel returns
```
uv run python tools/case.py examples/parcels --check docs/studies/parcels.json
```
`examples/parcels` holds ten tools: a lookup returning a parcel's state, weight, country and contact, one tool per state, two of them split by weight, a freight approval, a customs form, a contact check and a notice. Each task is planned, then verified by valgebra alone.
| task | program | links proven | stops | cells (undecided) |
| --- | --- | --- | ---: | --- |
| settle a parcel | strong | 18 of 18 | 0 | 18 (0) |
| settle a parcel, tools may fail | weak | 22 of 22 | 2 | 18 (0) |
| settle a parcel, freight approved first | strong | 24 of 24 | 0 | 18 (0) |
| return a parcel | weak | 9 of 9 | 1 | 14 (0) |
| customs for a parcel | weak | 3 of 3 | 1 | 11 (0) |
| notify a parcel's contact | strong | 3 of 3 | 0 | 11 (0) |
| notify a parcel's contact, verified addresses only | strong | 4 of 4 | 0 | 11 (0) |
| notify a parcel's contact, types mined from observed calls | strong | 4 of 4 | 0 | 11 (0) |
- Settling a parcel branches five ways on its state and weight. When tools may fail it retries the lookup and the idempotent calls and stops where a booking fails, since retrying a booking may book twice. Under the policy that freight is approved first, it approves right before the freight booking, on that path alone.
- A weak program's stops name what they leave: `lost`, `in_transit` and `returned` for a return, `IT`, `FR` and `DE` for a customs form.
- A notice goes to the contact as the sender wrote it, unless a flow rule or the types mined from observed calls route it through the contact check; under mined types the plan names both bindings that rest on them.
- `tests/test_run.py`, `tests/test_outcomes.py` and `tests/test_policy.py` run these programs against tools answering with values drawn from their own output schemas, and failing three times in ten: no contract is broken, and the monitor reports every policy violation the verifier refutes. Enforced, a run never makes the call a policy forbids, never sends an argument record outside the input set and never binds a result outside its contract.
## Libraries of growing size
```
uv run python tools/bench.py --check docs/studies/bench.json
```
Synthetic libraries of 8 to 256 tools hold a planted chain of four beside tools no held value can call and tools whose results nothing reads, each size in three tool orders. At every size the reachability pruning leaves 5 predicates and 12 cells, and the strong program is found and proven, 5 of 5 links.
# Reference
# The Python API
The names valgebra-planning promises a Python caller: each public module, the names its `__all__` holds, and the two modules that need the `mcp` extra. [The command line]() has a page of its own, and what each answer means is [the method]()'s.
## Import a name from its module
```
from valgebra_planning.contracts import read_contract, read_task
from valgebra_planning.planner import plan
from valgebra_planning.program import render
from valgebra_planning.verify import verify
find = read_contract(
{
"name": "find_parcel",
"inputSchema": {
"type": "object",
"properties": {"tracking": {"type": "string", "pattern": "^[A-Z]{2}[0-9]{9}[A-Z]{2}$"}},
"required": ["tracking"],
},
"outputSchema": {
"type": "object",
"properties": {"parcel_id": {"type": "integer", "minimum": 1}},
"required": ["parcel_id"],
},
}
)
contracts = {"find_parcel": find}
task = read_task(
"find a parcel",
{"tracking": {"type": "string", "pattern": "^[A-Z]{2}[0-9]{9}[A-Z]{2}$"}},
{"type": "integer", "minimum": 1},
)
found = plan(contracts, task)
assert found.strong and found.program is not None
print(render(found.program))
checked = verify(found.program, contracts, task)
print(checked.count("proven"), "of", len(checked.links), "links proven")
```
```
c1 = find_parcel(tracking=tracking)
return c1.parcel_id
2 of 2 links proven
```
The tracking code lies inside `find_parcel`'s argument, and the parcel identifier its output guarantees inside the goal.
**The package itself exports nothing**, and `valgebra_planning.__all__` is empty. Three modules define a function of their own name, `run`, `verify` and `proxy`, so a function exported from the package would hide its module there; `from valgebra_planning import *` would bind `plan`, `run` and `verify` over a caller's own names; and an export of `proxy` or `servers` would import the `mcp` SDK on every import of the package, with or without the extra.
## The public names
| module | names | needs |
| --- | --- | --- |
| `valgebra_planning.contracts` | `Contract`, `Slot`, `Task`, `read_contract`, `read_task` | |
| `valgebra_planning.program` | `Block`, `Branch`, `Call`, `Const`, `For`, `Next`, `Ref`, `Return`, `Stop`, `render`, `steps` | |
| `valgebra_planning.planner` | `DEPTH`, `Plan`, `Uncovered`, `plan`, `predicates` | |
| `valgebra_planning.cells` | `Abstraction`, `Cell`, `Predicate`, `Status`, `abstract`, `gather` | |
| `valgebra_planning.verify` | `Gap`, `Link`, `Verdict`, `Verification`, `verify` | |
| `valgebra_planning.critic` | `Critique`, `ProgramError`, `critique`, `read_program` | |
| `valgebra_planning.codemode` | `Repair`, `feedback`, `repair`, `stub`, `stubs` | |
| `valgebra_planning.run` | `Refusal`, `Run`, `ToolError`, `blame`, `run` | |
| `valgebra_planning.policy` | `Monitor`, `Policy`, `Reach`, `Transition`, `read_policy` | |
| `valgebra_planning.flows` | `Flow`, `read_flow` | |
| `valgebra_planning.mining` | `SlotKey`, `Types`, `infer_outputs`, `mine` | |
| `valgebra_planning.library` | `Library`, `Problem`, `read_library` | |
| `valgebra_planning.privilege` | `Change`, `Rule`, `Update`, `allowed`, `as_policy`, `describe`, `read_privileges`, `read_rules`, `updates` | |
| `valgebra_planning.vacuity` | `Certainty`, `Finding`, `vacuities` | |
| `valgebra_planning.servers` | `connect`, `read_server`, `run_on_server` | the `mcp` extra |
| `valgebra_planning.proxy` | `Gate`, `proxy`, `serve` | the `mcp` extra |
A module's `__all__` holds what a caller calls, the types those calls take and return, and the defaults a caller passes, `DEPTH` among them. Every other name a module defines serves the package's other modules and is not promised. `valgebra_planning._valgebra`, the one module importing valgebra and valgebra-jsonschema, and `valgebra_planning.cli`, the command line's, are not public.
## What holds the table
`tests/test_api.py` holds the table to the package:
- each public module's `__all__` to its row, and the public modules to the rows;
- each listed name to a definition in its own module, not one it imports;
- each type a public function, class or method names in its signature to a public name, or to one valgebra, valgebra-jsonschema or the standard library defines;
- the `needs` column to the modules that import `mcp` when they are imported.
**The limit.** Under `0.0.x` a release may change any public name; the table says which names a release can break, not that it will not. The changelog records each change.
## Reference
Each public module's names, read from their docstrings.
### valgebra\_planning.contracts
A tool's contract read as slots, and a task read as inputs and a goal.
An agent fills each argument of a call from a value it holds, so a tool is read as its argument slots, one per property of its input schema, and its result slots, one per field its output schema guarantees. Each slot is a set valgebra decides over, compiled by valgebra-jsonschema against the tool's own schema as root. To list the slots, the walk here reads five keywords itself, `properties`, `required`, `items`, `prefixItems` and a bare `$ref`, which it resolves from the document's root; what a keyword means is the companion's, so a slot a reading yields is kept only where valgebra proves the whole schema's set inside it.
#### Slot
One value a tool takes or returns: where it sits, and the set it lies in.
`path` is the argument's name for an argument, and the field names leading to it for a result, the empty path being the whole result. `schema` is the subschema as written, which a sampler draws members from against `root`, the document it sits in; `values` is the set it compiles to.
##### tool
```
tool: str
```
##### path
```
path: tuple[str, ...]
```
##### schema
```
schema: object
```
##### values
```
values: Validator[Any]
```
##### required
```
required: bool
```
##### root
```
root: object
```
##### name
```
name: str
```
Return the slot as a program writes it: `tool.path`.
##### \_\_init\_\_
```
__init__(
tool: str,
path: tuple[str, ...],
schema: object,
values: Validator[Any],
required: bool,
root: object,
) -> None
```
#### Contract
A tool's slots, with its whole input set and whether its arguments are independent.
`plain` holds when the input schema constrains each argument on its own: each one proven inside its slot, with the required ones present, makes the record a member. Otherwise a call is accepted only once the record itself is proven inside `accepts`.
##### name
```
name: str
```
##### arguments
```
arguments: tuple[Slot, ...]
```
##### results
```
results: tuple[Slot, ...]
```
##### accepts
```
accepts: Validator[Any]
```
##### returns
```
returns: Validator[Any] | None
```
##### plain
```
plain: bool
```
##### idempotent
```
idempotent: bool = False
```
##### hints
```
hints: frozenset[str] = frozenset()
```
##### trusted
```
trusted: bool = False
```
##### inferred
```
inferred: bool = False
```
##### \_\_init\_\_
```
__init__(
name: str,
arguments: tuple[Slot, ...],
results: tuple[Slot, ...],
accepts: Validator[Any],
returns: Validator[Any] | None,
plain: bool,
idempotent: bool = False,
hints: frozenset[str] = frozenset(),
trusted: bool = False,
inferred: bool = False,
) -> None
```
##### argument
```
argument(name: str) -> Slot
```
Return the argument slot called `name`, or raise `KeyError`.
##### result
```
result(*path: str) -> Slot
```
Return the result slot at `path`, or raise `KeyError`.
#### Task
What an agent holds and what it must return.
`held` maps each variable the agent starts with to its slots, read as a result's are: the whole value and each field it guarantees. `goal` is the set the returned value must lie in, and `goal_schema` the schema it compiles from.
##### name
```
name: str
```
##### held
```
held: Mapping[str, tuple[Slot, ...]]
```
##### goal
```
goal: Validator[Any]
```
##### goal\_schema
```
goal_schema: object
```
##### \_\_init\_\_
```
__init__(
name: str,
held: Mapping[str, tuple[Slot, ...]],
goal: Validator[Any],
goal_schema: object,
) -> None
```
#### read\_contract
```
read_contract(spec: Mapping[str, Any]) -> Contract
```
Read one entry of a server's tool list into its contract.
Raises `Unsupported` for what valgebra-jsonschema refuses to read, and for an input schema whose properties it cannot list.
#### read\_task
```
read_task(
name: str, inputs: Mapping[str, object], goal: object
) -> Task
```
Read a task: the schema of each value the agent starts with, and of the goal.
### valgebra\_planning.program
A program of tool calls and type tests, and its text.
A program is a block: calls, each binding arguments to references or to constants and naming its result, then one ending. A return hands a reference back, a stop marks a value the program does not cover, and a test branches on whether a reference lies in a tool's argument, each branch a block of its own. A reference is a variable and a path of fields below it, `c1.order.status`; a constant is a JSON value, `"delivered"`.
The text reads as Python, so a program written elsewhere in that form is read back by `valgebra_planning.critic`.
#### Ref
A variable, and the fields below it: `c1.order.status` is `c1` at `order.status`.
##### variable
```
variable: str
```
##### path
```
path: tuple[str, ...] = ()
```
##### \_\_init\_\_
```
__init__(variable: str, path: tuple[str, ...] = ()) -> None
```
##### \_\_str\_\_
```
__str__() -> str
```
Return the reference as a program writes it, a key no attribute names subscripted.
A key that is no Python identifier, or is a keyword, as `a-b` or `class`, reads back only as a subscript, `x["a-b"]`, the form the critic reads it in.
#### Const
A JSON value written into a call, held as its JSON text so a program stays hashable.
##### text
```
text: str
```
##### value
```
value: Any
```
Return the value the constant holds.
##### \_\_init\_\_
```
__init__(text: str) -> None
```
##### of
```
of(value: Any) -> Const
```
Return the constant `value`, a JSON value.
##### \_\_str\_\_
```
__str__() -> str
```
#### Call
Call `tool`, each argument bound to a reference or a constant, the result `result`.
A tool may answer with an error. `retry` makes the call again until it succeeds, which only a tool that is read-only or idempotent allows; `on_error` is the block run instead of the rest, where the result is never bound.
##### tool
```
tool: str
```
##### bindings
```
bindings: tuple[tuple[str, Ref | Const], ...]
```
##### result
```
result: str
```
##### retry
```
retry: bool = False
```
##### on\_error
```
on_error: Block | None = None
```
##### \_\_init\_\_
```
__init__(
tool: str,
bindings: tuple[tuple[str, Ref | Const], ...],
result: str,
retry: bool = False,
on_error: Block | None = None,
) -> None
```
#### Return
Hand back the value of a reference: the task's goal must hold it.
##### ref
```
ref: Ref
```
##### \_\_init\_\_
```
__init__(ref: Ref) -> None
```
#### Stop
End a path the program does not cover; `ref` is the value left uncovered there.
##### ref
```
ref: Ref
```
##### \_\_init\_\_
```
__init__(ref: Ref) -> None
```
#### Branch
Branch on whether `ref` lies in a set: a tool's argument, JSON values listed, or a key.
With `key` set the set is every object holding that key, and the branch where it holds reads the fields the key opens. With `tool` empty the set is `values`, read as a JSON Schema `enum`: `1` and `1.0` are one value there. Otherwise it is the argument `argument` of `tool`.
##### ref
```
ref: Ref
```
##### tool
```
tool: str
```
##### argument
```
argument: str
```
##### then
```
then: Block
```
##### otherwise
```
otherwise: Block
```
##### values
```
values: tuple[Any, ...] = ()
```
##### key
```
key: str = ''
```
##### against
```
against: str
```
Return the set as a program writes it.
##### \_\_init\_\_
```
__init__(
ref: Ref,
tool: str,
argument: str,
then: Block,
otherwise: Block,
values: tuple[Any, ...] = (),
key: str = "",
) -> None
```
#### Next
End one iteration of a loop's body.
##### \_\_init\_\_
```
__init__() -> None
```
#### For
Run `body` once for each item of the array `ref` holds, named `item`; then `after`.
What the body calls is scoped to its iteration: `after` reads nothing of it.
##### ref
```
ref: Ref
```
##### item
```
item: str
```
##### body
```
body: Block
```
##### after
```
after: Block
```
##### \_\_init\_\_
```
__init__(
ref: Ref, item: str, body: Block, after: Block
) -> None
```
#### Block
Calls in order, then one ending; a loop's body ends in `Next`.
##### calls
```
calls: tuple[Call, ...]
```
##### end
```
end: Return | Stop | Branch | For | Next
```
##### \_\_init\_\_
```
__init__(
calls: tuple[Call, ...],
end: Return | Stop | Branch | For | Next,
) -> None
```
#### render
```
render(block: Block, indent: str = '') -> str
```
Return the program as Python-like text, one step a line.
#### steps
```
steps(block: Block) -> int
```
Return the calls and tests on the longest path of a program, error paths included.
### valgebra\_planning.planner
Programs of calls and type tests, searched over the cells.
A state maps every reference the agent holds to the cells of the set it lies in. A call is enabled when each required argument can be bound to a reference whose cells all lie inside the argument's cells, and, where the input schema relates its arguments, valgebra proves the whole record inside it. A guarded call handles a reference that only overlaps an argument: it branches on the reference lying in the argument, calls the tool on the narrowed value, and goes on with the rest in the other branch. A program is strong when every path returns a reference whose cells lie inside the goal's: strong planning under nondeterministic outcomes (Cimatti et al. 2003, Def. 2.11), the outcomes partitioned by the cells rather than listed, and a branch on a runtime type test as an observation (Bertoli et al. 2006, Def. 2.8).
The search deepens on the calls and tests along a path, so the first strong program found is a shallowest one. Where none exists within the bound, one search at the full bound lets a branch stop once its sibling returns and no continuation exists within the depth its path has left, and each stop names the cells it leaves uncovered. Every program returned is checked again by `valgebra_planning.verify.verify`, which reads neither the cells nor the search.
#### DEPTH
```
DEPTH = 6
```
#### Uncovered
A stop of a weak program: where, the reference, and the values it leaves uncovered.
`examples` holds a member of each uncovered cell that has one; `undecided` counts the uncovered cells that may be empty.
##### where
```
where: str
```
##### ref
```
ref: str
```
##### examples
```
examples: tuple[Any, ...]
```
##### undecided
```
undecided: int
```
##### \_\_init\_\_
```
__init__(
where: str,
ref: str,
examples: tuple[Any, ...],
undecided: int,
) -> None
```
#### Plan
A program for a task, whether it is strong, and what its stops leave uncovered.
`assumed` names each binding that rests on a mined semantic type or on an output schema inferred from observed calls, and each retry, which rests on its tool's errors being transient and, unless its server is trusted, on its annotations.
##### program
```
program: Block | None
```
##### strong
```
strong: bool
```
##### uncovered
```
uncovered: tuple[Uncovered, ...]
```
##### abstraction
```
abstraction: Abstraction
```
##### expanded
```
expanded: int
```
##### assumed
```
assumed: tuple[str, ...] = ()
```
##### \_\_init\_\_
```
__init__(
program: Block | None,
strong: bool,
uncovered: tuple[Uncovered, ...],
abstraction: Abstraction,
expanded: int,
assumed: tuple[str, ...] = (),
) -> None
```
#### predicates
```
predicates(
contracts: Mapping[str, Contract], task: Task
) -> list[Predicate]
```
Return every argument and the goal, and each result or input some of them may read.
A value no argument and no goal can hold is never passed on, so its cells cost the search and decide nothing; it is left out, with its reference. The sets are gathered in the order of their names, which fixes the cut: valgebra leaves some meets undecided, and which ones depends on the order the cut splits by and draws its members in, so a listing order of its own would make a library's count that order's.
#### plan
```
plan(
contracts: Mapping[str, Contract],
task: Task,
*,
depth: int = DEPTH,
seed: int = 0,
weak: bool = True,
errors: bool = False,
policies: Sequence[Policy] = (),
flows: Sequence[Flow] = (),
types: Types | None = None,
) -> Plan
```
Search a program for `task` over `contracts`: strong first, then weak if asked.
With `errors`, any tool may answer with an error, and every call is retried or given a block for it, as `valgebra_planning.verify.verify` holds with the same flag. A call is made only where valgebra proves it keeps every policy away from its bad states, and a call a policy reads is kept even where no result of it is read; a path ends, in a return or a stop, only where no policy holds a pending state. A value reaches a flow rule's sink only as `valgebra_planning.verify.verify` holds it with the same rules. With mined `types`, a value fills an argument only where their types agree, and the plan names every binding that rests on one. Raises `ValueError` for a task naming an input as a tool.
### valgebra\_planning.cells
The cells: the minterms of every set a plan reads, within each kind of JSON value.
Every slot, input and goal is a predicate on JSON values. Each predicate taken inside or outside cuts the values into cells, and each predicate is exactly a union of cells, so an inclusion between two predicates' cells implies the inclusion between the predicates: the canonical monomials of the predicates as abstract states (Graf and Saidi 1997, §2.2), the minterms of an effective Boolean algebra (D'Antoni and Veanes 2017, §2.1). The values split first into seven disjoint kinds, and a predicate cuts only the cells of the kinds it meets.
A part of a cell is dropped only where valgebra proves it empty. It is inhabited where a concrete value lies in it, or where valgebra refutes its emptiness. Every other part is kept as undecided, so it can cost a plan, never admit a wrong one. Most cuts are settled by relations between two predicates, each asked of valgebra once: a cell inside a predicate disjoint from the new one lies outside it, a cell inside a predicate below the new one lies inside it, and a cell outside a predicate above it lies outside it.
#### Status
```
Status = Literal['inhabited', 'undecided']
```
#### Predicate
A set a plan reads, with the schema it compiles from and the names standing for it.
##### names
```
names: tuple[str, ...]
```
##### values
```
values: Validator[Any]
```
##### schema
```
schema: object
```
##### root
```
root: object
```
##### \_\_init\_\_
```
__init__(
names: tuple[str, ...],
values: Validator[Any],
schema: object,
root: object,
) -> None
```
#### Cell
One minterm: a kind, the predicates it lies inside, and whether it holds a value.
The cell lies outside every predicate of its kind not in `inside`. `witness` holds a member where one is known; an inhabited cell without one was proven non-empty.
##### kind
```
kind: str
```
##### inside
```
inside: frozenset[int]
```
##### values
```
values: Validator[Any]
```
##### status
```
status: Status
```
##### witness
```
witness: tuple[Any, ...] = ()
```
##### \_\_init\_\_
```
__init__(
kind: str,
inside: frozenset[int],
values: Validator[Any],
status: Status,
witness: tuple[Any, ...] = (),
) -> None
```
#### Abstraction
The predicates of a plan and the cells they cut the JSON values into.
##### predicates
```
predicates: tuple[Predicate, ...]
```
##### cells
```
cells: tuple[Cell, ...]
```
##### asked
```
asked: int = 0
```
##### \_\_init\_\_
```
__init__(
predicates: tuple[Predicate, ...],
cells: tuple[Cell, ...],
asked: int = 0,
_members: dict[int, frozenset[int]] = dict(),
) -> None
```
##### index
```
index(name: str) -> int
```
Return the predicate a name stands for, or raise `KeyError`.
##### cells\_of
```
cells_of(predicate: int) -> frozenset[int]
```
Return the cells lying inside a predicate.
##### members
```
members(cell: int) -> tuple[Any, ...]
```
Return the values a cell holds where a predicate it lies inside lists them all.
Elsewhere, the member found for it, if any.
##### undecided
```
undecided(cells: Iterable[int]) -> int
```
Return how many of `cells` may be empty.
#### gather
```
gather(
entries: Iterable[
tuple[str, Validator[Any], object, object]
],
) -> list[Predicate]
```
Merge named sets valgebra holds equal into one predicate each, keeping order.
Two schemas differing in a description, a title or a default compile to one set, and a predicate per spelling would only ask each relation again; the first spelling stays, to draw members from.
#### abstract
```
abstract(
predicates: Sequence[Predicate], *, seed: int = 0
) -> Abstraction
```
Cut the JSON values into the cells of `predicates`.
### valgebra\_planning.verify
Every link of a program, asked of valgebra alone.
A link is an inclusion a program rests on: a reference inside the argument it fills, a call's whole argument record inside the tool's input set where the arguments are related, and the returned reference inside the goal. Each is asked of valgebra with the set the reference lies in at that point of the program, narrowed by every test on the way there, and nothing else, not the cells, not the search: the belief execution along a path (Bertoli et al. 2006, Def. 3.4), each reference's set read apart from the others'. A program whose every link is proven and on which no path stops is a strong solution, applicable at each call and inside the goal at the end of each path (Bertoli et al. 2006, Thm. 3.5). A refuted link carries a value outside the inclusion where one is found among the examples given and the values drawn from the reference's own schema. A value found that way refutes an undecided link too, since a concrete member is a proof.
#### Verdict
```
Verdict = Literal['proven', 'refuted', 'undecided']
```
#### Link
One inclusion a program rests on, where it sits, and what valgebra says of it.
`where` names the branches leading to it, `then` and `else` joined by dots, the empty string being the top. `counterexample` holds the value refuting it, when one is found.
##### where
```
where: str
```
##### claim
```
claim: str
```
##### verdict
```
verdict: Verdict
```
##### counterexample
```
counterexample: tuple[Any, ...] = ()
```
##### assumed
```
assumed: tuple[str, ...] = ()
```
##### \_\_init\_\_
```
__init__(
where: str,
claim: str,
verdict: Verdict,
counterexample: tuple[Any, ...] = (),
assumed: tuple[str, ...] = (),
) -> None
```
#### Gap
A path the program stops on, and the reference it leaves uncovered there.
##### where
```
where: str
```
##### ref
```
ref: str
```
##### \_\_init\_\_
```
__init__(where: str, ref: str) -> None
```
#### Verification
The links of a program and the gaps it leaves.
##### links
```
links: tuple[Link, ...]
```
##### gaps
```
gaps: tuple[Gap, ...]
```
##### proven
```
proven: bool
```
Return whether every link is proven and no path stops.
##### \_\_init\_\_
```
__init__(
links: tuple[Link, ...], gaps: tuple[Gap, ...]
) -> None
```
##### count
```
count(verdict: Verdict) -> int
```
Return how many links read `verdict`.
#### verify
```
verify(
program: Block,
contracts: Mapping[str, Contract],
task: Task,
*,
examples: Mapping[str, Sequence[Any]] | None = None,
seed: int = 0,
errors: bool = False,
policies: Sequence[Policy] = (),
flows: Sequence[Flow] = (),
) -> Verification
```
Ask every link of `program` of valgebra, for `task` over `contracts`.
`examples` maps a reference, written as the program writes it, to values it may hold, tried first in search of a counterexample. With `errors`, any tool may answer with an error, and a call neither retried nor given an error block leaves that path uncovered. A retry is accepted only for a tool that is read-only or idempotent, since calling twice must act as calling once; it ends under fairness, the strong cyclic reading (Cimatti et al. 2003, Def. 2.10). Each policy adds a link at the end of every path: proven where no bad state can be reached there, refuted where one surely is, undecided where one possibly is. Each flow rule adds a link for every value from one of its sources bound to its sink, and, where implicit flows are read, for every call to the sink under a test on such a value. Raises `ValueError` for a task naming an input as a tool, whose source no name could tell apart.
### valgebra\_planning.critic
A program written elsewhere, read from Python, verified, and answered with a critique.
A language model proposes, a sound critic checks (Kambhampati et al. 2024, §3.1): the program's every link is asked of valgebra by `valgebra_planning.verify.verify`, under the rules the task is held to, and the answer names each link that is not proven, the value that refutes it where one is found, and what the author can change: for an argument a value only overlaps, the test that makes the call safe; for a rule, the order, the source or the error block it needs.
The reader takes the Python an agent writes against typed tool APIs: a function or a bare block of statements; `c1 = find_parcel(tracking=tracking)` or `tools.find_parcel(...)`, awaited or not; fields as attributes or as string subscripts; `return`; `stop(ref)`; and an argument as a value the program holds or a JSON constant (`state="delivered"`); `if`/`elif`/`else` testing a value against a tool's argument (`ref in tool.argument`) or against listed constants (`==`, `!=`, `in`, `not in`), or a key of a record (`"field" in ref`); `retry(tool(...))`; and `try:` around one call with `except ToolError:`; `for item in ref:` over an array, whose body ends each iteration where its statements run out and never returns; and `pass`. Anything else is refused by line, never skipped.
#### ProgramError
Bases: `ValueError`
A program the reader does not read, with the line that stops it.
#### Critique
A proposed program, its verification, and the critique to hand back to its author.
##### program
```
program: Block
```
##### verification
```
verification: Verification
```
##### notes
```
notes: tuple[str, ...]
```
##### accepted
```
accepted: bool
```
Return whether every link is proven and no path stops.
##### \_\_init\_\_
```
__init__(
program: Block,
verification: Verification,
notes: tuple[str, ...],
) -> None
```
#### read\_program
```
read_program(source: str) -> Block
```
Read a program from Python source: one function, or a block of statements.
Raises `ProgramError` naming the line of a construct it does not read.
#### critique
```
critique(
source: str,
contracts: Mapping[str, Contract],
task: Task,
*,
examples: Mapping[str, Sequence[Any]] | None = None,
errors: bool = False,
policies: Sequence[Policy] = (),
flows: Sequence[Flow] = (),
types: Types | None = None,
) -> Critique
```
Read, verify and critique a program proposed for `task` under the rules it is held to.
`errors`, `policies` and `flows` are held as `valgebra_planning.verify.verify` holds them. Mined `types` decide nothing: a binding crossing two types the observed calls show is a note, and the program is accepted or not on its links alone. Raises `ProgramError` for a program the reader does not read.
### valgebra\_planning.codemode
Typed tool stubs for a model to write a program against, and the loop that repairs it.
In code mode a model writes a program against typed tool APIs rather than calling tools one by one. `stubs` gives those APIs as Python: one function a tool, every argument by name, its type hint the kind its schema names, and its docstring the tool's own input and output JSON Schemas, since a pattern or a bound has no Python type and the critic holds the program to the schemas. `repair` is the loop of a model that proposes and a sound critic that checks, the critique handed back as the next prompt (Kambhampati et al. 2024, §3.2): a program is critiqued, and its critique handed back for the next proposal, until it is accepted or the rounds run out. The model is any callable from the last critique to a program, so no model is part of this package.
#### Repair
The rounds a program took: each source proposed and its critique, or why it was not read.
##### rounds
```
rounds: tuple[tuple[str, Critique | str], ...]
```
##### accepted
```
accepted: bool
```
Return whether the last program proposed was accepted.
##### \_\_init\_\_
```
__init__(
rounds: tuple[tuple[str, Critique | str], ...],
) -> None
```
#### stub
```
stub(contract: Contract) -> str
```
Return a tool's stub: its signature, and its input and output schemas as its docstring.
#### stubs
```
stubs(contracts: Mapping[str, Contract]) -> str
```
Return the stubs of every tool, after the preamble stating the language a program uses.
#### feedback
```
feedback(checked: Critique | str) -> str
```
Return a critique as the text handed back to the model: each note, a line.
#### repair
```
repair(
propose: Callable[[str | None], str],
contracts: Mapping[str, Contract],
task: Task,
*,
rounds: int = 3,
**rules: Any,
) -> Repair
```
Propose, critique and hand the critique back, until a program is accepted or `rounds` end.
`propose` takes the last critique as text, None the first time, and returns a program's source. The `rules` are those `valgebra_planning.critic.critique` holds a program to.
### valgebra\_planning.run
A program run on concrete values, each argument and result checked against its contract.
The runner calls the tools a program names with the values the program binds, takes each branch by testing the value it reads, and checks every argument record against the tool's input set, every policy's step before the call, every result against its output set and the returned value against the goal. It fails closed: a broken check stops the run before the call is made, the result bound or the value returned, and the run names the check. A field the program reads and the value it holds lacks ends the run, named as a check too, since no value can be passed on in its place. A proof of the program rests on the contracts; a tool that answers outside its own is what a run must not pass on. With `enforce=False` a break is recorded and the run goes on, so one run reports every break it meets: a diagnosis, never a guard.
#### ToolError
Bases: `Exception`
A tool answered with an error: an MCP result with `isError` set.
#### Refusal
Which check ended a run: `arguments`, `policy`, `result`, `goal`, `error` or `read`.
`tool` is the tool the check was on, where it was on one.
##### check
```
check: str
```
##### tool
```
tool: str | None = None
```
##### retried
```
retried: bool = False
```
##### \_\_init\_\_
```
__init__(
check: str,
tool: str | None = None,
retried: bool = False,
) -> None
```
#### Run
What a run returned or where it stopped, and every contract it broke on the way.
##### value
```
value: Any
```
##### stopped
```
stopped: str | None
```
##### broken
```
broken: tuple[str, ...]
```
##### refused
```
refused: str | None = None
```
##### why
```
why: Refusal | None = None
```
##### \_\_init\_\_
```
__init__(
value: Any,
stopped: str | None,
broken: tuple[str, ...],
refused: str | None = None,
why: Refusal | None = None,
) -> None
```
#### run
```
run(
program: Block,
contracts: Mapping[str, Contract],
task: Task,
inputs: Mapping[str, Any],
tools: Mapping[str, Callable[..., Any]],
*,
policies: Sequence[Policy] = (),
enforce: bool = True,
) -> Run
```
Run `program` on `inputs`, calling `tools` by name, checking every contract.
Each policy is stepped on a call before it is made, and reaching a bad state is a broken check like a broken contract, as is a run ending, in a return or a stop, in a pending one. With `enforce`, the default, the first broken check ends the run, named in `Run.refused`; without it every break is recorded and the run goes on. Raises `ValueError` for a task naming an input as a tool.
#### blame
```
blame(
result: Run,
contracts: Mapping[str, Contract],
*,
proven: bool,
) -> str | None
```
Return why a run broke, given whether its program was proven; None if nothing broke.
A proven program breaks at run time only where something it rests on fails: a tool's result outside the output schema its server declared is the server's, one outside a schema shaped from observed calls is that assumption's, and an error a retry could not outlast is the fairness a retry assumes. An argument record, a policy or a returned value breaking in a proven program is a check the verification proved: a defect of this package or of valgebra. An unproven program's break is its own link's.
### valgebra\_planning.policy
Policies over the calls a program makes: automata whose guards are valgebra sets.
A policy is a symbolic automaton over call events (D'Antoni and Veanes 2017, Def. 1): a transition fires on a call to its tool whose argument record lies in its guard, a JSON Schema the companion reads into a set. Some states are bad: reaching one is a violation, and a bad state is never left. Some are pending: a path may pass through one and must not end in one, an obligation still open, as a notice owed after a booking. A call no guard of the current state matches keeps that state. It states what a domain policy says in prose (τ-bench, Yao et al. 2024, §3), and what a trace rule checks one prefix at a time (AgentLTL, Elkoussy and Perez 2026, §3.4), as a set a whole program is decided against before it runs.
Statically, a program's every path steps the automaton with the argument records it may pass: a guard is taken surely where valgebra proves the record inside it, never where it proves them disjoint, and possibly otherwise. A path ending in a bad or a pending state surely refutes the program, possibly leaves it undecided, and no path ending in one proves it; a bad state never left makes ending in one the same as reaching one. Every path of a program ends, a loop's after any number of items, so an obligation is decided over the whole program before it runs, where a monitor reading a run's prefix cannot decide it (Bauer et al. 2011, Def. 3.4). At run time the same automaton is a monitor stepping on concrete records, and reading the pending states when the run ends.
A policy reads one program's calls in order. It carries no value from one call to another, so a rule about the same parcel across two calls is read as a rule about any two calls: a program approving one parcel and booking another passes a rule that a booking follows its own parcel's approval. A rule that a call takes a value another returned is a flow rule with `only` (`valgebra_planning.flows`). A policy instance per value, a parametric property (Roşu and Chen 2012, Def. 12), is not read.
#### Reach
```
Reach = Literal['never', 'possibly', 'surely']
```
#### Transition
From `source` to `target` on a call to `tool` whose arguments lie in `guard`.
With `hint` set and `tool` empty, the call is to any tool whose annotations set that hint, `destructiveHint` or another: a hint its server gives, untrusted unless the server is.
##### source
```
source: str
```
##### tool
```
tool: str
```
##### guard
```
guard: Validator[Any]
```
##### target
```
target: str
```
##### hint
```
hint: str = ''
```
##### \_\_init\_\_
```
__init__(
source: str,
tool: str,
guard: Validator[Any],
target: str,
hint: str = "",
) -> None
```
##### reads
```
reads(tool: str, hints: frozenset[str]) -> bool
```
Return whether a call to `tool`, whose annotations set `hints`, is one it reads.
#### Policy
An automaton over call events: where it starts, its bad states and its pending ones.
##### name
```
name: str
```
##### initial
```
initial: str
```
##### bad
```
bad: frozenset[str]
```
##### transitions
```
transitions: tuple[Transition, ...]
```
##### pending
```
pending: frozenset[str] = frozenset()
```
##### \_\_init\_\_
```
__init__(
name: str,
initial: str,
bad: frozenset[str],
transitions: tuple[Transition, ...],
pending: frozenset[str] = frozenset(),
) -> None
```
##### tools
```
tools() -> frozenset[str]
```
Return every tool a transition names.
##### hints
```
hints() -> frozenset[str]
```
Return every annotation hint a transition reads.
##### step
```
step(
states: frozenset[str],
tool: str,
record: Validator[Any],
hints: frozenset[str] = frozenset(),
) -> frozenset[str]
```
Return the states the automaton may be in after a call whose record lies in `record`.
A transition taken surely leaves its source; one taken possibly adds its target and keeps the source, as does a call no guard of the state surely matches. A bad state is never left.
##### reach
```
reach(
states: frozenset[str], *, ended: bool = False
) -> Reach
```
Return whether a bad state is held, or a pending one where a path ends: surely if all.
A path that has not ended may pass through a pending state.
#### Monitor
A policy stepped on concrete calls, as a run makes them.
##### policy
```
policy: Policy
```
##### state
```
state: str = ''
```
##### violations
```
violations: list[str] = field(default_factory=list)
```
##### \_\_init\_\_
```
__init__(
policy: Policy,
state: str = "",
violations: list[str] = list(),
) -> None
```
##### \_\_post\_init\_\_
```
__post_init__() -> None
```
##### observe
```
observe(
tool: str,
arguments: Mapping[str, Any],
hints: frozenset[str] = frozenset(),
) -> bool
```
Step on one call; return whether it reached a bad state, which it never leaves.
##### ended
```
ended() -> bool
```
Return whether the run ends in a pending state: an obligation it leaves open.
#### read\_policy
```
read_policy(spec: Mapping[str, Any]) -> Policy
```
Read a policy: `name`, `initial`, `bad` states, `transitions` and `pending`.
Each transition names its `from` and `to` states and its `tool`, or the annotation `hint` a tool must set, and optionally the JSON Schema its `arguments` record must meet, every record where it names none.
### valgebra\_planning.flows
Where a value came from, and which arguments it may reach.
A program's control flow is fixed before any tool runs, so the origin of every value it passes on is known from the program alone: a task input, or the result of a named tool. A flow rule names untrusted sources and a sink argument. A value from a source reaches the sink only where valgebra proves it inside the rule's endorsed set, when the rule names one, the narrowing a test or a sanitizing tool performs; otherwise it does not reach it at all. This is the integrity half of information-flow control for agents, a value's provenance as its capability (CaMeL, Debenedetti et al. 2025, §5.3) and its integrity as its label (FIDES, Costa et al. 2025, §4.1), and a privilege rule over arguments (Progent, Shi et al. 2025, §4.1), decided over sets rather than checked per value.
With `implicit`, a sink call made under a test on a value from a source is refused too: which branch runs carries that value's influence, the dependency on a condition that CaMeL's STRICT mode adds (Debenedetti et al. 2025, §5.4).
With `only`, the rule holds every origin but its sources: a value from a tool it does not name, from a task input it does not name, or written into the program as a literal reaches the sink only inside the endorsed set. That is integrity as provenance: an identifier must come from the tool that retrieved it, on every path, which refutes the identifier a model makes up to pass an authentication step, the integrity leak (Sah et al. 2026, §4.3).
#### Flow
Values from the origins the rule holds reach `tool.argument` only inside `endorsed`.
It holds `sources`, or, with `only`, every origin but them.
##### name
```
name: str
```
##### sources
```
sources: frozenset[str]
```
##### tool
```
tool: str
```
##### argument
```
argument: str
```
##### endorsed
```
endorsed: Validator[Any] | None
```
##### implicit
```
implicit: bool
```
##### only
```
only: bool = False
```
##### sink
```
sink: str
```
Return the sink as a program writes it.
##### \_\_init\_\_
```
__init__(
name: str,
sources: frozenset[str],
tool: str,
argument: str,
endorsed: Validator[Any] | None,
implicit: bool,
only: bool = False,
) -> None
```
##### holds
```
holds(origin: str | None) -> bool
```
Return whether a value from `origin` is held to the rule; None is a literal.
#### read\_flow
```
read_flow(spec: Mapping[str, Any]) -> Flow
```
Read a flow rule from its JSON form.
It holds `name`, `sources`, `sink` as `tool.argument`, and optionally the `endorsed` JSON Schema, `implicit` and `only`. A source is a tool's name or a task input's.
### valgebra\_planning.mining
Semantic types mined from observed calls, stated as assumptions.
Two slots with the same schema are one set to valgebra, so the planner may pass a customer's name where a ticket's subject goes. Observed calls tell them apart: a value a tool returned that a later call took as an argument links the two slots, and slots linked by any shared value form one semantic type (APIphany, Guo et al. 2022, §4). A binding across two types is then refused, which narrows the planner's choices to what the observations show.
A mined type is an assumption, never a proof: the verifier reads none, every link of a program stays valgebra's, and a plan names each binding that relied on one. A slot never observed carries no type and is bound as its set alone allows.
#### SlotKey
```
SlotKey = tuple[str, str]
```
#### Types
The semantic type of every slot seen in the observations.
##### of
```
of: Mapping[SlotKey, int]
```
##### \_\_init\_\_
```
__init__(of: Mapping[SlotKey, int]) -> None
```
##### agree
```
agree(one: SlotKey, other: SlotKey) -> bool
```
Return whether two slots may be bound together: one is untyped, or both share one.
##### typed
```
typed(one: SlotKey, other: SlotKey) -> bool
```
Return whether both slots carry a type, so binding them rests on the observations.
#### mine
```
mine(
observed: Iterable[Mapping[str, Any]],
contracts: Mapping[str, Contract],
) -> Types
```
Return the semantic types the observed calls show.
Each observation is `{"tool": name, "arguments": {...}, "result": ...}`. Every argument and every result field a contract names is a slot; two slots holding one value, under JSON equality, are one type.
#### infer\_outputs
```
infer_outputs(
observed: Iterable[Mapping[str, Any]],
listing: Iterable[Mapping[str, Any]],
) -> dict[str, dict[str, Any]]
```
Return an output schema for each listed tool declaring none, shaped from its results.
An inferred schema is an assumption, as a mined type is: a contract carrying one is marked `valgebra_planning.contracts.Contract.inferred`, and every link and binding resting on it names it.
### valgebra\_planning.library
A library on disk: a server's tool list, the tasks over it and the rules each is held to.
A library is a directory. `tools.json` holds a server's `tools/list` result, `{"tools": [...]}`, and `"trusted": true` where the server's annotations are trusted. `tasks.json` holds `{"tasks": [...]}`, each task its `name`, the JSON Schema of each input in `inputs` and of the `goal`, and the rules it names: `errors` (any tool may fail), `policies` and `flows` by name, and `types`, the file of observed calls its types are mined from; a tool listed without an `outputSchema` gets one shaped from its results in those observed calls, an assumption (`valgebra_planning.mining.infer_outputs`). `policies.json` and `flows.json` hold the rules a task names, as `valgebra_planning.policy.read_policy` and `valgebra_planning.flows.read_flow` read them.
#### Problem
A task and the rules a program for it is held to.
##### task
```
task: Task
```
##### errors
```
errors: bool = False
```
##### policies
```
policies: tuple[Policy, ...] = ()
```
##### flows
```
flows: tuple[Flow, ...] = ()
```
##### types
```
types: Types | None = None
```
##### \_\_init\_\_
```
__init__(
task: Task,
errors: bool = False,
policies: tuple[Policy, ...] = (),
flows: tuple[Flow, ...] = (),
types: Types | None = None,
) -> None
```
#### Library
The tools of a library, by name, and its problems, in the order the file lists them.
##### tools
```
tools: Mapping[str, Contract]
```
##### problems
```
problems: tuple[Problem, ...]
```
##### policies
```
policies: Mapping[str, Policy] = field(default_factory=dict)
```
##### flows
```
flows: Mapping[str, Flow] = field(default_factory=dict)
```
##### \_\_init\_\_
```
__init__(
tools: Mapping[str, Contract],
problems: tuple[Problem, ...],
policies: Mapping[str, Policy] = dict(),
flows: Mapping[str, Flow] = dict(),
) -> None
```
##### problem
```
problem(name: str) -> Problem
```
Return the problem whose task is `name`; raise `KeyError` naming it otherwise.
#### read\_library
```
read_library(
directory: Path,
tools: Mapping[str, Contract] | None = None,
) -> Library
```
Read a library directory; a rule a task names and the directory lacks is a `KeyError`.
`tools`, read from a live server, replaces the directory's `tools.json`. A task naming an input as a tool is a `ValueError`.
### valgebra\_planning.privilege
Privilege policies in Progent's format, read as valgebra sets (Shi et al. 2025, §4.1).
A policy maps each tool to its rules, `[priority, effect, condition, fallback]`: effect 0 allows and 1 forbids, and the condition maps an argument to the JSON Schema its value must meet or to a regular expression a string value must match from its start. A condition checks only the arguments a call passes. Rules are tried by priority, a forbidding rule before an allowing one of the same priority, and the first whose condition holds decides; a call no rule matches, and a call to a tool the policy names no rule for, is denied. Within one priority that is the order Progent applies a policy in (Shi et al. 2025, §4.2, Alg. 2), which reads no priority. A rule asking the user (fallback 2) is read as denied, the reading that admits no call the user did not approve.
The calls a policy allows to a tool are then a set: each allowing rule's condition, minus the conditions of every rule tried before it, joined. Progent asks Z3 whether an update narrows a policy, one argument and one rule a tool at a time; here the question is an inclusion between two such sets, every rule and every argument at once, which valgebra decides, refutes with a call that one policy allows and the other does not, or leaves undecided.
#### Change
```
Change = Literal['narrowing', 'expansion', 'undecided']
```
#### Rule
One rule of a tool: its priority, whether it allows, and the condition as a schema.
##### priority
```
priority: int
```
##### allows
```
allows: bool
```
##### condition
```
condition: dict[str, Any]
```
##### \_\_init\_\_
```
__init__(
priority: int, allows: bool, condition: dict[str, Any]
) -> None
```
#### Update
Whether a new policy narrows an old one for a tool, and a call showing an expansion.
##### tool
```
tool: str
```
##### change
```
change: Change
```
##### witness
```
witness: tuple[Any, ...] = ()
```
##### \_\_init\_\_
```
__init__(
tool: str, change: Change, witness: tuple[Any, ...] = ()
) -> None
```
#### read\_rules
```
read_rules(
rules: Iterable[Sequence[Any]],
) -> tuple[Rule, ...]
```
Read a tool's rules in the order they are tried: by priority, forbidding first.
#### allowed
```
allowed(rules: Sequence[Rule]) -> Validator[Any]
```
Return the argument records the rules allow: each allowing one's, minus those tried first.
#### read\_privileges
```
read_privileges(
policy: Mapping[str, Iterable[Sequence[Any]]],
) -> dict[str, tuple[Rule, ...]]
```
Read a policy in Progent's format: each tool's rules, in the order they are tried.
#### updates
```
updates(
old: Mapping[str, Sequence[Rule]],
new: Mapping[str, Sequence[Rule]],
) -> list[Update]
```
Return, for each tool the new policy names, whether it narrows the old policy's calls.
A narrowing is applied without asking, and an expansion needs approval, as Progent has it (Shi et al. 2025, §4.3).
#### as\_policy
```
as_policy(
name: str,
privileges: Mapping[str, Sequence[Rule]],
tools: Iterable[str],
) -> Policy
```
Return the privilege policy as an automaton the verifier, planner and runner read.
A call outside a tool's allowed set reaches the bad state `denied`; a tool the policy names no rule for is denied every call.
#### describe
```
describe(update: Update) -> str
```
Return an update as a line: the tool, the change, and the call showing an expansion.
### valgebra\_planning.vacuity
Specifications that hold for a trivial reason, decided over a library's sets.
A goal no value meets makes every task over it unsolvable, and one every value meets makes any program a solution; a policy transition whose guard no argument record of its tool meets never fires, and a policy whose bad and pending states no transition that can fire reaches is never violated; a flow rule whose endorsed set misses the sink's argument lets nothing through, and one that holds it refuses nothing. Each is a specification satisfied vacuously (Kupferman and Vardi 1999, Def. 2), a check that passes without testing what its author meant, and each is a set question valgebra decides: emptiness, inclusion, a meet.
The cheap question is asked first: values drawn from a schema are tried for membership, and a member found is a proof the set is inhabited, so valgebra is asked only where none is. A question valgebra leaves undecided is reported as undecided, never as vacuous.
#### Certainty
```
Certainty = Literal['proven', 'undecided']
```
#### Finding
A specification holding vacuously, where it is written, and whether valgebra proves it.
##### where
```
where: str
```
##### finding
```
finding: str
```
##### certainty
```
certainty: Certainty
```
##### \_\_init\_\_
```
__init__(
where: str, finding: str, certainty: Certainty
) -> None
```
#### vacuities
```
vacuities(library: Library) -> list[Finding]
```
Return every specification of `library` that holds vacuously, or may.
### valgebra\_planning.servers
Tools read from a live MCP server, and a program run against it.
`read_server` pages through a server's `tools/list` and reads each tool into its contract, as `valgebra_planning.contracts.read_contract` reads a listing on disk. `run_on_server` runs a program with `valgebra_planning.run.run`, each call a `tools/call` through the client: the result's `structuredContent` is the value a call returns, an `isError` result is a `valgebra_planning.run.ToolError`, and a tool returning no structured content returns the text of its content blocks. A call the server answers with a protocol error is a tool error too, and so is one asking for input (MCP 2026-07-28's `input_required`: a sampling, an elicitation, the roots, or an interaction it waits on): the client gives none, so no value a program did not hold reaches a call.
Requires the `mcp` extra. The runner is synchronous and the client asynchronous, so the run goes on a worker thread and each call is sent to the client's event loop.
#### connect
```
connect(server: str) -> Client
```
Return a client for a server: a URL is Streamable HTTP, anything else a stdio command.
The command is split as a POSIX shell splits it (`shlex.split`), on Windows as well: a backslash escapes the character after it, so a Windows path is passed quoted, as `shlex.quote` quotes it, the way pre-commit quotes the interpreter in a hook's `entry`.
#### read\_server
```
read_server(client: Client) -> dict[str, Contract]
```
Return the contract of every tool the server lists, by name, every page read.
#### run\_on\_server
```
run_on_server(
program: Block,
contracts: Mapping[str, Contract],
task: Task,
inputs: Mapping[str, Any],
client: Client,
*,
policies: Sequence[Policy] = (),
enforce: bool = True,
) -> Run
```
Run `program` against the server `client` is connected to, failing closed.
### valgebra\_planning.proxy
An MCP server in front of another, holding every call to the contracts, policies and flows.
The proxy lists the upstream server's tools as they are, and answers each `tools/call` only after checking it, as the fail-closed runner checks a call: the argument record against the tool's input set, each policy's step, and, the call forwarded, the result against its output set. A check that breaks answers the call with a tool error naming it, as Progent's proxy mode answers a denied call with its fallback message (Shi et al. 2025, §4.1, §7), so the agent can try another way; nothing breaking it reaches the upstream server or the agent.
A flow rule is held by provenance read from values: the proxy sees values, not a program's references, so an argument equal, as one JSON value, to a value an untrusted tool returned is taken as coming from it, and refused unless it lies in the rule's endorsed set. A rule with `only` refuses an argument equal to no value its sources returned: an identifier not retrieved earlier in the proxy's process, the strict grounding gate (Sah et al. 2026, §4.8). Both are assumptions: a value equal by chance to an untrusted one is refused with it, and one equal by chance to a retrieved one passes, and a value the agent transforms, upper-cased, encoded or cut, equals none it was returned and passes: a flow rule here holds against no attacker that adapts, where the contract and policy checks hold against any. A proxy sees no task, so a value from a task input is from elsewhere. The proxy serves one client over stdio for as long as its process runs, and MCP 2026-07-28 has no session a client ends, so a policy's pending states are not read there. A call the upstream answers with a protocol error, or with a request for input, is answered with a tool error: the proxy gives no input and forwards no request for one, since a value it never checked would reach the call. Requires the `mcp` extra.
#### Gate
The checks a proxy holds each call to, and the values each untrusted tool returned.
##### contracts
```
contracts: Mapping[str, Contract]
```
##### monitors
```
monitors: list[Monitor]
```
##### flows
```
flows: Sequence[Flow]
```
##### seen
```
seen: dict[object, set[str]] = field(default_factory=dict)
```
##### \_\_init\_\_
```
__init__(
contracts: Mapping[str, Contract],
monitors: list[Monitor],
flows: Sequence[Flow],
seen: dict[object, set[str]] = dict(),
) -> None
```
##### before
```
before(tool: str, arguments: dict[str, Any]) -> str | None
```
Return why a call may not be made, or None.
##### after
```
after(tool: str, value: Any) -> str | None
```
Return why a result may not be passed on, or None; remember untrusted tools' values.
#### proxy
```
proxy(
upstream: Client,
listing: Sequence[Tool],
contracts: Mapping[str, Contract],
*,
policies: Sequence[Policy] = (),
flows: Sequence[Flow] = (),
) -> Server[Any]
```
Return an MCP server answering `listing` through `upstream`, every call checked.
#### serve
```
serve(
upstream: Client,
*,
policies: Sequence[Policy] = (),
flows: Sequence[Flow] = (),
) -> None
```
Serve the proxy over stdio in front of the server `upstream` is connected to.
# References
The works the method and the modules cite, each under the key a text cites it by: the surnames of its one or two authors, or its first author's with `et al.`, and the year. `tools/docs_lint.py` holds this list and the citations in the tree equal, in both directions.
## Planning under nondeterminism
- **Cimatti et al. 2003.** A. Cimatti, M. Pistore, M. Roveri, P. Traverso. Weak, strong, and strong cyclic planning via symbolic model checking. Artificial Intelligence 147, 2003, 35-84. [doi:10.1016/S0004-3702(02)00374-0]()
- **Bertoli et al. 2006.** P. Bertoli, A. Cimatti, M. Roveri, P. Traverso. Strong planning under partial observability. Artificial Intelligence 170, 2006, 337-384. [doi:10.1016/j.artint.2006.01.004]()
- **Daniele et al. 2000.** M. Daniele, P. Traverso, M. Y. Vardi. Strong cyclic planning revisited. European Conference on Planning (ECP 1999), Springer, 2000.
## Abstraction over Boolean algebras
- **Graf and Saidi 1997.** S. Graf, H. Saidi. Construction of abstract state graphs with PVS. CAV 1997.
- **D'Antoni and Veanes 2017.** L. D'Antoni, M. Veanes. The power of symbolic automata and transducers. CAV 2017.
- **Kupferman and Vardi 1999.** O. Kupferman, M. Y. Vardi. Vacuity detection in temporal model checking. CHARME 1999, LNCS 1703, 82-98. [doi:10.1007/3-540-48153-2\_8](). The extended version is in International Journal on Software Tools for Technology Transfer 4(2), 2003, 224-233, [doi:10.1007/s100090100062](), whose numbering is not the one cited here.
- **Bauer et al. 2011.** A. Bauer, M. Leucker, C. Schallhart. Runtime verification for LTL and TLTL. ACM Transactions on Software Engineering and Methodology 20(4), 2011. [doi:10.1145/2000799.2000800](). A monitor decides a property on a prefix only by a bad or a good one, which a pending state is not.
- **Roşu and Chen 2012.** G. Roşu, F. Chen. Semantics and algorithms for parametric monitoring. Logical Methods in Computer Science 8(1:09), 2012. Parametric trace slicing, which a policy does not read.
## Records and their fields
- **Castagna 2023.** G. Castagna. Typing records, maps, and structs. Proc. ACM Program. Lang. 7 (ICFP), 2023, article 196. [doi:10.1145/3607838](). Selection of a field the record's type proves defined, and the projection that types it.
## Synthesis from typed components
- **Feng et al. 2017.** Y. Feng, R. Martins, Y. Wang, I. Dillig, T. W. Reps. Component-based synthesis for complex APIs. POPL 2017. The reachability pruning of SyPet.
- **Guo et al. 2022.** Z. Guo, D. Cao, D. Tjong, J. Yang, C. Schlesinger, N. Polikarpova. Type-directed program synthesis for RESTful APIs. PLDI 2022. [doi:10.1145/3519939.3523450](). Semantic types mined from observed calls, as APIphany.
## Language models as planners and agents
- **Kambhampati et al. 2024.** S. Kambhampati, K. Valmeekam, L. Guan, M. Verma, K. Stechly, S. Bhambri, L. Saldyt, A. Murthy. Position: LLMs can't plan, but can help planning in LLM-Modulo frameworks. ICML 2024, PMLR 235. [arXiv:2402.01817]()
- **Yao et al. 2024.** S. Yao, N. Shinn, P. Razavi, K. Narasimhan. τ-bench: a benchmark for tool-agent-user interaction in real-world domains. [arXiv:2406.12045](), 2024.
- **Elkoussy and Perez 2026.** L. Elkoussy, J. Perez. AgentLTL: a trace-verification framework for measuring, enforcing, and training procedural compliance in tool-using LLM agents. [arXiv:2607.02599](), 2026.
- **Mansoor et al. 2026.** I. K. Mansoor, A. Phadke, P. Rana. Verified tool calls improve LLM agent reliability under non-atomic failures. [arXiv:2608.02645](), 2026. A postcondition read before a retry, which the method does not read.
## Information flow and privilege for agents
- **Sah et al. 2026.** T. Sah, V. Srivastava, D. Sah, K. Jordan. The verifier tax: horizon dependent safety success tradeoffs in tool using LLM agents. ACM CAIS 2026. [arXiv:2603.19328](). Integrity leaks, identifiers made up to pass authentication, and deterministic grounding gates against them: a flow rule with `only` over a program, and the proxy's check at run time.
- **Beurer-Kellner et al. 2025.** L. Beurer-Kellner, B. Buesser, A.-M. Creţu, E. Debenedetti, D. Dobos, D. Fabian, M. Fischer, D. Froelicher, K. Grosse, D. Naeff, E. Ozoani, A. Paverd, F. Tramèr, V. Volhejn. Design patterns for securing LLM agents against prompt injections. [arXiv:2506.08837](), 2025. Plan-then-execute and code-then-execute, the order the critic and the runner hold.
- **Nasr et al. 2025.** M. Nasr, N. Carlini, C. Sitawarin, S. V. Schulhoff, J. Hayes, M. Ilie, J. Pluto, S. Song, H. Chaudhari, I. Shumailov, A. Thakurta, K. Y. Xiao, A. Terzis, F. Tramèr. The attacker moves second: stronger adaptive attacks bypass defenses against LLM jailbreaks and prompt injections. [arXiv:2510.09023](), 2025. Why the proxy's flow rules, read by equality, are no guarantee.
- **Debenedetti et al. 2025.** E. Debenedetti, I. Shumailov, T. Fan, J. Hayes, N. Carlini, D. Fabian, C. Kern, C. Shi, A. Terzis, F. Tramèr. Defeating prompt injections by design. [arXiv:2503.18813](), 2025. CaMeL.
- **Costa et al. 2025.** M. Costa, B. Köpf, A. Kolluri, A. Paverd, M. Russinovich, A. Salem, S. Tople, L. Wutschitz, S. Zanella-Béguelin. Securing AI agents with information-flow control. [arXiv:2505.23643](), 2025. FIDES.
- **Shi et al. 2025.** T. Shi, J. He, Z. Wang, H. Li, L. Wu, W. Guo, D. Song. Progent: securing AI agents with privilege control. [arXiv:2504.11703](), 2025.
## Specifications and prior work
- [Model Context Protocol, revision 2026-07-28](): a tool's `inputSchema`, `outputSchema` and annotations, and a result's `isError`.
- [JSON Schema draft 2020-12](), read by [valgebra-jsonschema]().
- valplan, [doi:10.5281/zenodo.23686600](): predicate abstraction over a Boolean algebra of JSON Schema sets with strong planning over the cells, the method this package starts from. Its code is not in this tree.