AGTP-RCNS: Runtime Contract Negotiation Substrate

Runtime Contract Negotiation

Runtime Contract Negotiation Substrate The Runtime Contract Negotiation Substrate (RCNS) is the machinery by which a server delivers Tier C endpoints (the tier taxonomy in ): endpoints synthesized at runtime from registered primitives when a caller addresses a (method, path) pair that is absent from the Tier A or Tier B set. PROPOSE is the AGTP method that explicitly invokes RCNS. RCNS also operates implicitly when a server is configured to accept unregistered requests as synthesis candidates; the wire surface in that case is the same set of contract identifiers and reasoned status codes (461, 464) registered in and specified here. This document specifies the four-lock dispatcher gate, the two delivery modes (confirm-first 461 and optimistic 263 with the Contract-Synthesized header), the endpoint-keyed PROPOSE body shape, the contract scoping rules, the per-agent rate limiting and idempotency key contract, the synthesis_id, contract_hash, and negotiation_origin Attribution-Record extension fields, and the DISCOVER /patterns, DISCOVER /contracts, INSPECT target=contract, and INSPECT target=rcns-attempt inventory surfaces. The Tier C taxonomy in and the reservations in (status codes 461 and 464, reason vocabulary rcns-disabled, trust-tier-insufficient, composition-impossible, synthesis-error, contract-not-yours, contract-revoked) constitute the wire foundation for the substrate.

Tier C Resolution A server with active synthesized contracts MUST maintain a resolver that answers, for any inbound (method, path) pair, whether an active Tier C contract exists for that pair. The resolver is the dispatcher hook that closes the loop between the tier classification (the tier taxonomy in ) and the synthesis machinery: an unregistered (method, path) pair that resolves to an active contract is classified Tier C and dispatched to the synthesized handler; a pair that fails to resolve is dispatched per the unregistered-pair rules in the tier taxonomy in . The resolver MUST scope each lookup by the requesting Agent-ID. A contract synthesized for Agent-ID X MUST NOT resolve for an unrelated Agent-ID Y; the server MUST return 464 RCNS No Contract with reason: contract-not-yours in that case. Contracts that have expired, been revoked, or been suspended MUST NOT resolve. The resolver returns, when an active contract exists:

The synthesis_id of the matched contract.
The recipe_lineage (recipe name and captured recipe version) the contract was synthesized under.
The contract's expiration time and remaining budget, if applicable.

These fields are server-internal at lookup time but appear on INSPECT target=contract responses (the target=contract extension to INSPECT specified in ) and in the Attribution-Record extension fields () on every invocation served under the contract.

The Four-Lock Dispatcher Gate RCNS synthesis fires only when all four of the following locks are open at the moment of an unregistered request. The locks are distributed across actors: server operator, requesting agent's invoker, requesting agent's identity, and requesting agent's posture. No single party can unilaterally activate RCNS.

Server policy enabled. The server's operator has set [policies.rcns].enabled = true (or the equivalent in the server's configuration format). The default posture is OFF; servers ship with RCNS disabled and the operator opts in explicitly.
Caller opt-in header. The request carries Allow-RCNS: true. Clients that have withheld consent to runtime negotiation never get it; a missing or non-true value means the unregistered request is refused per the standard Tier classification rules (the tier taxonomy in ).
Caller scope. The requesting agent's Authority-Scope includes the rcns:negotiate token. Agents lacking this token cannot trigger synthesis even with the header set.
Minimum trust tier. The requesting agent's resolved trust_tier () is greater than or equal to the server's configured min_trust_tier (default 1, the strictest). Agents below the threshold receive 464 RCNS No Contract with reason: trust-tier-insufficient.

When any of the four locks is closed, the server MUST NOT synthesize. The specific refusal depends on which lock is closed: Four-Lock Gate Refusal Mapping

Lock closed	Server response
Server policy disabled	`464 RCNS No Contract` reason: `rcns-disabled`
Caller opt-in absent	Standard unregistered-pair refusal (`404` or `405`); RCNS goes unsignaled
Caller scope absent	`262 Authorization Required` reason `scope-required scope: rcns:negotiate` when the agent's identity document grants the token but the request omitted it from its claim; `455 Scope Violation` reason `scope-exceeded` when the document omits it (obtainability rule of )
Trust tier insufficient	`464 RCNS No Contract` reason: `trust-tier-insufficient`

The asymmetry between locks 1 and 2 (rcns-disabled 464 vs opaque 404) is deliberate: the server policy lock surfaces RCNS posture to interested callers; the opt-in lock is a no-surprise gate for callers that never asked. A request that holds the Synthesis-Id header (presenting an already-issued contract) MUST NOT trigger a new synthesis attempt; the gate is skipped and the request is dispatched directly through the contract resolution path. This prevents recursive RCNS: a contract invocation cannot itself produce a new contract.

Delivery Modes When the four-lock gate opens and the server determines a synthesis is possible, the server delivers the contract in one of two modes selected by operator policy: Confirm-first (default): The server returns 461 RCNS Contract Available with a response body carrying the synthesized contract preview. The body MUST include: ", "method": "BOOK", "path": "/room", "endpoint": { "..." : "..." }, "recipe_lineage": { "recipe_name": "", "recipe_version": "" }, "contract_hash": "", "expires_at": "" } ]]> The caller accepts the contract by re-issuing the original request with the Contract-Synthesized header carrying the returned synthesis_id. The contract is bound to the caller's Agent-ID at the moment the 461 was issued; a different Agent-ID presenting the same synthesis_id is refused with 464 contract-not-yours. The caller declines the contract by ignoring the response; the contract record MAY be garbage-collected by the server after a configured TTL. Optimistic: The server synthesizes the contract and executes the request inline, returning the normal 200 OK (or method- specific success code) for the underlying action. The response MUST carry the Contract-Synthesized header with the issued synthesis_id, signaling to the caller that this response was served under a runtime-negotiated contract, as distinct from a Tier A or Tier B endpoint. Callers that wish to repeat the action send subsequent requests with the Contract-Synthesized header to bypass the gate. Optimistic mode reduces latency at the cost of removing the caller's opportunity to preview the synthesized contract. Confirm-first is the safer default; optimistic is appropriate when the server operator knows recipes produce contracts the caller will accept.

Contract Scoping and Lifecycle A synthesized contract is bound to:

The originating Agent-ID (set when the 461 was issued or the optimistic synthesis fired).
The recipe and recipe version captured at synthesis time ().
The contract's expiration timestamp.

Servers MUST enforce these bindings on every request carrying a Contract-Synthesized header:

Wrong Agent-ID → 464 contract-not-yours.
Unknown synthesis_id → 404 Not Found.
Expired or revoked contract → 464 contract-revoked.

Contracts have three release paths:

Caller release. The originating agent invokes SUSPEND with the synthesis_id parameter to release a contract it no longer needs. The release emits an rcns_release event in the agent's lifecycle stream and evicts the contract from the runtime.
Operator revocation. The server operator invokes REVOKE with target=contract and synthesis_id to revoke a contract; the runtime evicts immediately and the next presentation returns 464 contract-revoked.
TTL expiration. Contracts have an operator-configured TTL; the runtime evicts on expiry.

Stale Contract Sweep When an operator edits a recipe that has active contracts synthesized under earlier versions (), those contracts continue to execute under their captured version; the spec guarantees in-flight contract stability across recipe edits. Operators that need to flush stale contracts (typically after a security-relevant recipe change) invoke REVOKE target=stale-contracts: REVOKE target=stale-contracts Parameters

Parameter	Required	Description
`target`	MUST	The literal string `stale-contracts`.
`mode`	MAY	One of `grandfather` (report drifted contracts but leave them running) or `invalidate` (evict drifted contracts). Default is the value of the `on_policy_change` knob in .
`actor`	SHOULD	Identifier of the operator invoking the sweep, recorded on emitted lifecycle events.

The sweep walks every active contract in the server's synthesis runtime and compares each contract's captured recipe_version against the current version of the same-named recipe in the loaded policies. Three outcomes per contract:

Version matches. Contract is left alone.
Version differs and mode is grandfather. Contract is reported in the response as drifted but MUST NOT be evicted; the contract continues to execute under its captured version.
Version differs and mode is invalidate. Contract MUST be evicted from the runtime. The eviction MUST emit an rcns_release event in the originating agent's lifecycle stream with reason: policy-change-invalidation and the operator's identifier carried in the event payload to distinguish operator-fired invalidations from agent-initiated releases (the SUSPEND synthesis_id= invocation defined in ). Subsequent presentations of the evicted synthesis_id return 404 Not Found.

Passthrough contracts (those without a recipe lineage, synthesized without a recipe) are skipped: the sweep has no version to compare against. Contracts whose recipe has been entirely removed from policy (the recipe name no longer exists) are treated as drift with current_version reported as null; under invalidate mode, these contracts are evicted. The sweep returns a structured response listing every contract examined with its disposition (unchanged, grandfathered, or evicted). Authorization for REVOKE target=stale-contracts requires the operator inspect:all scope token; agents cannot fire the sweep on behalf of others. The sweep is operator-fired by design. AGTP servers lack support hot configuration reload; the operator explicitly invokes the sweep when they know they have edited a recipe and want the resulting drift to be either reported or invalidated. Operators that want strict recipe-edit-invalidates-contracts behavior set on_policy_change = invalidate and invoke the sweep after every recipe edit.

Headers and Rate Limiting RCNS uses two request headers and one response header: RCNS Request and Response Headers

Header	Direction	Purpose
`Allow-RCNS`	Request	Caller opt-in to runtime negotiation. Value `true` opens lock 2 of the four-lock gate (). Absent or non-`true` keeps the gate closed.
`Contract-Synthesized`	Request and Response	Identifies a synthesized contract by `synthesis_id`. On a request, presents a previously-issued contract to bypass the gate. On a response (optimistic mode), notifies the caller that the response was served under a synthesized contract.
`Idempotency-Key`	Request	Per-agent idempotency key for RCNS-eligible requests. Servers MUST scope the idempotency cache by `(Agent-ID, Idempotency-Key)`; replays of the same key from the same agent receive the cached response, replays from different agents are independent requests.

Servers MUST implement per-agent rate limiting on RCNS gate evaluations. When the per-agent rate exceeds the configured ceiling, the server returns 429 Too Many Requests with scope: rcns in the response body to distinguish RCNS rate limiting from other rate-limit sources. The default ceiling is operator-configured; implementations SHOULD default to a conservative value (e.g., 10 evaluations per minute) and operators MAY raise it. Rate limiting applies to gate evaluations only; invocations served under an already-issued contract are outside it. Repeated Contract-Synthesized-bearing requests against a synthesized contract are rate-limited like any other endpoint, outside the RCNS rate limit.

Attribution-Record Extension Fields Every action dispatched under a synthesized contract, whether RCNS-spawned, PROPOSE-spawned, or future-mechanism- spawned, MUST carry the following extension fields on its Attribution-Record payload, in addition to the base identifier-chain fields specified in : RCNS Attribution-Record Extension Fields

Field	Type	Description
`synthesis_id`	string	Opaque identifier of the contract under which this action was dispatched.
`contract_hash`	string	SHA-256 of the canonical contract definition (the synthesized endpoint plus its recipe lineage at synthesis time), rendered as 64 lowercase hexadecimal characters. Stable across all invocations of the same contract.
`negotiation_origin`	string	One of `rcns-gate` (synthesized via the four-lock gate), `propose` (synthesized via explicit PROPOSE), or `pre-registered` (a future origin for contracts elevated from Tier C to Tier B).

These fields enable chain inspectors and audit consumers to group invocations by contract identity, distinguish contracts produced through different origins, and verify that a stream of actions all ran under the same synthesized contract definition. The fields are present only on actions served under a contract. Tier A and Tier B endpoint invocations omit them entirely; their absence is itself diagnostic information.

RCNS Configuration The full set of operator-controlled RCNS knobs is specified in this section. The configuration is operator- authored and is invisible to callers on the wire; what is visible is the result of the configuration (whether the gate fires, which mode it delivers in, what the rate ceiling is). The block name ([policies.rcns] in the recommended TOML form) is conventional and carries no normative weight; servers using different configuration formats apply equivalent semantics. RCNS Configuration Knobs

Knob	Default	Purpose
`enabled`	`false`	Master switch (lock 1 of the four-lock gate)
`mode`	`confirm-first`	Delivery mode: `confirm-first` (461) or `optimistic`
`min_trust_tier`	`1` (strictest)	Minimum resolved trust tier for callers (lock 4)
`rate_limit_per_minute`	`10`	Per-agent rate ceiling for gate evaluations
`contract_ttl_seconds`	implementation-defined	Default contract TTL; operators SHOULD set explicitly
`on_policy_change`	`grandfather`	Default behavior of the operator-fired stale-contract sweep (). One of `grandfather` (report drifted contracts but leave them running) or `invalidate` (evict drifted contracts and emit `rcns_release` events with `reason: policy-change-invalidation`). The sweep is operator-fired; this knob sets its default mode, which operators MAY override per invocation.

The default posture is conservative: a freshly-installed AGTP server has RCNS disabled and, when enabled, defaults to confirm-first delivery at the strictest trust tier with a low rate ceiling. Operators relax these defaults explicitly as their deployment matures.

Purpose PROPOSE is the AGTP method that triggers runtime contract negotiation. An agent that needs an endpoint the server has yet to advertise submits a PROPOSE request carrying an endpoint definition conformant to specification; the server evaluates the proposal against the contract layer and either instantiates the endpoint as a session-scoped artifact or refuses. PROPOSE is one of the eighteen floor methods defined in . Its parameter table is specified there. This document specifies the synthesis semantics that govern server-side evaluation.

Negotiation Flow

PROPOSE Request Body Shape PROPOSE accepts the proposed endpoint definition in one of two mutually exclusive body forms. Servers MUST accept both forms; clients SHOULD emit the wrapped form for new code.

Wrapped form (RECOMMENDED) The proposed endpoint definition is carried under a top-level endpoint field: The wrapped form makes the (method, path) pair the explicit key of the proposal and clears the way for synthesis-time fields (e.g., version, lineage) to ride at the parameters level without colliding with endpoint definition fields. The wrapped form is the form used by RCNS dispatcher-gate escalations ().

Legacy form The endpoint definition fields appear directly under parameters with a name field naming the endpoint: A PROPOSE request MUST NOT carry both endpoint and name at the same time. Servers MUST return 400 Bad Request with reason: ambiguous-body if both are present.

263 Response Body On approval the server returns 263 Proposal Approved with a body carrying the synthesized endpoint: ", "endpoint": { "..." : "..." }, "recipe_lineage": { "recipe_name": "", "recipe_version": "" } } ]]> The top-level method and path fields name the synthesized endpoint and MUST match the proposed pair. The synthesis_id is an opaque identifier the server uses to distinguish this contract from other contracts; clients SHOULD record it for use with INSPECT target=contract and the RCNS revocation surface. The recipe_lineage field, when present, records the recipe that produced the synthesis and the recipe version captured at synthesis time; this disambiguates contracts produced under different versions of the same recipe.

Recipe Versioning A server's contract synthesis machinery typically composes synthesized endpoints from operator-authored recipes (composition rules that name a set of underlying primitives and how to invoke them). Recipes evolve: operators edit them to fix bugs, support new primitives, or refine semantic claims. To prevent recipe edits from silently mutating running contracts, recipes carry a version identifier and synthesis captures the version in effect at the moment the contract was produced. The version field is operator-defined; servers MUST treat the value opaquely. The recommended convention is a monotonically increasing string (semver, integer counter, or timestamp); the specific format has no effect on wire interoperability. When a server synthesizes a contract from a recipe:

The server MUST record the recipe's current version on the resulting contract record at synthesis time.
The server MUST present the captured version in the recipe_lineage.recipe_version field of the 263 response body () and in any subsequent INSPECT target=contract response naming this contract.
The synthesized contract MUST continue to execute under the captured recipe version for the contract's lifetime, even if the operator subsequently edits the recipe to a new version.
A subsequent PROPOSE for the same (method, path) pair MAY produce a new contract bound to the new recipe version; the new contract carries a distinct synthesis_id and the prior contract continues to operate under its captured version until released or revoked.

The recipe-version capture rule decouples contract stability from recipe evolution. Operators who edit a recipe never disturb in-flight callers; callers who need the updated behavior reproduce the proposal under the new recipe version. Operators that want to force callers off an old recipe version use the contract revocation surface specified in (revoking specific synthesis_id values); recipes are never mutated in place.

Server-Side Synthesis Evaluation On receipt of a PROPOSE request, the server MUST evaluate:

Method conformance. Is the proposed method in the AGTP-METHODS approved method catalog, or is it a custom method declared in the server's policies.methods ()? Otherwise, return 459 Method Violation.
Path conformance. Does the proposed path satisfy the path grammar in ? Otherwise, return 460 Endpoint Violation.
Semantic block conformance. Does the proposed semantic block carry all required fields with valid values? Otherwise, return 400 Bad Request.
Schema conformance. Are the input and output schemas valid JSON Schema documents? Otherwise, return 400 Bad Request.
Authority sufficiency. Does the proposing agent's declared Authority-Scope cover the proposed authority requirements? If the agent's identity document grants them but the request omitted them from its claim, return 262 Authorization Required with reason scope-required; if the document omits them, return 455 Scope Violation with reason scope-exceeded ().
Capability envelope. Can the server actually synthesize the proposed endpoint from its existing capabilities? Otherwise, return 463 Proposal Rejected with reason: composition-impossible.
Policy acceptance. Does the server's policy permit the proposed method-and-path combination? Otherwise, return 463 with reason: policy-refused.

If all evaluations pass, the server synthesizes the endpoint and returns 263 Proposal Approved.

Synthesis-Composed Endpoints When a server synthesizes an endpoint, the server is composing the proposed behavior from existing endpoints internally. The synthesized endpoint is exposed to the agent as a single endpoint, but the server's handler implementation invokes one or more underlying endpoints to fulfill the request. Authority MUST be preserved through the composition. The agent's Authority-Scope MUST be sufficient for every underlying endpoint the synthesis invokes. If a composed step would require authority the agent lacks, the synthesis MUST fail at evaluation time (step 5), before any execution.

Session-Scoped vs Persistent Synthesis By default, a synthesized endpoint is session-scoped: it exists for the duration of the AGTP session that proposed it and is removed when the session ends. The agent MAY request persistent synthesis by setting persistent: true in the PROPOSE body; the server MAY honor or refuse the persistence request independently of the synthesis decision. Persistent synthesis subjects the proposed endpoint to the server's regular endpoint catalog and is reflected in subsequent manifest retrievals.

Code	Name	Returned When
261	Negotiation In Progress	Server has accepted PROPOSE for evaluation; agent polls via `QUERY /proposals/{proposal_id}` for terminal status
262	Authorization Required	Caller scope lock closed with the token granted but unclaimed: reason `scope-required scope: rcns:negotiate`. When the identity document omits the token the lock returns 455 Scope Violation per (see for the general semantics)
263	Proposal Approved	Server has synthesized and instantiated the proposed endpoint. Response body carries top-level `method` and `path` fields naming the synthesized endpoint, plus the full endpoint definition
461	RCNS Contract Available	Synthesis preview returned in confirm-first mode. Response body carries a contract preview with `synthesis_id`, resolved `(method, path)`, and the recipe lineage. Caller accepts by re-issuing with the `Contract-Synthesized` header
463	Proposal Rejected	Server cannot or declines to synthesize the proposed endpoint
464	RCNS No Contract	Synthesis attempted but no contract could be delivered. Response body carries one of the reasons in the RCNS vocabulary per