AGTP-RCNS: Runtime Contract Negotiation Substrate

1.1. Relationship to AGTP and AGTP-METHODS

Base AGTP defines the PROPOSE floor method, the negotiation status codes 261, 262, 263, 461, 463, and 464, the reason vocabulary for 461 and 464, the INSPECT target=contract and INSPECT target=rcns-attempt extensions, and the rcns_* lifecycle events. [AGTP-METHODS] defines the endpoint primitive that a synthesized contract instantiates, the tier taxonomy that classifies a contract as Tier C, the recipe-backed composition handler, and the manifest policy fields (synthesis_enabled, max_synthesis_depth) through which an operator advertises participation. This document defines everything between those two sets: when synthesis fires, what it produces, how the product is delivered, scoped, observed, and retired.¶

A server that implements [AGTP-METHODS] without this document is conformant and refuses unregistered pairs with 404 or 405. RCNS is an opt-in substrate; the default posture is off.¶

1.2. Document Lineage

The normative text in this document was carried in [AGTP-API] as the PROPOSE and Synthesis chapter and the DISCOVER /patterns and DISCOVER /contracts built-in endpoints. It is extracted here unchanged in substance so that the method vocabulary and the negotiation substrate can be reviewed, cited, and revised on their own timelines. Section anchors from [AGTP-API] are preserved where they appear.¶

1.3. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3.1. 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 [AGTP-METHODS]): 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 [AGTP] 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 [AGTP-METHODS] and the reservations in [AGTP] (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.¶

{
  "synthesis_id": "<opaque identifier>",
  "method": "BOOK",
  "path": "/room",
  "endpoint": { "..." : "..." },
  "recipe_lineage": {
    "recipe_name": "<recipe identifier>",
    "recipe_version": "<version string>"
  },
  "contract_hash": "<sha256 of canonical contract>",
  "expires_at": "<RFC 3339 timestamp>"
}

3.2. 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 [AGTP-METHODS] 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 [AGTP]. Its parameter table is specified there. This document specifies the synthesis semantics that govern server-side evaluation.¶

3.3. Negotiation Flow

Step 1:  Agent retrieves the server manifest (which carries the
         method policy as `policies.methods`)
Step 2:  Agent determines the needed endpoint is undeclared
Step 3:  Agent constructs a conformant endpoint definition
Step 4:  Agent sends PROPOSE with the endpoint definition in body
Step 5a: Server accepts and synthesizes
         Server evaluates contract conformance and capability envelope
         Server composes the endpoint from existing endpoints
         Server returns 263 Proposal Approved with the
           endpoint definition for the synthesized endpoint
         Synthesis-ID matches original proposal
         Synthesized endpoint is session-scoped by default
         Agent MAY invoke the endpoint immediately
Step 5b: Server rejects (463)
         Server returns 463 Proposal Rejected with structured reason
         Response SHOULD reference manifest entries that satisfy a
           similar capability if available
         Agent MAY modify proposal and retry (maximum 3 turns)
         After 3 rejections agent MUST ESCALATE

3.4. 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.¶

{
  "method": "PROPOSE",
  "task_id": "task-propose-01",
  "parameters": {
    "endpoint": {
      "method": "BOOK",
      "path": "/room",
      "description": "Books a room for the named guest.",
      "semantic": { "..." : "..." },
      "input_schema": { "..." : "..." },
      "output_schema": { "..." : "..." }
    },
    "persistent": false
  }
}

{
  "method": "PROPOSE",
  "task_id": "task-propose-02",
  "parameters": {
    "name": "book-room",
    "method": "BOOK",
    "path": "/room",
    "semantic": { "..." : "..." }
  }
}

{
  "status": 263,
  "method": "BOOK",
  "path": "/room",
  "synthesis_id": "<opaque identifier>",
  "endpoint": { "..." : "..." },
  "recipe_lineage": {
    "recipe_name": "<recipe identifier>",
    "recipe_version": "<version string>"
  }
}

3.5. 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:¶

1. The server MUST record the recipe's current version on the resulting contract record at synthesis time.¶

2. The server MUST present the captured version in the recipe_lineage.recipe_version field of the 263 response body (Section 3.4) and in any subsequent INSPECT target=contract response naming this contract.¶

3. 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.¶

4. 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 Section 3.1 (revoking specific synthesis_id values); recipes are never mutated in place.¶

3.6. Server-Side Synthesis Evaluation

On receipt of a PROPOSE request, the server MUST evaluate:¶

1. 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 ([AGTP-METHODS])? Otherwise, return 459 Method Violation.¶

2. Path conformance. Does the proposed path satisfy the path grammar in [AGTP-METHODS]? Otherwise, return 460 Endpoint Violation.¶

3. Semantic block conformance. Does the proposed semantic block carry all required fields with valid values? Otherwise, return 400 Bad Request.¶

4. Schema conformance. Are the input and output schemas valid JSON Schema documents? Otherwise, return 400 Bad Request.¶

5. 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 ([AGTP]).¶

6. Capability envelope. Can the server actually synthesize the proposed endpoint from its existing capabilities? Otherwise, return 463 Proposal Rejected with reason: composition-impossible.¶

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

3.7. 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.¶

3.8. 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.¶

4.1. DISCOVER /patterns

Servers SHOULD expose DISCOVER /patterns. The endpoint returns the inventory of synthesis patterns the server will negotiate against under RCNS: the operator-authored recipes (Section 3.5) and the (method, path) shapes those recipes match. The endpoint is reachable even when RCNS is disabled (Section 3.1.7); when RCNS is disabled, the response SHOULD indicate the disabled state so callers can distinguish "no patterns exist" from "patterns exist but synthesis is off."¶

{
  "rcns_enabled": true,
  "patterns": [
    {
      "recipe_name": "book-room",
      "recipe_version": "3",
      "method": "BOOK",
      "path_exact": "/room",
      "description": "Books a room for the named guest at the named property."
    }
  ]
}

The response MUST be a JSON object with rcns_enabled (boolean) and patterns (array). Each pattern entry MUST carry recipe_name, recipe_version, and method, plus exactly one of path_exact (byte-exact match) or path_regex (regular expression match against the request path). Servers MAY include additional descriptive fields (description, required_scopes, semantic) at their discretion; callers MUST ignore unknown fields.¶

The endpoint surfaces server posture explicitly: an agent inspecting DISCOVER /patterns knows in advance what (method, path) shapes the server will consider for synthesis.¶

4.2. DISCOVER /contracts

Servers that have ever synthesized at least one contract MUST expose DISCOVER /contracts. The endpoint returns active synthesized contracts, scoped by default to the requesting agent. Callers with the inspect:all Authority-Scope token receive contracts across all agents (operator visibility).¶

[
  {
    "synthesis_id": "<opaque>",
    "method": "BOOK",
    "path": "/room",
    "originating_agent_id": "<64 hex>",
    "recipe_lineage": {
      "recipe_name": "book-room",
      "recipe_version": "3"
    },
    "contract_hash": "<64 hex>",
    "negotiation_origin": "rcns-gate",
    "issued_at": "<RFC 3339>",
    "expires_at": "<RFC 3339>"
  }
]

The response is a JSON array. Each entry MUST carry synthesis_id, method, path, originating_agent_id, recipe_lineage, contract_hash, and negotiation_origin matching the Attribution-Record extension fields specified in Section 3.1.6. The issued_at and expires_at fields SHOULD be present.¶

A server MUST NOT return contracts whose originating_agent_id differs from the requesting Agent-ID, unless the request carries the inspect:all scope.¶

6.1. Synthesis Authority Preservation

The synthesis evaluation step (step 5 in Section 3.6) MUST verify that authority is preserved through composition. A synthesis that elevates authority by composing endpoints with sufficient individual scopes into a behavior the agent is barred from is a known threat. Servers MUST reject syntheses where the composed behavior exceeds what the agent's Authority-Scope permits, regardless of whether the individual steps are within scope.¶

7.1. Status Code Assignments

• 261 Negotiation In Progress¶

• 263 Proposal Approved¶

• 463 Proposal Rejected¶

7.2. Header Field Assignments

• Allow-RCNS (request)¶

• Contract-Synthesized (request and response)¶

• Idempotency-Key (request)¶

Semantics for each are specified in Section 3.1.5.¶

7.3. Scope Token

• rcns:negotiate, the Authority-Scope token that opens lock 3 of the dispatcher gate (Section 3.1.2), for the Authority-Scope token vocabulary maintained per [AGTP].¶

10.1. Normative References

[AGTP]

Hood, C., "Agent Transfer Protocol (AGTP)", Work in Progress, Internet-Draft, draft-hood-independent-agtp-10, 2026, <https://datatracker.ietf.org/doc/html/draft-hood-independent-agtp-10>.

[AGTP-METHODS]

Hood, C., "AGTP Methods (AGTP Verbs): Method Vocabulary, Path Grammar, and Endpoints", Work in Progress, Internet-Draft, draft-hood-agtp-methods-00, 2026, <https://datatracker.ietf.org/doc/html/draft-hood-agtp-methods-00>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

10.2. Informative References

[AGTP-API]

Hood, C., "AGTP-API: Verbs, Paths, Endpoints, and Synthesis", Work in Progress, Internet-Draft, draft-hood-agtp-api-01, 2026, <https://datatracker.ietf.org/doc/html/draft-hood-agtp-api-01>.

[AGTP-IDENTIFIERS]

Hood, C., "AGTP Identifier Chain", Work in Progress, Internet-Draft, draft-hood-agtp-identifiers-03, 2026, <https://datatracker.ietf.org/doc/html/draft-hood-agtp-identifiers-03>.

[AGTP-TRUST]

Hood, C., "AGTP Trust and Verification Specification", Work in Progress, Internet-Draft, draft-hood-agtp-trust-03, 2026, <https://datatracker.ietf.org/doc/html/draft-hood-agtp-trust-03>.