Architecture & safety boundaries

Version 0.15.0 branch/join execution

Version 0.15.0 supports a narrow, fully resolved required Exactly(1) acyclic graph with a Pydantic request/response, at least one FromRequest, supported request/result/authenticated-context/default inputs, a unique sink reached by every operation, and exactly one producer of the endpoint’s exact full response annotation. AgentChoice is excluded. Ready operations execute sequentially with declaration-order tie-breaking; after adds business ordering. This is not a public graph API, parallel scheduler, feedback, or general graph support. Existing chain, choice, repetition, and checkpoint behavior is unchanged. Published v0.14.0 is unchanged; milestone 4 is partial and milestone 3 remains partial. See example 20 and the contract.

Unreleased source: one producer-backed choice in required DAGs

Current source adds one producer-backed choice argument to an otherwise eligible required Exactly(1) acyclic branch/join DAG; this is unreleased and not part of published summonpot 0.15.0. Require Pydantic request/response models, at least one FromRequest, one unique sink reached by every operation, and exactly one exact full response annotation producer. The exact declared choice Operation producer returns list[ConcreteModel]. The agent chooses only the argument value, not which branch runs. Historical version 0.15.0 branch/join remains choice-free; existing uniquely ordered linear chains retain their multiple-choice support.

All operations execute sequentially in stable declaration-priority order among ready nodes in this acyclic graph with a unique sink. The choice producer must run before its consumer. There is no global choice barrier: an earlier independent operation may already have effects when an empty/unavailable/oversized choice domain returns the existing redacted 409 before consumer/model work. A singleton binds locally without model lookup/call; ambiguous choices expose only bounded inert candidate evidence and opaque tokens to a private selector with no business tools. The shared kernel validates and invokes the consumer; no additional result/context disclosure or final model acknowledgment is added. after is business ordering.

Explicit function-tool quota (UsageLimits.tool_calls_limit) and private allow_direct=False reject this graph shape before effects. This is not a public graph API, parallel scheduler, repeat, feedback, durable recovery, or general graph compiler. Milestones 3 and 4 remain partial. See the operation reference and example 23.

Version 0.15.0 bounded repeated calls

One required typed operation may run a finite positive number of times (1 <= minimum <= maximum, maximum > 1) with a Pydantic request, at least one FromRequest, direct closed Literal[str] AgentChoice inputs, supported request/context bindings or immutable defaults, and exact full operation-output/endpoint-response annotation identity. Summonpot owns sequential decisions; business functions are not selector tools. It locally validates selections, shares one usage budget and deadline, resolves the model lazily, auto-finishes at maximum, and returns only the final successful canonical result; any failure aborts. Previous-result evidence is limited to 65,536 characters per decision, not an aggregate prompt budget. Explicit tool_calls_limit fails before provider/effects. No producer choices, FromResult, after, zero-minimum/unbounded bounds, implicit batch, or general graph. Existing Exactly(1) and producer-choice routes remain unchanged. Published v0.14.0 is untouched; milestone 3 remains partial and a narrow repeated-stage consumer is now documented below. Broader repeated-result addressing remains planned.

Version 0.15.0 repeated-stage final-result consumer

The original two-operation form lets one bounded repeated producer feed one required, choice-free terminal operation after the producer stage closes. The terminal uses FromResult(producer, field, invocation="final") to bind the final successful canonical result from one immutable closure record; meeting the minimum alone does not make it ready, and a failed or uncertain invocation aborts without earlier-result fallback. This two-operation shape is version 0.15.0, not published v0.14.0 behavior. It does not add aggregation, repeated consumers, inspect/correct/verify workflows, or general graphs. See the repeated-stage contract.

Version 0.15.0 single-stage sequential chains

Version 0.15.0 supports a uniquely ordered chain with one nonterminal bounded repeated operation, an optional resolved prefix and a nonempty resolved suffix. Every other operation is required Exactly(1) with no agent choices. A Pydantic request needs at least one FromRequest across the whole chain, not necessarily on the repeated operation; supported request/result/authenticated-context bindings and immutable defaults remain required. The repeated operation has positive finite bounds (minimum >= 1, maximum > 1), direct closed plain-string Literal choices and a Pydantic intermediate distinct from the response. Ordinary FromResult reads single-invocation results; repeated results require invocation="final", with at least one suffix consumer. Exactly one terminal operation owns the endpoint’s exact full response annotation. Prefix operations run before one lazy model resolution; suffix operations run after immutable stage closure without further model decisions or acknowledgment. One principal, ledger, absolute deadline and usage budget span the request. Prefix results/context/ledger are not implicitly projected into model prompts; receiving constraints are checked before each start. Explicit function-tool quotas reject before all work. No feedback cycles, external choices, multiple repeated stages, aggregation, parallelism or durable recovery are added. Published behavior before v0.15.0 remains unchanged. See the single-stage chain contract.

Version 0.15.0 prefix selection before repetition

Version 0.15.0 also composes exactly one producer-backed choice argument on one required Exactly(1) prefix consumer with one nonterminal bounded repeated stage and a resolved suffix. The candidate producer is an earlier single-start operation returning list[ConcreteModel]; repeated choices remain direct closed string Literal values, and all other operations remain resolved required Exactly(1). Pydantic request/response, chain-wide FromRequest, unique ordering, final-invocation addressing and exact terminal response ownership remain required. Empty/unavailable/oversized candidate domains stop before selection or repeated work; a singleton binds locally, while ambiguity uses canonical request-local tokens. Singleton selection still leads to model-backed repeated decisions. One lazy model-configuration lookup, run, principal, ledger, deadline and usage budget span both phases. No business-function tools, reselection after same-run failure, effect replay or final model acknowledgment are added. A fresh request starts a fresh run. Published behavior before v0.15.0 remains unchanged. See the composed selection/stage contract. See the canonical contract.

Version 0.15.0 bounded checkpoint progression

Version 0.15.0 admits one explicit Required(check, calls=Between(1, M), until="accepted") with finite M >= 2. Its marker must name a stored, non-null strict Boolean field in the validated Pydantic output; until=None retains ordinary semantics. The uniquely ordered required region uses bounds 1..M; a nonempty uniquely ordered optional negative continuation uses 0..M-1. Exactly one Required(..., calls=Exactly(1)) terminal returns the exact full endpoint response and reads only final checkpoint fields. Unsupported marked shapes reject at registration. True closes; false continues, while the Mth false closes unresolved without another continuation. Empty choice domains abort with the existing redacted 409, not an unresolved result. Only one frame operation is in flight; continuation admission atomically retires that round’s authority, so closure cannot race it. Invocations use the existing shared kernel. Request, principal, ledger, usage budget and deadline are shared across rounds. No rollback, replay, durable resume or recovery is provided; effects may remain after later failure. Published behavior before v0.15.0 remains unchanged. See the source contract and examples 18–19.

One public abstraction

Summonpot modernizes APIs for the AI era without replacing an endpoint with a separate agent layer. A declaration combines a validated request model, fixed goal, explicit application-owned capabilities, and typed response. The same contract generates HTTP routes and OpenAPI.

The diagram summarizes the shared contract, not a broad general-purpose deterministic executor. Open full size.

Authority is explicit

• The application supplies exact callables and decides which capabilities exist.
• Depends(...) and Required(...) express optional and mandatory operations.
• FromRequest(...) binds trusted, validated caller data.
• AgentChoice(...) marks only the arguments where an agent-owned decision is permitted.
• The agent runtime is bounded; operation use is enforced per request and output is validated locally.
• An operation output is not a distributed exactly-once completion guarantee.

The endpoint goal is fixed in code; caller input is business data, not instructions that redefine authority. The contract closes the capability set, and successful responses must satisfy the declared model.

Request bindings, exact application capabilities, agent choices, and final validation have distinct owners. Open full size.

What runs without a model

One fully resolved Exactly(1) operation can execute directly only in a narrow supported slice: a Pydantic request, at least one FromRequest binding, remaining parameters from request data or supported immutable identity-stable callable defaults, and operation output exactly matching the endpoint response model. This path does not resolve, construct, or call a model. It does not fall back to a model after execution begins.

From 0.12.0, model-free execution also covers uniquely ordered chains of at least two required Exactly(1) operations with a Pydantic request, at least one FromRequest binding, only FromRequest/FromResult bindings or supported immutable defaults, and the terminal operation’s exact full endpoint response annotation. The runtime returns its canonical validated terminal result. An AgentChoice normally keeps the chain agent-mediated. A narrowly bounded result-dependent exception included from version 0.14.0 is documented in the operation reference; published 0.13.0 behavior remains agent-mediated. Version 0.15.0 supports one or more producer-backed choices with framework-owned progression. In an otherwise eligible uniquely ordered required Exactly(1) chain, a Pydantic request, at least one FromRequest, supported request/result/authenticated-context bindings or immutable defaults, and exact full terminal response annotation identity remain required. All current consumer domains are checked before selection or start. Singleton bindings resolve locally; a decision-only selector returns ambiguous tokens with no business-operation tools. The shared kernel validates and invokes the operation, then continues locally until another genuine decision is needed. The canonical terminal result returns without a final model acknowledgment. Request/principal, reservations, token domains, usage budgets and one deadline remain request-local across frontiers and corrections. Explicit tool_calls_limit retains the previous one-way agent suffix; allow_direct=False and other noneligible declarations retain their existing route. Limits remain 128 candidates and 65,536 evidence characters per binding, not an aggregate prompt/context budget. Prefix effects may precede provider-configuration failure; no rollback, effect replay or durable resume is added. Historical v0.14.0 remains exactly-one-choice. See the operation reference for details.

From version 0.13.0, authenticated FromContext may also resolve arguments in the admitted single operation or uniquely ordered chain. The existing Pydantic request, at-least-one- FromRequest, immutable-default, and exact full response requirements still apply to model-free execution; context-only declarations remain agent-mediated. The application verifies credentials with Summon(context=authenticate) and supplies a frozen, closed, immutable principal. The runtime snapshots canonical values without replaying principal validation hooks, preflights all context receivers before effects, and keeps context out of model inputs. See the authenticated context contract.

Other supported declarations retain the provider-neutral agent runtime. Unsupported explicit contract shapes fail at registration rather than quietly accepting unenforced model-supplied arguments. Broader graph and deterministic compiler shapes remain planned.

Safe integration checklist

1. Register only exact application callables intended for this endpoint.
2. Bind caller-controlled fields through validated request models.
3. Use AgentChoice only for genuinely semantic choices, never for trusted identifiers or authorization.
4. Keep side-effecting operations narrow and enforce authorization inside application code.
5. Apply timeouts and usage limits; treat the keyless test model as executable, not as a sandbox.
6. Confirm output validation and public error redaction are part of the integration’s expectations.

See the source-level authority-boundary design, review guidance, and roadmap.