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))
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.