RFC-0015 · Agent Runtime Binding
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Status: Draft Owners: Runtime, AI
1. Scope
Defines the binding declaration kind, which connects an agent declaration (RFC-0008 §8.10) to a concrete execution environment. This RFC specifies:
- The syntax and semantics of the
bindingdeclaration - The execution protocol the runtime MUST follow when dispatching an agent
- Permission enforcement at the runtime boundary
- Health-checking requirements before dispatch
- Binding resolution when multiple environments are declared
- Model role validation at compile time
- Diagnostic codes in the M015xx range
This RFC resolves the design question deferred in RFC-0008 §8.10: the agent declaration is the compile-time capability contract; the binding declaration is the separate runtime configuration that maps an agent to an endpoint, model provider, and dispatch policy.
This RFC does not redefine agent capability contracts (RFC-0009), the storage write path (RFC-0007), or model declarations (RFC-0008 §6.20). It references those specifications normatively.
2. Goals
- The
bindingdeclaration is the sole place where execution endpoint, model selection, and dispatch policy are specified; agent declarations remain environment-agnostic. - Multiple bindings per agent are supported to enable dev/staging/prod environment separation without duplicating capability contracts.
- The runtime MUST enforce that all agent writes are within the agent’s declared
permissionsbefore any write reaches the object graph. - Binding failure (unhealthy endpoint, missing binding, model mismatch) MUST produce a structured diagnostic and MUST NOT crash the runtime.
- Agents carrying the
draftepistemic modifier (RFC-0008 §11.2) MUST NOT be activatable in bundles withciState: ready.
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
3. Declaration Constraints
- Every
bindingdeclaration MUST reference exactly oneagentdeclaration via itsagent:property. - A
bindingMUST specify anenvironment:URI and amodel:reference. - The
model:referenced in a binding MUST resolve to amodeldeclaration that includesruntime-agentin itsroles. Violation produces compile error M01503. - The runtime MUST NOT dispatch to a binding whose health check has not returned a successful response. Failure produces diagnostic M01501.
- An agent bound in an install plan with
ciState: readyMUST NOT carry thedraftmodifier. Violation produces compile error M01502. - Every write the agent attempts during execution MUST be covered by the agent’s declared
permissionsblock. Out-of-scope writes produce error M01500 and the entire agent invocation is rolled back atomically. - An agent MAY have zero or more bindings. An agent with zero bindings in the active environment cannot be dispatched; any action that fires it produces diagnostic M01504.
- Bindings MUST NOT be declared inside entity, flow, or policy blocks. They are top-level declarations.
4. The binding Declaration
4.1 Syntax
binding-decl ::= { decl-modifier } "binding" IDENT "{" binding-body "}"
binding-body ::= "agent:" IDENT NEWLINE
"environment:" STRING NEWLINE
"model:" IDENT NEWLINE
[ "version:" STRING NEWLINE ]
[ "healthCheck:" STRING NEWLINE ]
[ "timeout:" DURATION NEWLINE ]
[ retry-block ]
[ circuit-breaker-block ]
[ "envTag:" STRING NEWLINE ]
retry-block ::= "retryPolicy" "{" retry-prop* "}"
retry-prop ::= "maxAttempts:" NUMBER NEWLINE
| "backoff:" ( "linear" | "exponential" | "fixed" ) NEWLINE
| "initialDelay:" DURATION NEWLINE
| "maxDelay:" DURATION NEWLINE
circuit-breaker-block ::= "circuitBreaker" "{" { circuit-breaker-prop } "}"
circuit-breaker-prop ::= "failureThreshold" ":" NUMBER NEWLINE
| "resetAfter" ":" DURATION NEWLINE
DURATION ::= NUMBER ( "ms" | "s" | "m" )
All binding-body entries are unordered except that agent:, environment:, and model: are required; their absence produces M01510.
4.2 Canonical Example
binding RecommendationEngineBinding {
agent: RecommendationEngine
environment: "ollama://localhost:11434"
model: Gemma3Local
version: "1.0.0"
healthCheck: "/health"
timeout: 30s
retryPolicy {
maxAttempts: 3
backoff: exponential
}
circuitBreaker {
failureThreshold: 5
resetAfter: 60s
}
}
4.3 Multi-Environment Bindings
An agent may have multiple bindings differentiated by envTag:. The active binding is selected by matching envTag against the install plan’s environment tag (RFC-0005 §4a). If no envTag is specified the binding is treated as the default and is selected when no tag-specific binding matches.
binding RecommendationEngineLocal {
agent: RecommendationEngine
environment: "ollama://localhost:11434"
model: Gemma3Local
envTag: "development"
healthCheck: "/health"
timeout: 30s
}
binding RecommendationEngineProduction {
agent: RecommendationEngine
environment: "https://inference.internal/v1"
model: GPT4o
envTag: "production"
healthCheck: "/health"
timeout: 10s
retryPolicy {
maxAttempts: 2
backoff: exponential
initialDelay: 500ms
maxDelay: 5s
}
}
If more than one binding matches the active environment tag for the same agent, the compiler produces error M01511 (ambiguous binding). The install plan must ensure only one binding per agent per environment tag is active.
4.4 envTag Resolution Order
The runtime resolves the active binding for an agent as follows:
- Collect all bindings that reference the agent.
- Filter to bindings whose
envTagmatches the install plan’s environment tag exactly. - If exactly one match exists, use it.
- If no match exists, fall back to bindings with no
envTagdeclared. - If multiple defaults exist, produce M01511.
- If no binding is resolved, dispatch fails with M01504.
5. Execution Protocol
When an action bound to an agent fires, the runtime MUST execute the following steps in order. Any step that fails halts the sequence; no subsequent step is executed.
Step 1 — Resolve binding
The runtime resolves the active binding for the referenced agent using the environment-tag resolution order defined in §4.4. If no binding is resolved, the action fails with diagnostic M01504.
Step 2 — Health check
If the resolved binding declares a healthCheck path, the runtime MUST issue an HTTP GET to <environment base URL><healthCheck path> before proceeding. A non-2xx response or a connection failure results in diagnostic M01501 and the action is marked failed. The runtime MUST NOT retry dispatch to an unhealthy endpoint; the retry policy (§4.2) governs retries of healthy-but-transiently-failing inference calls, not health check failures.
Step 3 — Prompt construction
The runtime constructs the inference request payload from:
- The agent’s
protocolsblock, which declares the typed AI protocol (RFC-0009 §4) and its required inputs/outputs. - The current execution context: the triggering action’s inputs, the current gnomon instances in scope, and any relevant derivation state (RFC-0007).
- The agent’s
requirementsblock, serialized as system-level constraints.
Prompt construction MUST NOT include data outside the agent’s declared permissions scope. Including out-of-scope data in the prompt is treated as an escalation attempt and produces M01500.
Step 4 — Dispatch
The runtime POSTs the constructed payload to the environment endpoint using the protocol implied by the URI scheme:
| Scheme | Transport |
|---|---|
ollama:// | Ollama REST API (/api/generate or /api/chat) |
https:// | OpenAI-compatible Chat Completions API |
grpc:// | gRPC inference service (future; not yet normative) |
The model: field from the binding is included in the request. The timeout: value from the binding governs the HTTP/gRPC client timeout. If no timeout is declared, the runtime default is 60 seconds.
If the dispatch fails transiently (network error, 5xx response), the runtime applies the retryPolicy if one is declared, then re-executes from Step 2 (including health check) before each retry attempt. If all retry attempts are exhausted, the action fails with diagnostic M01505.
Step 5 — Response validation
The runtime validates the model’s response against the output types declared in the agent’s outputs block (RFC-0008 §8.10). Each produces: <Type> in <field> declaration defines a required typed output field. Validation failures produce diagnostic M01506 and the response is discarded; the invocation is rolled back.
Validation is structural: the response MUST parse to the declared types. Semantic validation (confidence thresholds, evidence requirements) is governed by RFC-0009 §5 and is enforced separately.
Step 6 — Permission-gated write
The validated outputs are written to the gnomon object graph (RFC-0007) under the agent’s declared permissions. Before each write the runtime MUST check:
- The target field or instance is within the agent’s
permissionsblock. - The write does not escalate the epistemic status of existing
asserteddata by overwriting it withinferredorestimateddata without explicit human confirmation (RFC-0009 §4). - The write does not target a terminal or high-authority state (RFC-0009 §9).
Any write that fails these checks produces diagnostic M01500 and the entire agent invocation is rolled back atomically. Partial writes are not permitted.
Step 7 — Post-write event emission
After a successful write, the runtime emits a write event on the affected gnomon instances. Any rules or aspects that observe the written fields are evaluated in the standard event propagation order (RFC-0007). The ordering is: (1) the audit log entry is written atomically with the object graph write (both committed in the same transaction), then (2) post-write rules fire after the transaction commits. Post-write rules are not part of the agent invocation’s atomicity boundary; they fire independently.
6. Permission Enforcement
Permission enforcement is normative and non-bypassable. The rules below supplement RFC-0009 §2 and §9.
6.1 Scope of the permissions block
The permissions block in an agent declaration enumerates the fields, entities, and state transitions the agent is allowed to write. The runtime MUST treat this list as a closed set. Any write attempt against a target not in the list MUST be rejected before the write reaches the object graph.
6.2 Rollback semantics
A permission violation (M01500) causes atomic rollback of the entire agent invocation. Any writes already performed within the same invocation are reversed. The triggering action is marked failed and its effects are not applied. The rollback MUST be recorded in the audit log with the agent identity, the attempted write target, and the M01500 code.
6.3 Escalation prohibition
Agents MUST NOT escalate their own permissions by writing to the agent or binding declaration registries, injecting new rules or aspects, or producing values that are subsequently used to authorize further writes. Attempts to do so produce M01500 and may also trigger a security alert at the platform level (RFC-0009 §9).
7. Health Checking
The healthCheck property declares a path that the runtime probes before dispatch. The probe semantics are:
- The runtime issues an HTTP GET to the resolved endpoint.
- A response with status 200–299 is treated as healthy.
- Any other response, or a timeout, is treated as unhealthy.
- The probe timeout is fixed at 5 seconds and is not configurable per-binding in this version.
- A failed health check produces M01501. The action is marked failed; the retry policy is NOT applied to health check failures.
If no healthCheck is declared, the runtime skips the probe and proceeds to Step 4. This is permitted for environments where a dedicated health endpoint is unavailable, but it is not recommended because a missing endpoint will surface as a dispatch error rather than an early-fail diagnostic.
8. draft Agents and Bundle Readiness
RFC-0008 §11.2 defines the draft epistemic modifier. An agent carrying draft is an incomplete or AI-generated declaration that has not been reviewed by a human author.
The rule is:
An agent with the
draftmodifier MUST NOT be bound in a bundle withciState: ready. Violation produces compile error M01502.
The compiler enforces this at bundle emission time. The check applies to the agent declaration, not to the binding: if agent RecommendationEngine carries draft, then binding RecommendationEngineBinding { agent: RecommendationEngine ... } is invalid in a ready bundle regardless of the binding’s own modifier state.
This rule ensures that no unreviewed AI-generated agent can be activated in a production install plan. See also RFC-0008 §11.2 (M08786) for the parallel rule that prohibits draft declarations in ready bundles generally.
9. Model Role Validation
A binding references a model declaration by name. At compile time the compiler MUST verify that the referenced model declaration includes runtime-agent in its roles list (RFC-0008 §6.20).
// Valid: Gemma3Local declares roles [rule-compiler, runtime-agent]
binding RecommendationEngineBinding {
agent: RecommendationEngine
model: Gemma3Local // OK — runtime-agent role present
...
}
// Invalid: a model declared with roles [rule-compiler] only
binding BadBinding {
agent: SomeAgent
model: CompilerOnlyModel // M01503 — runtime-agent role absent
...
}
If the binding’s model: reference cannot be resolved (the model declaration is absent or not imported), the compiler produces M01512 (unresolved model reference).
If the model is resolved but runtime-agent is absent from its roles, the compiler produces M01503. This is a compile error, not a runtime diagnostic.
10. Diagnostic Codes
All binding diagnostics are in the M015xx range.
M0150x — Permission and write enforcement
| Code | Severity | Condition |
|---|---|---|
| M01500 | Error | Agent write attempt targets field or entity outside declared permissions; invocation rolled back |
| M01501 | Error | Health check probe returned non-2xx or timed out; dispatch aborted |
| M01502 | Error | draft agent referenced by a binding in a bundle with ciState: ready |
| M01503 | Error | Binding model: references a model whose roles does not include runtime-agent |
| M01504 | Error | No binding resolved for agent in the active environment; action cannot dispatch |
| M01505 | Error | All retry attempts exhausted for a transient dispatch failure |
| M01506 | Error | Model response failed structural validation against agent’s declared output types |
M0151x — Declaration and configuration
| Code | Severity | Condition |
|---|---|---|
| M01510 | Error | binding declaration missing required property (agent:, environment:, or model:) |
| M01511 | Error | Multiple bindings resolve to the same agent for the same environment tag (ambiguous binding) |
| M01512 | Error | model: reference in binding cannot be resolved to a known model declaration |
| M01513 | Warning | No healthCheck declared; endpoint liveness is not probed before dispatch |
| M01514 | Warning | No retryPolicy declared; transient dispatch failures will not be retried |
| M01515 | Warning | timeout: exceeds 120s; review whether a shorter timeout is appropriate |
| M01516 | Error | Binding references a model declaration whose digest has changed since last activation; re-activation required |
| M01517 | Warning | Binding environment: URI references an endpoint not on the platform allowlist of approved inference endpoints |
M01540–M01541 — Circuit breaker and timeout
| Code | Severity | Condition |
|---|---|---|
| M01540 | Error | Dispatch rejected — circuit breaker is open; endpoint exceeded failure threshold |
| M01541 | Warning | Action-level agentTimeout exceeds binding-level timeout: — action timeout has no effect; binding timeout is the ceiling |
M0983x — Agent read scope (RFC-0009 allocation)
M09832 — see RFC-0009 §8 (agent identity mismatch); not defined in this RFC.
11. Invariants
The following invariants are normative. The compiler or runtime MUST enforce each.
- Binding–agent coupling: A binding is invalid if its
agent:reference cannot be resolved to a knownagentdeclaration in the compiled bundle. Error M01510. - Single active binding per environment: For any (agent, envTag) pair, exactly one binding may be active in a given install plan. Error M01511.
- Model role: The binding’s
model:reference MUST resolve to a model withruntime-agentinroles. Error M01503. - Draft guard: A
draftagent MUST NOT be activatable in a ready bundle. Error M01502. - Atomicity of writes: All writes within a single agent invocation are transactional. A permission failure or validation failure rolls back all of them.
- No silent partial writes: The runtime MUST NOT write any portion of an agent’s output if any portion fails validation or permission checks.
- Audit trail: Every agent invocation — successful or failed — MUST produce an audit log entry containing the agent name, binding name, environment tag, invocation timestamp, outcome, and any diagnostic codes raised. The audit log entry MUST be written in the same database transaction as the write to the object graph — i.e., both the audit entry and the object graph update are committed atomically. Post-write rules fire after the transaction commits and are not part of the atomic boundary.
12. Failure Modes
| Failure | Trigger | Diagnostic | Recovery |
|---|---|---|---|
| No binding resolved | Agent invoked but no matching binding for active envTag | M01504 | Add a binding with the correct envTag, or remove the envTag constraint |
| Health check failure | Endpoint unreachable or returns non-2xx | M01501 | Restore the inference service; binding becomes dispatchable once health check passes |
| Model role mismatch | model: lacks runtime-agent | M01503 (compile) | Update the model declaration’s roles or choose a different model |
| Permission violation | Agent writes outside declared permissions | M01500 | Narrow the agent’s effects, or expand its permissions with appropriate review |
| Response validation failure | Model output doesn’t conform to declared output types | M01506 | Revise the agent’s protocols/outputs declarations or improve the prompt |
| Draft in ready bundle | draft agent bound in ciState: ready bundle | M01502 (compile) | Remove draft modifier after human review, or exclude the binding from the ready bundle |
| Retry exhaustion | All retries failed for transient error | M01505 | Increase maxAttempts, investigate inference service stability |
13. Security
This section supplements RFC-0009 §9.
-
No escalation beyond declared permissions. Agents MUST NOT acquire write access beyond their
permissionsblock through any mechanism: prompt injection, indirect writes via rule-triggered side effects, or binding reconfiguration. The runtime enforces this at the write boundary (§6), not only at authoring time (RFC-0009 §9, invariant 1). -
Prompt confidentiality. The constructed prompt (Step 3) MUST NOT include data from gnomon instances outside the agent’s read scope. The read scope is derived from the agent’s
permissionsblock. If the runtime cannot determine read scope, it MUST default to denying the data’s inclusion rather than permitting it. -
Environment URI validation. The
environment:URI MUST be validated at compile time against a platform allowlist of approved inference endpoints where one exists. Bindings referencing unapproved endpoints produce a warning M01517. This is especially important for production bundles. -
Audit log integrity. The audit log entry for each agent invocation (§11, invariant 7) MUST be written in the same database transaction as the write to the object graph — both are committed atomically. This prevents an attacker who can interrupt the write from suppressing the audit trail. Post-write rules fire after the transaction commits and are outside the atomic boundary (see §5 step 7 and §11 invariant 7).
-
Model version pinning. Bindings referencing a
modeldeclaration that usesdigest:(content-addressed pin) provide stronger reproducibility guarantees than those using onlyversion:. Unpinned model references should be treated as higher-risk in security-sensitive environments. -
Cross-agent invocation. An agent MUST NOT invoke another agent directly. Multi-agent workflows MUST be expressed as separate actions bound to separate agents, with explicit data passing through the object graph. This prevents transitive permission escalation.