# drafts

name: draft-sovereign-satp
rev: 00
title: Sovereign Autonomous Trust Protocol (SATP) v1.0
time: 2026-05-02T20:40:54Z
group_uri: /api/v1/group/group/1027/
expires: 2026-11-03T20:40:53Z
states: ["/api/v1/doc/state/4/", "/api/v1/doc/state/150/"]
categories: ["Agent identity/auth", "Policy/governance"]
tags: []
fetched_at: 2026-05-22T09:24:50.092713+00:00
source: ietf
abstract:
  This document specifies the Sovereign Autonomous Trust Protocol
     (SATP), a foundational framework for establishing verifiable
     identity, attribution, and governance for autonomous machines.  SATP
     provides a non-repudiable "Root of Trust" for both digital AI agents
     and physical autonomous systems.

full_text:
  Network Working Group                                              S. AG
  Internet-Draft                                              Sovereign AG
  Intended status: Standards Track                              2 May 2026
  Expires: 3 November 2026


              Sovereign Autonomous Trust Protocol (SATP) v1.0
                          draft-sovereign-satp-00

  Abstract

     This document specifies the Sovereign Autonomous Trust Protocol
     (SATP), a foundational framework for establishing verifiable
     identity, attribution, and governance for autonomous machines.  SATP
     provides a non-repudiable "Root of Trust" for both digital AI agents
     and physical autonomous systems.

  Status of This Memo

     This Internet-Draft is submitted in full conformance with the
     provisions of BCP 78 and BCP 79.

     Internet-Drafts are working documents of the Internet Engineering
     Task Force (IETF).  Note that other groups may also distribute
     working documents as Internet-Drafts.  The list of current Internet-
     Drafts is at https://datatracker.ietf.org/drafts/current/.

     Internet-Drafts are draft documents valid for a maximum of six months
     and may be updated, replaced, or obsoleted by other documents at any
     time.  It is inappropriate to use Internet-Drafts as reference
     material or to cite them other than as "work in progress."

     This Internet-Draft will expire on 3 November 2026.

  Copyright Notice

     Copyright (c) 2026 IETF Trust and the persons identified as the
     document authors.  All rights reserved.

     This document is subject to BCP 78 and the IETF Trust's Legal
     Provisions Relating to IETF Documents (https://trustee.ietf.org/
     license-info) in effect on the date of publication of this document.
     Please review these documents carefully, as they describe your rights
     and restrictions with respect to this document.  Code Components
     extracted from this document must include Revised BSD License text as
     described in Section 4.e of the Trust Legal Provisions and are
     provided without warranty as described in the Revised BSD License.




  AG                       Expires 3 November 2026                [Page 1]


  Internet-Draft                  SATP v1.0                       May 2026


  Table of Contents

     1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   2
     3.  The Three Pillars of Trust  . . . . . . . . . . . . . . . . .   2
       3.1.  Pillar I: Decentralized Machine Identity (DID)  . . . . .   2
       3.2.  Pillar II: Just-In-Time (JIT) Authorization . . . . . . .   2
       3.3.  Pillar III: Immutable Audit Chain . . . . . . . . . . . .   3
     4.  Technical Architecture  . . . . . . . . . . . . . . . . . . .   3
       4.1.  Cryptographic Primitives  . . . . . . . . . . . . . . . .   3
       4.2.  High-Velocity Anchoring (6.42us)  . . . . . . . . . . . .   3
       4.3.  Autonomous Self-Healing . . . . . . . . . . . . . . . . .   3
     5.  Implementation Accessibility  . . . . . . . . . . . . . . . .   3
     6.  Conclusion  . . . . . . . . . . . . . . . . . . . . . . . . .   3
     Appendix A.  Appendix A: Reference Implementation . . . . . . . .   3
     Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   3

  1.  Introduction

     The proliferation of autonomous systems has created a "Trust Gap."
     SATP addresses this by establishing a decentralized,
     cryptographically anchored identity standard.

  2.  Terminology

     SATP  Sovereign Autonomous Trust Protocol.

     Root of Trust (RoT)  The foundational cryptographic anchor.

     Autonomous Machine (AM)  Any software or hardware entity capable of
        independent decision-making.

     Controller Entity  The legal organization responsible for the
        machine.

  3.  The Three Pillars of Trust

  3.1.  Pillar I: Decentralized Machine Identity (DID)

     Every autonomous unit is issued a permanent did:satp identifier
     anchored to a verified institutional controller.

  3.2.  Pillar II: Just-In-Time (JIT) Authorization

     SATP enforces a "Zero-Trust" model, issuing JIT authorization for
     specific tool-calls or mechanical operations.





  AG                       Expires 3 November 2026                [Page 2]


  Internet-Draft                  SATP v1.0                       May 2026


  3.3.  Pillar III: Immutable Audit Chain

     Every action is recorded to an NDJSON-based Usage Ledger, hashed and
     chained for tamper-proof auditing.

  4.  Technical Architecture

  4.1.  Cryptographic Primitives

     Utilizes Ed25519 for signatures and SHA-384 for ledger integrity.

  4.2.  High-Velocity Anchoring (6.42us)

     Achieves a mean Anchoring speed of 6.42 microseconds for mass-scale
     industrial deployment.

  4.3.  Autonomous Self-Healing

     Initiates autonomous recovery and rollback to the last verified
     anchor in the event of a breach.

  5.  Implementation Accessibility

     Designed for transparent integration via a cryptographic proxy,
     enabling one-line standard implementation.

  6.  Conclusion

     SATP is the definitive standard for the machine economy, enabling
     safe deployment at a multi-trillion dollar scale.

  Appendix A.  Appendix A: Reference Implementation

     Installation: pip install satp-sdk

     from satp import ProtocolAnchor

     @ProtocolAnchor.secure()
     def autonomous_action(payload):
         pass

  Author's Address

     Sovereign AG
     Sovereign AG
     Email: protocol@sovereign.ag





  AG                       Expires 3 November 2026                [Page 3]


name: draft-sovereign-svtp
rev: 00
title: Sovereign Verification & Trust Protocol (SVTP) v1.0
time: 2026-05-04T16:54:36Z
group_uri: /api/v1/group/group/1027/
expires: 2026-11-04T07:32:31Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["Agent identity/auth", "Policy/governance", "AI safety/alignment"]
tags: []
fetched_at: 2026-05-22T09:24:50.092721+00:00
source: ietf
abstract:
  This document specifies the Sovereign Verification & Trust Protocol
     (SVTP), a foundational framework for establishing verifiable
     identity, attribution, and governance for autonomous machines.
     SVTP provides a non-repudiable "Root of Trust" for both digital
     AI agents and physical autonomous systems (e.g., industrial
     robotics, autonomous vehicles). By defining the SVTP-DID
     (did:svtp) and the Protocol Seal mechanism, this standard
     enables secure machine-to-machine (M2M) interaction, automated
     compliance with NIST-800-218, and institutional-grade liability
     containment in the machine economy.

full_text:
  Network Working Group                                     S. AG (Sovereign)
  Internet-Draft                                              SVTP Protocol
  Intended status: Standards Track                              3 May 2026
  Expires: 3 November 2026


               Sovereign Verification & Trust Protocol (SVTP) v1.0
                           draft-sovereign-svtp-00

  Abstract

     This document specifies the Sovereign Verification & Trust Protocol
     (SVTP), a foundational framework for establishing verifiable
     identity, attribution, and governance for autonomous machines.
     SVTP provides a non-repudiable "Root of Trust" for both digital
     AI agents and physical autonomous systems (e.g., industrial
     robotics, autonomous vehicles). By defining the SVTP-DID
     (did:svtp) and the Protocol Seal mechanism, this standard
     enables secure machine-to-machine (M2M) interaction, automated
     compliance with NIST-800-218, and institutional-grade liability
     containment in the machine economy.

  Status of This Memo

     This Internet-Draft is submitted in full conformance with the
     provisions of BCP 78 and BCP 79.

     Internet-Drafts are working documents of the Internet Engineering
     Task Force (IETF). Note that other groups may also distribute
     working documents as Internet-Drafts. The list of current Internet-
     Drafts is at https://datatracker.ietf.org/drafts/current/.

     Internet-Drafts are draft documents valid for a maximum of six
     months and may be updated, replaced, or obsoleted by other
     documents at any time. It is inappropriate to use Internet-Drafts
     as reference material or to cite them other than as "work in
     progress."

     This Internet-Draft will expire on 3 November 2026.

  Additional Information and Repository Access

     Official Repository: https://github.com/Sovereign-AG/sovereign-core
     Official SDK: https://pypi.org/project/svtp-sdk/
     Project Website: https://svtp-protocol.org
     API Root Authority: https://api.sovereign.ag
     Governance Body: Sovereign AG
     Technical Compliance: NIST SP 800-218 (April 2026 Revision)

  Copyright Notice

     Copyright (c) 2026 IETF Trust and the persons identified as the
     document authors. All rights reserved.


     This document is subject to BCP 78 and the IETF Trust's Legal
     Provisions Relating to IETF Documents
     (https://trustee.ietf.org/license-info) in effect on the date of
     publication of this document.  Please review these documents
     carefully, as they describe your rights and restrictions with
     respect to this document.




  AG                       Expires 3 November 2026                [Page 1]


  Internet-Draft                  SVTP v1.0                       3 May 2026


  Table of Contents

     1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   2
     3.  The Three Pillars of Trust  . . . . . . . . . . . . . . . . .   2
       3.1.  Pillar I: Decentralized Machine Identity (DID)  . . . . .   2
       3.2.  Pillar II: Just-In-Time (JIT) Authorization . . . . . . .   2
       3.3.  Pillar III: Immutable Audit Chain . . . . . . . . . . . .   3
     4.  Technical Architecture  . . . . . . . . . . . . . . . . . . .   3
       4.1.  Cryptographic Primitives  . . . . . . . . . . . . . . . .   3
       4.2.  The Protocol Seal . . . . . . . . . . . . . . . . . . . .   3
       4.3.  High-Velocity Anchoring (6.42us Performance)  . . . . . .   3
       4.4.  Autonomous Self-Healing (Recovery and Continuity) . . . .   4
       4.5.  Global Revocation (The Kill-Switch) . . . . . . . . . . .   4
     5.  Compliance Mapping (NIST-800-218 and ISO-42001) . . . . . . .   4
     6.  Implementation Accessibility (Transparent Integration)  . . .   4
     7.  Protocol Economics  . . . . . . . . . . . . . . . . . . . . .   5
     8.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
     9.  Conclusion  . . . . . . . . . . . . . . . . . . . . . . . . .   5
     Appendix A.  Reference Implementation (Quickstart) . . . . . . . .   6
     Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   6

  1.  Introduction

     The proliferation of autonomous systems---ranging from large-scale
     language model agents to physical industrial automation---has created
     a "Trust Gap." Existing identity protocols (e.g., OAuth, SAML)
     assume a human-in-the-loop, which is insufficient for the
     high-velocity machine economy.

     SVTP addresses this by establishing a decentralized,
     cryptographically anchored identity standard. It moves away from
     "permission-based" trust toward "certainty-based" trust.

  2.  Terminology

     Sovereign Verification & Trust Protocol (SVTP): The core protocol
     defining the issuance and verification of machine trust.

     Root of Trust (RoT): The foundational cryptographic anchor that
     certifies the identity and behavioral bounds of a machine.

     Autonomous Machine (AM): Any software or hardware entity capable
     of independent decision-making and tool-execution.

     did:svtp: The decentralized identifier format specific to the
     SVTP standard.

     Controller Entity: The legal organization or institutional body
     responsible for the governance, liability, and cryptographic
     oversight of an Autonomous Machine.




  AG                       Expires 3 November 2026                [Page 2]


  Internet-Draft                  SVTP v1.0                       3 May 2026


  3.  The Three Pillars of Trust

     The SVTP framework is constructed upon three immutable pillars
     that ensure the integrity of the Universal Root of Trust.

  3.1.  Pillar I: Decentralized Machine Identity (DID)

     Every autonomous unit is issued a permanent did:svtp identifier.
     This identifier is cryptographically anchored to a verified
     institutional controller, ensuring that every machine has a
     verifiable "legal persona" in the machine economy.

  3.2.  Pillar II: Just-In-Time (JIT) Authorization

     SVTP enforces a "Zero-Trust" model for machine agency. Trust is
     not granted globally; it is issued JIT for specific tool-calls or
     mechanical operations. This minimizes the attack surface and
     prevents lateral movement in autonomous clusters.

  3.3.  Pillar III: Immutable Audit Chain (Usage Ledger)

     Every SVTP-certified action is recorded to an NDJSON-based Usage
     Ledger. Each entry is hashed and chained to the previous block,
     creating a tamper-proof record of autonomous decisions that
     satisfies international audit requirements.

  4.  Technical Architecture

  4.1.  Cryptographic Primitives

     SVTP utilizes Ed25519 for signature generation and SHA-384 for
     ledger integrity. These choices prioritize high-performance
     M2M throughput while maintaining quantum-resistant safety bounds.

  4.2.  The Protocol Seal

     For every high-fidelity action, the SVTP Root generates a
     "Protocol Seal." This seal acts as a cryptographic proof-of-intent,
     linking the machine's DID to a specific timestamp and action
     payload.

  4.3.  High-Velocity Anchoring (6.42us Performance)

     SVTP is optimized for mass-scale industrial deployment. The core
     protocol achieves a mean Anchoring and Handshake speed of 6.42
     microseconds. This allows for the near-instantaneous formation
     of secure identity anchors and M2M trust pathways, ensuring that
     dynamic fleets can be provisioned and secured without
     computational bottlenecking.




  AG                       Expires 3 November 2026                [Page 3]


  Internet-Draft                  SVTP v1.0                       3 May 2026


  4.4.  Autonomous Self-Healing (Recovery and Continuity)

     SVTP provides a unique "Self-Healing" mechanism for compromised
     nodes. In the event of a cryptographic breach or unauthorized
     behavioral drift, the protocol initiates an autonomous recovery
     sequence. Instead of a complete system cessation, the SVTP Root
     enforces a Rollback to the last verified anchor, re-issues a
     clean protocol seal, and restores the machine to a trusted state
     without service interruption. This ensures mission-critical
     continuity in hostile execution environments.

  4.5.  Global Revocation (The Kill-Switch)

     In the event of an anomalous variance, the SVTP Root Controller
     retains the ability to issue a global signature revocation. This
     operation propagates in <100ms, effectively "air-gapping" the
     rogue unit from the trusted ecosystem.

  5.  Compliance Mapping (NIST-800-218 and ISO-42001)

     SVTP is designed to satisfy the non-repudiation and identity
     provenance requirements of NIST SP 800-218. Furthermore, it
     aligns with ISO/IEC 42001 governance standards for trustworthy
     artificial intelligence systems.

  6.  Implementation Accessibility (Transparent Integration)

     A core design requirement of SVTP is "Low-Friction Adoption." The
     protocol is implemented via a high-performance Transparent Proxy
     Architecture. This allows institutions to wrap existing
     autonomous models and industrial control systems in the SVTP Root
     without modifying the underlying logic or model weights.

     By utilizing a single-line cryptographic wrapper, developers
     activate the Three Pillars of Trust (Identity, Auth, and Audit)
     instantaneously, ensuring rapid global standardization across
     legacy and genesis autonomous fleets.

  7.  Protocol Economics

     To ensure the sustainability of the Root of Trust, SVTP
     incorporates a three-tiered settlement mechanism:
     - MINT: Initial identity anchor formation ($1.00)
     - ACTION: High-fidelity tool-call verification ($0.01)
     - PULSE: Continuous system heartbeat monitoring ($0.0001)

  8.  Security Considerations

     SVTP assumes a "Hostile Execution" environment. By separating the
     identity layer from the model logic, it prevents prompt
     injection or mechanical variance from compromising the
     institutional root.



  AG                       Expires 3 November 2026                [Page 4]


  Internet-Draft                  SVTP v1.0                       3 May 2026


  9.  Conclusion

     SVTP (Sovereign Verification & Trust Protocol) is the definitive
     standard for the machine economy. By providing a universal Root
     of Trust, it enables the safe and verifiable deployment of
     autonomous intelligence at a multi-trillion dollar scale.

  Appendix A.  Reference Implementation (Quickstart)

     To demonstrate the feasibility and low-friction adoption of the
     SVTP standard, a reference SDK is provided for rapid
     integration.

     A.1. Installation

        $ pip install svtp-sdk

     A.2. One-Line Standard Implementation

        The following snippet demonstrates the transparent wrapping of
        an autonomous function to activate SVTP Three-Pillar
        governance:

        from svtp_sdk import ProtocolAnchor

        @ProtocolAnchor.secure()
        def autonomous_action(payload):
            # SVTP Root of Trust Active
            # Non-repudiable Audit and DID Attestation Enabled
            pass

     A.3. Verification

        Institutional controllers can verify the SVTP integrity of any
        machine action via the global trust endpoint:

        $ svtp-verify --did did:svtp:72a1 --seal <PROTOCOL_SEAL>

  Author's Address

     Sovereign AG
     Email: office.sovereign.ag@gmail.com




  AG                       Expires 3 November 2026                [Page 5]


name: draft-abbott-mcp-ax
rev: 00
time: 2026-05-05T02:55:34Z
group_uri: /api/v1/group/group/1027/
expires: 2026-11-06T02:55:34Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["A2A protocols", "Data formats/interop", "Agent discovery/reg"]
tags: []
fetched_at: 2026-05-22T09:24:50.092725+00:00
source: ietf
title:
  MCP Aggregation Protocol (MCP-AX): Hierarchical Tool Namespace Delegation for Model Context Protocol Servers

abstract:
  This document specifies MCP-AX, an aggregation protocol for Model
     Context Protocol (MCP) servers.  MCP-AX enables hierarchical
     composition of tool namespaces across heterogeneous networks of MCP
     servers, from cloud services to resource-constrained embedded
     devices.  The protocol defines a master-subagent architecture
     directly inspired by the AgentX protocol (RFC 2741), adapted for the
     tool/resource model of MCP rather than the OID/MIB model of SNMP.

     MCP-AX introduces recursive namespace delegation, capability-aware
     routing, transport bridging for constrained nodes, and
     irreversibility-gated tool dispatch suitable for autonomous and semi-
     autonomous AI agent systems.

full_text:
  Independent Submission                                         I. Abbott
  Internet-Draft                                                SoftOboros
  Intended status: Experimental                                 4 May 2026
  Expires: 5 November 2026


       MCP Aggregation Protocol (MCP-AX): Hierarchical Tool Namespace
               Delegation for Model Context Protocol Servers
                           draft-abbott-mcp-ax-00

  Abstract

     This document specifies MCP-AX, an aggregation protocol for Model
     Context Protocol (MCP) servers.  MCP-AX enables hierarchical
     composition of tool namespaces across heterogeneous networks of MCP
     servers, from cloud services to resource-constrained embedded
     devices.  The protocol defines a master-subagent architecture
     directly inspired by the AgentX protocol (RFC 2741), adapted for the
     tool/resource model of MCP rather than the OID/MIB model of SNMP.

     MCP-AX introduces recursive namespace delegation, capability-aware
     routing, transport bridging for constrained nodes, and
     irreversibility-gated tool dispatch suitable for autonomous and semi-
     autonomous AI agent systems.

  Status of This Memo

     This Internet-Draft is submitted in full conformance with the
     provisions of BCP 78 and BCP 79.

     Internet-Drafts are working documents of the Internet Engineering
     Task Force (IETF).  Note that other groups may also distribute
     working documents as Internet-Drafts.  The list of current Internet-
     Drafts is at https://datatracker.ietf.org/drafts/current/.

     Internet-Drafts are draft documents valid for a maximum of six months
     and may be updated, replaced, or obsoleted by other documents at any
     time.  It is inappropriate to use Internet-Drafts as reference
     material or to cite them other than as "work in progress."

     This Internet-Draft will expire on 5 November 2026.

  Copyright Notice

     Copyright (c) 2026 IETF Trust and the persons identified as the
     document authors.  All rights reserved.





  Abbott                   Expires 5 November 2026                [Page 1]


  Internet-Draft                   MCP-AX                         May 2026


     This document is subject to BCP 78 and the IETF Trust's Legal
     Provisions Relating to IETF Documents (https://trustee.ietf.org/
     license-info) in effect on the date of publication of this document.
     Please review these documents carefully, as they describe your rights
     and restrictions with respect to this document.

  Table of Contents

     1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
       1.1.  Design Goals  . . . . . . . . . . . . . . . . . . . . . .   4
       1.2.  Distinction from API Gateways . . . . . . . . . . . . . .   5
       1.3.  Relationship to AgentX  . . . . . . . . . . . . . . . . .   5
       1.4.  MCP Governance Note . . . . . . . . . . . . . . . . . . .   6
     2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   6
     3.  Architecture Overview . . . . . . . . . . . . . . . . . . . .   7
       3.1.  Topology  . . . . . . . . . . . . . . . . . . . . . . . .   7
       3.2.  Transparency  . . . . . . . . . . . . . . . . . . . . . .   7
     4.  Namespace Model . . . . . . . . . . . . . . . . . . . . . . .   7
       4.1.  Namespace Syntax  . . . . . . . . . . . . . . . . . . . .   7
       4.2.  Registration and Ownership  . . . . . . . . . . . . . . .   8
       4.3.  Namespace Isolation . . . . . . . . . . . . . . . . . . .   8
     5.  Aggregator Behavior . . . . . . . . . . . . . . . . . . . . .   8
       5.1.  tools/list Handling . . . . . . . . . . . . . . . . . . .   9
       5.2.  tools/call Routing  . . . . . . . . . . . . . . . . . . .   9
       5.3.  Recursive Aggregation . . . . . . . . . . . . . . . . . .   9
     6.  Registration Protocol . . . . . . . . . . . . . . . . . . . .   9
       6.1.  Registration Request  . . . . . . . . . . . . . . . . . .   9
       6.2.  Registration Response . . . . . . . . . . . . . . . . . .  10
       6.3.  Heartbeat and Deregistration  . . . . . . . . . . . . . .  11
     7.  Tool Dispatch and Routing . . . . . . . . . . . . . . . . . .  11
       7.1.  Routing Table . . . . . . . . . . . . . . . . . . . . . .  11
       7.2.  Request and Response Transformation . . . . . . . . . . .  11
       7.3.  Timeout Propagation . . . . . . . . . . . . . . . . . . .  12
     8.  Transport Bridging  . . . . . . . . . . . . . . . . . . . . .  12
       8.1.  Gateway Role  . . . . . . . . . . . . . . . . . . . . . .  12
       8.2.  CBOR-MCP Mapping  . . . . . . . . . . . . . . . . . . . .  13
       8.3.  Stub Requirements . . . . . . . . . . . . . . . . . . . .  13
     9.  Capability Metadata . . . . . . . . . . . . . . . . . . . . .  14
       9.1.  Capability Annotation Schema  . . . . . . . . . . . . . .  14
       9.2.  Aggregator Annotation Obligations . . . . . . . . . . . .  14
     10. Security Considerations . . . . . . . . . . . . . . . . . . .  14
       10.1.  Per-Hop Authentication . . . . . . . . . . . . . . . . .  14
       10.2.  Scope Restriction  . . . . . . . . . . . . . . . . . . .  15
       10.3.  Namespace Spoofing Prevention  . . . . . . . . . . . . .  15
       10.4.  Transport Security . . . . . . . . . . . . . . . . . . .  15
     11. Irreversibility and Safety Gates  . . . . . . . . . . . . . .  15
       11.1.  Motivation . . . . . . . . . . . . . . . . . . . . . . .  15
       11.2.  Irreversibility Classification . . . . . . . . . . . . .  15



  Abbott                   Expires 5 November 2026                [Page 2]


  Internet-Draft                   MCP-AX                         May 2026


       11.3.  Gate Enforcement . . . . . . . . . . . . . . . . . . . .  15
       11.4.  Agent Budget Propagation . . . . . . . . . . . . . . . .  16
     12. Notification Aggregation  . . . . . . . . . . . . . . . . . .  16
     13. Failure Modes and Recovery  . . . . . . . . . . . . . . . . .  17
       13.1.  Subserver Failure  . . . . . . . . . . . . . . . . . . .  17
       13.2.  Degraded Mode  . . . . . . . . . . . . . . . . . . . . .  17
       13.3.  Aggregator Failure . . . . . . . . . . . . . . . . . . .  17
       13.4.  Split-Brain Prevention . . . . . . . . . . . . . . . . .  18
     14. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  18
     15. References  . . . . . . . . . . . . . . . . . . . . . . . . .  18
       15.1.  Normative References . . . . . . . . . . . . . . . . . .  18
       15.2.  Informative References . . . . . . . . . . . . . . . . .  19
     Appendix A: AgentX Full Correspondence Table  . . . . . . . . . .  20
     Appendix B: Embedded Stub Reference Profiles  . . . . . . . . . .  21
       B.1 Profile A -- Table Stub . . . . . . . . . . . . . . . . . .  21
       B.2 Profile B -- Self-Describing Stub . . . . . . . . . . . . .  22
       B.3 Boot Sequence . . . . . . . . . . . . . . . . . . . . . . .  22
       B.4 Gateway Responsibilities  . . . . . . . . . . . . . . . . .  23
     Appendix C: Example Topologies  . . . . . . . . . . . . . . . . .  23
       C.1 Enterprise SaaS Aggregation . . . . . . . . . . . . . . . .  23
       C.2 Industrial IoT with Edge Gateway  . . . . . . . . . . . . .  24
       C.3 Recursive Regional Hierarchy  . . . . . . . . . . . . . . .  24
     Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  24
     Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  25

  1.  Introduction

     The Model Context Protocol (MCP) [MCP] defines a client-server
     architecture in which an AI model (the client) discovers and invokes
     tools, reads resources, and receives notifications from MCP servers.
     As deployment scales from single-server configurations to enterprise,
     IoT, and hybrid cloud/edge topologies, the need arises for
     hierarchical aggregation of MCP servers behind a unified namespace.

     This problem is not new.  SNMP encountered identical scaling
     constraints in the 1990s and produced AgentX [RFC2741], which defined
     a master agent / subagent architecture for delegating OID subtrees.
     The structural correspondence is direct:













  Abbott                   Expires 5 November 2026                [Page 3]


  Internet-Draft                   MCP-AX                         May 2026


              +==================+=============================+
              | AgentX Concept   | MCP-AX Concept              |
              +==================+=============================+
              | Master Agent     | Root Aggregator             |
              +------------------+-----------------------------+
              | Subagent         | Subserver                   |
              +------------------+-----------------------------+
              | OID Subtree      | Tool Namespace Prefix       |
              +------------------+-----------------------------+
              | MIB Registration | Tool Registration           |
              +------------------+-----------------------------+
              | ax.Register PDU  | mcpax/register              |
              +------------------+-----------------------------+
              | ax.Get/GetNext   | tools/call (routed)         |
              +------------------+-----------------------------+
              | MIB Walk         | tools/list (recursive)      |
              +------------------+-----------------------------+
              | ax.Notify PDU    | MCP notification (prefixed) |
              +------------------+-----------------------------+
              | ax.Ping PDU      | mcpax/heartbeat             |
              +------------------+-----------------------------+
              | Session ID       | session_id                  |
              +------------------+-----------------------------+

                                   Table 1

     This document specifies the MCP-AX protocol, adapting the AgentX
     model for MCP's tool/resource/notification primitives.

  1.1.  Design Goals

     (a)  A model client MUST be able to interact with an MCP-AX
          aggregator using unmodified MCP protocol.  Aggregation is
          transparent to the client.

     (b)  Namespace delegation MUST be recursive: an aggregator MAY
          register as a subserver of a parent aggregator, forming an
          arbitrarily deep hierarchy.

     (c)  Resource-constrained devices, including those with RAM budgets
          below 4 KiB, MUST be supportable through a gateway aggregator by
          means of a bounded stub profile.  The protocol MUST NOT assume
          that participating nodes can parse JSON, manage sessions,
          perform authentication, negotiate schemas, or store fully
          qualified tool names.  These are gateway responsibilities, not
          leaf requirements.  The stub profile defines the minimum
          contract between a constrained device and its gateway; the
          gateway maps that contract into MCP-AX on behalf of the device.



  Abbott                   Expires 5 November 2026                [Page 4]


  Internet-Draft                   MCP-AX                         May 2026


     (d)  Tool dispatch MUST carry capability metadata sufficient for the
          client to reason about latency, mutability, and reversibility
          without knowledge of the routing topology.

     (e)  Security context MUST NOT bleed across aggregation boundaries.
          Each hop authenticates independently.

  1.2.  Distinction from API Gateways

     HTTP reverse proxies and API gateways (nginx, Envoy, Kong) route
     requests by URI path or header.  MCP-AX differs in four respects that
     are not achievable through gateway configuration alone:

     (a)  Recursive namespace delegation: aggregation depth is unbounded
          and each hop is itself an MCP-AX participant, not a transparent
          proxy.

     (b)  Capability propagation: tool metadata (latency class,
          mutability, reversibility, consistency) is a first-class
          protocol element, not an out-of-band annotation.

     (c)  Safety semantics: irreversibility gates and agent budget
          enforcement operate on tool-call semantics, not HTTP verbs.

     (d)  Embedded transport bridging: sub-TCP transports (UART, BLE, CAN,
          SPI) with CBOR encoding are protocol-native, not bolted on via
          sidecar.

  1.3.  Relationship to AgentX

     MCP-AX is a spiritual successor to AgentX [RFC2741], not a profile or
     extension of it.  The wire protocol is MCP JSON-RPC, not AgentX PDUs.
     However, the registration semantics, namespace delegation model, and
     master/subagent lifecycle are directly derived from AgentX, which is
     cited as a normative architectural reference.

     The term "agent" -- used independently in SNMP network management
     (1988), AgentX subagent delegation (1999), and contemporary AI agent
     systems (2024) -- names the same abstraction at three different
     layers of the stack.  MCP-AX makes this recursion explicit.











  Abbott                   Expires 5 November 2026                [Page 5]


  Internet-Draft                   MCP-AX                         May 2026


  1.4.  MCP Governance Note

     MCP originated at Anthropic in November 2024.  In December 2025,
     Anthropic, Block, and OpenAI contributed MCP and the Agent-to-Agent
     (A2A) protocol to the Agentic AI Foundation (AAIF), a Linux
     Foundation project.  MCP-AX treats MCP as a stable external
     specification and cites it accordingly.  Should MCP be submitted as
     an IETF RFC in future, the normative reference herein should be
     updated.

     Several IETF Internet-Drafts have already referenced MCP as an
     external specification for network management use cases
     [I-D.zeng-mcp-network-mgmt] [I-D.zeng-mcp-network-measurement]
     [I-D.zeng-mcp-troubleshooting].  MCP-AX follows this precedent.

  2.  Terminology

     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
     "SHOULD", "SHOULD NOT", "RECOMMENDED", "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.

     Aggregator:  An MCP server that exposes a unified tool namespace
        composed from one or more downstream MCP servers (subservers).
        Analogous to an AgentX master agent.

     Subserver:  An MCP server that registers its tools with an upstream
        aggregator.  Analogous to an AgentX subagent.

     Leaf Server:  A subserver that does not itself aggregate other
        servers.  Terminal node in the hierarchy.

     Gateway:  An aggregator that additionally performs transport bridging
        (e.g., UART/CBOR to HTTP/JSON) for constrained subservers.

     Namespace Prefix:  A dot-delimited string prepended to tool names
        during registration to establish hierarchical ownership.
        Analogous to an OID subtree in AgentX.

     Tool Route:  The ordered list of aggregator segments from root to the
        leaf server that owns a tool.

     Capability Annotation:  Metadata attached to a tool registration
        describing latency class, mutability, reversibility, and transport
        characteristics.

     Stub:  A minimal MCP implementation on a constrained device,



  Abbott                   Expires 5 November 2026                [Page 6]


  Internet-Draft                   MCP-AX                         May 2026


        supporting only tools/list and tools/call over a compact transport
        encoding.

  3.  Architecture Overview

  3.1.  Topology

     MCP-AX defines a tree topology rooted at one or more root
     aggregators.  The model client connects to the root aggregator and
     sees a flat, fully-qualified tool namespace.

                           Model Client
                                |
                                | (standard MCP)
                                |
                         Root Aggregator (R)
                           /           \
                          /             \
                     Regional Agg (A)   Local Server (L)
                        /       \
                       /         \
                     Cloud (C)  Edge Gateway (G)
                                    /       \
                                   /         \
                             MCU Stub (M1)  MCU Stub (M2)
                             (UART/CBOR)    (BLE/CBOR)

     Each non-leaf node is an aggregator.  Each aggregator accepts
     registrations from downstream subservers, prepends its namespace
     prefix to registered tool names, exposes the merged namespace
     upstream, and routes tools/call requests to the owning subserver.

  3.2.  Transparency

     The model client issues standard MCP requests.  It receives tools/
     list responses containing fully qualified (prefixed) tool names and
     capability annotations.  It issues tools/call with the fully
     qualified name.  The aggregation hierarchy is opaque to the client
     except as revealed by namespace structure and capability metadata.

  4.  Namespace Model

  4.1.  Namespace Syntax

     Tool names in MCP-AX use dot-delimited hierarchical segments:

               <root-segment>.<aggregator-segment>*.<local-name>




  Abbott                   Expires 5 November 2026                [Page 7]


  Internet-Draft                   MCP-AX                         May 2026


     Example: infra.edge.stm32h7.dma2d_status

     Segments MUST match the regular expression [a-z0-9_-]{1,63}.  The
     total fully qualified name MUST NOT exceed 255 characters.

  4.2.  Registration and Ownership

     When a subserver registers with an aggregator, it provides its local
     tool list (via tools/list) and a requested namespace segment.  The
     aggregator validates the segment for uniqueness among current
     registrations.  First-registered-wins semantics apply, consistent
     with AgentX [RFC2741] Section 7.1.5.1.  A conflict MUST result in
     rejection with error "namespace_conflict".

     A subserver MAY include an "authority" field in its registration
     request, using DNS name syntax (e.g.,
     "dns:edge01.factory.example.com").  When present, the (authority,
     segment) pair constitutes the ownership claim.  An aggregator MAY
     reject re-registration of a segment by a different authority, even
     after the original session has expired.  This provides stable
     namespace ownership across session churn, failover, and multi-root
     federation without requiring a global registry.

     An authority claim is an assertion, not proof.  Without verification,
     a rogue subserver connecting after a reboot can claim an authority
     string it does not own.  For namespaces containing mutable or
     irreversible-mutable tools, aggregators SHOULD require cryptographic
     proof of authority: a signed JWT bearing the authority DNS name as
     subject, a client certificate whose SAN matches the claimed
     authority, or equivalent.  Aggregators MAY accept unverified
     authority claims for read-only or development namespaces where the
     risk of impersonation is acceptably low.

  4.3.  Namespace Isolation

     A subserver MUST NOT register tools with names containing the dot
     separator.  Hierarchical depth is achieved only through recursive
     aggregation, not through subserver self-prefixing.  This prevents
     namespace spoofing: the aggregator is the sole authority for prefix
     assignment.

  5.  Aggregator Behavior









  Abbott                   Expires 5 November 2026                [Page 8]


  Internet-Draft                   MCP-AX                         May 2026


  5.1.  tools/list Handling

     Upon receiving tools/list from upstream (or from the model client),
     the aggregator returns its cached merged namespace if valid.
     Otherwise, it issues tools/list to each registered subserver,
     prefixes results, merges, caches (RECOMMENDED TTL: 60 seconds), and
     returns.

  5.2.  tools/call Routing

     Upon receiving tools/call for a fully qualified tool name, the
     aggregator looks up the tool in its routing table, advances the route
     cursor (Section 7.2), forwards the request to the downstream session,
     and returns the response.  If the tool name is not found, the
     aggregator MUST return error code -32601 (method not found).

  5.3.  Recursive Aggregation

     An aggregator MAY itself register as a subserver of a parent
     aggregator, presenting its merged namespace for further prefixing.
     There is no protocol-imposed depth limit; implementations SHOULD
     support at least 8 levels.

     Implementations MUST detect and reject registration cycles.  When an
     aggregator registers as a subserver of a parent, it MUST include its
     own aggregator_id and the aggregator_ids of all its downstream
     subservers in the registration request's "x-mcpax-subtree-ids" field.
     The parent MUST reject the registration if its own aggregator_id
     appears in that set.  This provides cycle detection at registration
     time with no runtime overhead on tool dispatch.

  6.  Registration Protocol

  6.1.  Registration Request

















  Abbott                   Expires 5 November 2026                [Page 9]


  Internet-Draft                   MCP-AX                         May 2026


     {
       "jsonrpc": "2.0",
       "method": "mcpax/register",
       "id": 1,
       "params": {
         "subserver_id": "550e8400-e29b-41d4-a716-446655440000",
         "segment": "stm32h7",
         "authority": "dns:edge01.factory.example.com",
         "capabilities": {
           "tools": true,
           "resources": false,
           "notifications": true
         },
         "heartbeat_interval_ms": 5000,
         "transport_class": "uart_cbor",
         "version": "2026-05-01"
       }
     }

     The "subserver_id" field is a stable UUID that persists across
     sessions and reboots.  The "authority" field is OPTIONAL; see
     Section 4.2.  Together with the aggregator's own identity, these
     fields enable deterministic split-brain detection (Section 13.4).

  6.2.  Registration Response

     {
       "jsonrpc": "2.0",
       "id": 1,
       "result": {
         "status": "registered",
         "assigned_segment": "stm32h7",
         "session_id": "a3f7c...",
         "heartbeat_deadline_ms": 15000,
         "budget": {
           "max_calls_per_minute": 60,
           "max_mutable_calls_per_session": 10
         }
       }
     }











  Abbott                   Expires 5 November 2026               [Page 10]


  Internet-Draft                   MCP-AX                         May 2026


  6.3.  Heartbeat and Deregistration

     If heartbeat_interval_ms is non-zero, the subserver MUST send "mcpax/
     heartbeat" within each interval.  Three consecutive missed heartbeats
     trigger automatic deregistration.  A subserver may also send "mcpax/
     deregister" explicitly.  Upon deregistration, the aggregator MUST
     remove all tools from that subserver's namespace within one heartbeat
     interval and re-advertise upstream.

     These semantics mirror AgentX session timeout (Section 7.1.1 of
     [RFC2741]).

  7.  Tool Dispatch and Routing

  7.1.  Routing Table

     {
       "infra.edge.stm32h7.dma2d_status": {
         "downstream_session": "a3f7c...",
         "downstream_name":    "dma2d_status",
         "capability":         { ... },
         "registered_at":      "2026-05-01T12:00:00Z"
       }
     }

  7.2.  Request and Response Transformation

     Routing uses a cursor model rather than string manipulation.  Each
     tools/call request carries an "x-mcpax-route" array containing the
     full sequence of namespace segments from root to leaf, and an "x-
     mcpax-cursor" integer indicating the current position in that array.
     Each aggregator increments the cursor by one and forwards the request
     downstream.  The downstream server uses the segment at the cursor
     position to identify itself and dispatches to the tool named by the
     final segment.

     Example for tool "infra.edge.stm32h7.dma2d_status":

     "x-mcpax-route":  ["infra", "edge", "stm32h7", "dma2d_status"],
     "x-mcpax-cursor": 0

     Root aggregator matches "infra" at cursor 0, increments to 1,
     forwards.  Regional aggregator matches "edge" at cursor 1, increments
     to 2, forwards.  Gateway matches "stm32h7" at cursor 2, increments to
     3, dispatches tool "dma2d_status".






  Abbott                   Expires 5 November 2026               [Page 11]


  Internet-Draft                   MCP-AX                         May 2026


     This avoids string parsing errors, supports non-string namespace
     encodings in future extensions (integer IDs, hashes), and preserves
     the full route for diagnostics at every hop.

     The response is forwarded upstream without modification to the result
     field.  The aggregator MAY add "x-mcpax-latency-ms" to response
     metadata.

  7.3.  Timeout Propagation

     The aggregator SHOULD set downstream request timeouts based on the
     capability annotation's latency_class:

                      +===============+================+
                      | latency_class | Timeout        |
                      +===============+================+
                      | realtime      | 500 ms         |
                      +---------------+----------------+
                      | fast          | 5 s            |
                      +---------------+----------------+
                      | standard      | 30 s           |
                      +---------------+----------------+
                      | slow          | 120 s          |
                      +---------------+----------------+
                      | batch         | caller-managed |
                      +---------------+----------------+

                                   Table 2

  8.  Transport Bridging

  8.1.  Gateway Role

     A gateway translates between MCP's native transport (HTTP+SSE or
     stdio) and constrained transports used by embedded stubs.  Defined
     bridged transport classes:

     *  uart_cbor: UART with COBS framing, CBOR payload

     *  ble_cbor: BLE GATT characteristics, CBOR payload

     *  spi_cbor: SPI with length-prefix framing, CBOR payload

     *  can_cbor: CAN bus with ISO-TP segmentation, CBOR payload

     *  mqtt_json: MQTT topics, JSON payload





  Abbott                   Expires 5 November 2026               [Page 12]


  Internet-Draft                   MCP-AX                         May 2026


  8.2.  CBOR-MCP Mapping

     The gateway maintains a bidirectional mapping between MCP JSON-RPC
     and a compact CBOR [RFC7049] representation.  Tool names are replaced
     with integer IDs assigned at registration time.  JSON-RPC envelope
     fields "jsonrpc", "method", "id" map to CBOR map keys 0, 1, 2
     respectively.  Schema validation occurs at the gateway, not on the
     stub.

     The gateway MUST strip all "x-mcpax-*" metadata (route array, cursor,
     hop count, latency annotations) before translating a request to the
     stub transport.  A constrained stub receives only its integer tool ID
     and the CBOR-encoded arguments.  Routing metadata is a gateway
     concern; it MUST NOT leak onto constrained transports where every
     byte has a cost.

     The combination of integer tool IDs, typed argument schemas, and
     gateway-side validation constitutes a minimal interface description
     for constrained environments -- functionally equivalent to the subset
     of IDL semantics required for RPC dispatch, without requiring a
     separate schema language or code generator on the stub.

  8.3.  Stub Requirements

     An MCP-AX stub MUST NOT be required to parse JSON, implement HTTP or
     SSE, manage sessions, perform authentication, or store fully
     qualified tool names.  These responsibilities are fully delegated to
     the gateway.  Two stub profiles are defined:

     Profile A -- Table Stub:  No self-description capability.  The
        gateway owns all tool schemas and maps integer command IDs to MCP-
        AX tool names from its own configuration.  The device exposes
        numeric command IDs only.  Suitable for devices with no dynamic
        discovery requirement, including legacy 8-bit microcontrollers.

     Profile B -- Self-Describing Stub:  Announces tool IDs and compact
        schemas at boot or on gateway request via CBOR registration
        frames.  Suitable for Cortex-M0+, AVR, MSP430, and equivalent
        16/32-bit devices.

     Profile A target resource budget: effectively zero dynamic RAM for
     protocol state; the command table is ROM-resident and the gateway
     handles everything else.  Profile B target: fewer than 2 KB flash
     code, fewer than 256 bytes RAM for request/response buffers.  See
     Appendix "Appendix B: Embedded Stub Reference Profiles" for reference
     descriptor structures for both profiles.





  Abbott                   Expires 5 November 2026               [Page 13]


  Internet-Draft                   MCP-AX                         May 2026


  9.  Capability Metadata

  9.1.  Capability Annotation Schema

     {
       "latency_class":  "realtime|fast|standard|slow|batch",
       "consistency":    "strong|eventual|best_effort",
       "mutable":        boolean,
       "reversible":     boolean,
       "idempotent":     boolean,
       "transport":      "native|uart_cbor|ble_cbor|...",
       "auth_scope":     "read|write|admin",
       "cost_class":     "free|metered|expensive",
       "availability":   "always|scheduled|best_effort|degraded",
       "schema_version": "<semver>"
     }

     The "consistency" field indicates the data consistency model of the
     tool's backing state.  Agents SHOULD use this to determine whether
     parallel invocations across tools in the same subtree may observe
     stale state, and whether retry after failure requires read-before-
     write verification.

     The "availability" value "degraded" indicates that the tool remains
     listed but may return structured error responses for some or all
     invocations.  This supports partial-failure semantics required by
     industrial control and observability pipelines where binary present/
     absent is insufficient.  See Section 13.2.

  9.2.  Aggregator Annotation Obligations

     The aggregator MUST propagate capability annotations upstream without
     modification.  It MUST add "x-mcpax-hops" indicating the aggregation
     depth.  It MUST adjust "latency_class" upward if the aggregation path
     introduces latency that changes the effective class; it MUST NOT
     adjust latency_class downward.

  10.  Security Considerations

  10.1.  Per-Hop Authentication

     Each aggregation boundary is an authentication boundary.  Credentials
     MUST NOT be forwarded across aggregation hops.  This is the critical
     lesson from SNMP's community string model [RFC3414]: transitive
     credential forwarding violates least privilege.  MCP-AX mandates
     independent authentication at each hop, with tokens scoped to the
     immediate downstream session per [RFC8707].




  Abbott                   Expires 5 November 2026               [Page 14]


  Internet-Draft                   MCP-AX                         May 2026


  10.2.  Scope Restriction

     An aggregator MUST scope the authorization context per registered
     subserver.  A subserver registered with auth_scope "read" MUST NOT
     receive requests that imply "write" or "admin" operations.

  10.3.  Namespace Spoofing Prevention

     The prohibition on subserver self-prefixing (Section 4.3) prevents a
     malicious subserver from registering tools that appear to belong to a
     different subtree.  The aggregator is the sole authority for prefix
     assignment.

  10.4.  Transport Security

     Aggregator-to-aggregator links MUST use TLS 1.3 or equivalent.
     Gateway-to-stub links (UART, SPI, BLE) operate in physically
     constrained environments where TLS may be infeasible.  Gateways MUST
     treat stub-provided data as untrusted and validate all inputs against
     the registered schema before forwarding upstream.

  11.  Irreversibility and Safety Gates

  11.1.  Motivation

     When the model client is an autonomous AI agent, tool invocations may
     have real-world consequences that are difficult or impossible to
     reverse.  The aggregation hierarchy is the natural enforcement point
     for safety policy: the aggregator has visibility into the blast
     radius of downstream operations that individual leaf servers lack.

  11.2.  Irreversibility Classification

     Tools with "reversible": false and "mutable": true are classified as
     irreversible-mutable and MUST be flagged with "x-mcpax-safety":
     "irreversible_mutable" in the namespace.

  11.3.  Gate Enforcement

     An aggregator operating in "gated" mode MUST intercept tools/call
     requests targeting irreversible-mutable tools, return a
     "confirmation_required" response to the client (including tool name,
     arguments, capability annotation, and route), and await "mcpax/
     confirm" before dispatching downstream.  Unconfirmed requests expire
     after a configurable timeout (default: 300 seconds).






  Abbott                   Expires 5 November 2026               [Page 15]


  Internet-Draft                   MCP-AX                         May 2026


     The "mcpax/confirm" request MUST include a "proof" field containing a
     cryptographic token obtained from an authority external to the
     requesting model client.  Acceptable proof types include: a signature
     from a human operator's key pair, a signed nonce from an external
     policy engine, or an approval token from an out-of-band authorization
     service.  The aggregator MUST validate the proof against a configured
     trust anchor before dispatching the gated request.

     Without this requirement, an autonomous model client can trivially
     self-confirm by issuing "mcpax/confirm" immediately after receiving
     "confirmation_required", rendering the gate ineffective.  The proof
     field ensures that confirmation requires a cryptographic assertion
     that the model client cannot manufacture from its own context.

     Safety Gate Monotonicity: once a request is classified as requiring
     confirmation at any hop in the aggregation hierarchy, all upstream
     hops MUST preserve that requirement.  No aggregator or client MAY
     remove or downgrade a gate introduced by a downstream aggregator.
     Any aggregator MAY escalate an ungated request to gated; none MAY de-
     escalate.  This ensures that the most conservative policy in the path
     governs.

  11.4.  Agent Budget Propagation

     Budget enforcement (max_calls_per_minute,
     max_mutable_calls_per_session, max_cost_units_per_session) is per-
     session, declared in the registration response, and non-negotiable.
     A subserver exceeding its budget MUST receive error -32003
     ("budget_exceeded").

  12.  Notification Aggregation

     Subserver notifications are prefixed with the originating namespace
     segment and forwarded upstream.  The aggregator MUST NOT reorder
     notifications from a single subserver.

     The aggregator MUST implement per-subserver rate limiting (default:
     100/second).  If exceeded, the aggregator buffers up to a
     configurable depth (default: 1000), then drops oldest notifications,
     increments a "notifications_dropped" counter (exposed as a tool on
     the aggregator), and emits a synthetic "notification_overflow"
     notification upstream.  This directly addresses the SNMP trap storm
     problem [RFC3413].

     Notifications MAY include "x-mcpax-event-id" (UUID) and "x-mcpax-
     causal-parent" (UUID or null) fields.  These do not impose cross-
     subserver ordering but enable downstream consumers to reconstruct
     causal chains when notifications from multiple subservers relate to



  Abbott                   Expires 5 November 2026               [Page 16]


  Internet-Draft                   MCP-AX                         May 2026


     the same triggering event.  Aggregators MUST forward these fields
     without modification if present.  Aggregators MUST NOT hold causal
     parent notifications in state or attempt to correlate them; they are
     opaque pass-through values.  Causal reconstruction is a consumer
     concern, not an aggregator concern.

  13.  Failure Modes and Recovery

  13.1.  Subserver Failure

     On heartbeat timeout or connection loss, the aggregator emits
     "subserver_lost" upstream.  On reconnection, tools are re-added.  The
     aggregator MUST NOT cache tool definitions across sessions.

  13.2.  Degraded Mode

     Rather than immediately removing all tools from a failed subserver's
     namespace, an aggregator MAY transition those tools to
     "availability": "degraded".  In degraded mode, tools remain listed in
     tools/list responses but tools/call requests return a structured
     error:

     {
       "code": -32002,
       "message": "tool_degraded",
       "data": {
         "reason": "subserver_unreachable",
         "since": "2026-05-01T12:05:00Z",
         "retry_after_ms": 5000
       }
     }

     The aggregator MUST remove degraded tools entirely after a
     configurable grace period (RECOMMENDED: 5 minutes) if the subserver
     does not recover.  Degraded-mode semantics are essential for
     industrial control and observability pipelines where abrupt namespace
     changes can trigger cascading failures in upstream consumers.

  13.3.  Aggregator Failure

     The parent detects heartbeat loss and removes the entire subtree.
     Subservers MAY reconnect to a configured backup aggregator.
     Convergence time after failure MUST be less than three heartbeat
     intervals across the affected subtree.







  Abbott                   Expires 5 November 2026               [Page 17]


  Internet-Draft                   MCP-AX                         May 2026


  13.4.  Split-Brain Prevention

     Each subserver carries a stable "subserver_id" (UUID) in its
     registration request.  Each aggregator maintains its own
     "aggregator_id" (UUID).  An aggregator MUST reject a registration
     from a subserver_id that is already registered with a different
     aggregator_id in the same tree.

     For cloud deployments, detection SHOULD use a shared registration
     store (e.g., DynamoDB, etcd) keyed by subserver_id.  For edge
     deployments where shared state is unavailable, the aggregator SHOULD
     query the subserver for its current parent_id and reject if it
     differs.  This provides deterministic behavior without mandating a
     specific distributed consensus system.

  14.  IANA Considerations

     This document requests the following registrations:

     (a)  MCP-AX method namespace "mcpax/*" in the MCP method registry (to
          be established by the Agentic AI Foundation or a future IETF
          working group).

     (b)  MCP-AX capability annotation keys "x-mcpax-*" in the MCP
          metadata registry (to be established).

     (c)  MCP-AX transport class identifiers in a new "MCP-AX Transport
          Classes" registry.

  15.  References

  15.1.  Normative References

     [MCP]      Agentic AI Foundation / Linux Foundation, "Model Context
                Protocol Specification", Originally authored by D. Soria
                Parra and J. Spahr-Summers, Anthropic.  Governance
                transferred to the Agentic AI Foundation, a Linux
                Foundation project, December 2025., November 2025,
                <https://modelcontextprotocol.io/specification/>.

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







  Abbott                   Expires 5 November 2026               [Page 18]


  Internet-Draft                   MCP-AX                         May 2026


     [RFC2741]  Daniele, M., Wijnen, B., Ellison, M., and D. Francisco,
                "Agent Extensibility (AgentX) Protocol Version 1",
                RFC 2741, DOI 10.17487/RFC2741, January 2000,
                <https://www.rfc-editor.org/rfc/rfc2741>.

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

     [RFC8707]  Campbell, B. and J. Bradley, "Resource Indicators for
                OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, February 2020,
                <https://www.rfc-editor.org/rfc/rfc8707>.

  15.2.  Informative References

     [I-D.zeng-mcp-network-measurement]
                Zeng, X., "MCP-based Network Measurement Framework", Work
                in Progress, Internet-Draft, draft-zeng-mcp-network-
                measurement-00, October 2025,
                <https://datatracker.ietf.org/doc/html/draft-zeng-mcp-
                network-measurement-00>.

     [I-D.zeng-mcp-network-mgmt]
                Zeng, X., "Model Context Protocol (MCP) Extensions for
                Network Equipment Management", Work in Progress, Internet-
                Draft, draft-zeng-mcp-network-mgmt-01, October 2025,
                <https://www.ietf.org/archive/id/draft-zeng-mcp-network-
                mgmt-01.html>.

     [I-D.zeng-mcp-troubleshooting]
                Zeng, X., "Using MCP for Intent-Based Network
                Troubleshooting Automation", Work in Progress, Internet-
                Draft, draft-zeng-mcp-troubleshooting-00, October 2025,
                <https://www.ietf.org/archive/id/draft-zeng-mcp-
                troubleshooting-00.html>.

     [RFC3413]  Levi, D., Meyer, P., and B. Stewart, "Simple Network
                Management Protocol (SNMP) Applications", STD 62,
                RFC 3413, DOI 10.17487/RFC3413, December 2002,
                <https://www.rfc-editor.org/rfc/rfc3413>.

     [RFC3414]  Blumenthal, U. and B. Wijnen, "User-based Security Model
                (USM) for version 3 of the Simple Network Management
                Protocol (SNMPv3)", STD 62, RFC 3414,
                DOI 10.17487/RFC3414, December 2002,
                <https://www.rfc-editor.org/rfc/rfc3414>.





  Abbott                   Expires 5 November 2026               [Page 19]


  Internet-Draft                   MCP-AX                         May 2026


     [RFC7049]  Bormann, C. and P. Hoffman, "Concise Binary Object
                Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
                October 2013, <https://www.rfc-editor.org/rfc/rfc7049>.

  Appendix A: AgentX Full Correspondence Table

          +==========================+=============================+
          | AgentX Concept           | MCP-AX Concept              |
          +==========================+=============================+
          | Master Agent             | Root Aggregator             |
          +--------------------------+-----------------------------+
          | Subagent                 | Subserver                   |
          +--------------------------+-----------------------------+
          | OID Subtree              | Namespace Prefix            |
          +--------------------------+-----------------------------+
          | MIB Registration         | Tool Registration           |
          +--------------------------+-----------------------------+
          | ax.Register PDU          | mcpax/register              |
          +--------------------------+-----------------------------+
          | ax.Unregister PDU        | mcpax/deregister            |
          +--------------------------+-----------------------------+
          | ax.Get/GetNext/GetBulk   | tools/call (routed)         |
          +--------------------------+-----------------------------+
          | ax.Notify PDU            | MCP notification (prefixed) |
          +--------------------------+-----------------------------+
          | ax.Ping PDU              | mcpax/heartbeat             |
          +--------------------------+-----------------------------+
          | ax.Response PDU          | JSON-RPC response           |
          +--------------------------+-----------------------------+
          | Session ID               | session_id                  |
          +--------------------------+-----------------------------+
          | Context                  | Namespace segment           |
          +--------------------------+-----------------------------+
          | sysUpTime                | registered_at timestamp     |
          +--------------------------+-----------------------------+
          | AgentX socket (unix/tcp) | HTTP+SSE / stdio / bridged  |
          +--------------------------+-----------------------------+

                                   Table 3

     Key divergences from AgentX:

     (a)  Wire format is JSON-RPC (or CBOR for bridged transports), not
          binary PDUs.

     (b)  Namespaces are locally unique by first-registration, not
          globally by IANA OID assignment.




  Abbott                   Expires 5 November 2026               [Page 20]


  Internet-Draft                   MCP-AX                         May 2026


     (c)  Capability annotations (latency, mutability, reversibility) have
          no AgentX equivalent.

     (d)  Irreversibility gates and agent budget enforcement are MCP-AX
          additions with no SNMP analog.

  Appendix B: Embedded Stub Reference Profiles

  B.1 Profile A -- Table Stub

     Profile A targets devices with no self-description capability,
     including legacy 8-bit microcontrollers (8051-class, 6800-class).
     The gateway owns all tool schemas and name mappings.  The device
     exposes only numeric command IDs over a minimal frame protocol.

     Resource budget: effectively zero dynamic RAM for protocol state.
     The command dispatch table is ROM-resident.  The gateway
     configuration file defines the mapping from command IDs to MCP-AX
     tool names, argument schemas, and capability annotations.

     Reference wire frame (gateway-to-stub and stub-to-gateway):

             +-----+-----+------+---------+-----+---------+-----+
             | SOF | LEN | TYPE | TOOL_ID | SEQ | PAYLOAD | CRC |
             |  1B | 1-2B|  1B  |   1B    | 1B  |   NB    | 1-2B|
             +-----+-----+------+---------+-----+---------+-----+

             TYPE:  0x01 = call request
                    0x02 = call response
                    0x03 = registration (Profile B only)
                    0x04 = heartbeat

             PAYLOAD: fixed structs, TLV, or raw bytes.
                      Interpretation is defined in gateway config.

     Profile A devices need not use CBOR.  The gateway translates between
     the device's native byte layout and MCP-AX JSON-RPC.  The stub's only
     contract is: receive (TOOL_ID, PAYLOAD), execute, return (SEQ,
     PAYLOAD, status byte).












  Abbott                   Expires 5 November 2026               [Page 21]


  Internet-Draft                   MCP-AX                         May 2026


     <CODE BEGINS>
     /* Profile A: ROM command table -- no CBOR, no schemas on device */
     typedef struct {
         uint8_t   cmd_id;
         uint8_t   req_len;       /* fixed request payload length  */
         uint8_t   resp_len;      /* fixed response payload length */
         int (*handler)(const uint8_t *req, uint8_t *resp);
     } mcpax_cmd_t;

     static const mcpax_cmd_t commands[] = {
         { 0x01, 0,  4, read_sensor_handler  },
         { 0x02, 1,  0, set_led_handler      },
     };
     <CODE ENDS>

  B.2 Profile B -- Self-Describing Stub

     Profile B targets 16/32-bit microcontrollers (Cortex-M0+, AVR,
     MSP430) that can announce tool IDs and compact argument schemas at
     boot via CBOR registration frames.

     Resource budget: fewer than 2 KB flash code, fewer than 512 bytes ROM
     for schema tables, fewer than 256 bytes RAM for request/response
     buffers.  Transport: UART at 9600 baud or higher, COBS framing.
     Encoding: CBOR [RFC7049], map-only payloads.

     <CODE BEGINS>
     /* Profile B: self-describing tool table with CBOR type hints */
     typedef struct {
         uint8_t   tool_id;
         uint8_t   arg_count;
         uint8_t   arg_types[4];   /* CBOR major types */
         uint8_t   ret_type;
         int (*handler)(const uint8_t *args, uint8_t *resp,
                        uint16_t *resp_len);
     } mcpax_tool_t;

     static const mcpax_tool_t tools[] = {
         { 0x01, 0, {}, CBOR_MAP, dma2d_status_handler },
         { 0x02, 1, {CBOR_UINT}, CBOR_MAP, set_led_handler },
     };
     <CODE ENDS>

  B.3 Boot Sequence

     Profile A:





  Abbott                   Expires 5 November 2026               [Page 22]


  Internet-Draft                   MCP-AX                         May 2026


     1.  Stub powers on; gateway detects presence (UART RTS/CTS, GPIO, or
         poll).

     2.  Gateway loads tool mappings and schemas from its own
         configuration.

     3.  Gateway sends mcpax/register upstream on behalf of stub.

     4.  Gateway begins heartbeat on behalf of stub.

     5.  Stub enters idle state, awaiting framed command bytes.

     Profile B:

     1.  Stub powers on; sends CBOR registration frame listing tool_ids
         and schemas.

     2.  Gateway maps tool_ids to fully qualified names from its
         configuration.

     3.  Gateway sends mcpax/register upstream.

     4.  Gateway begins heartbeat on behalf of stub.

     5.  Stub enters idle state, awaiting CBOR tool call frames.

  B.4 Gateway Responsibilities

     For both profiles, the gateway handles all protocol complexity:

     *  CBOR/byte-frame to JSON-RPC bidirectional translation

     *  Tool ID to fully qualified name mapping

     *  Schema validation of arguments before forwarding to stub

     *  Stripping of all x-mcpax-* routing metadata at the stub boundary

     *  Authentication context for upstream aggregator

     *  Heartbeat generation on behalf of stub

     *  Buffering and retry for unreliable transports (BLE, CAN)

  Appendix C: Example Topologies

  C.1 Enterprise SaaS Aggregation




  Abbott                   Expires 5 November 2026               [Page 23]


  Internet-Draft                   MCP-AX                         May 2026


                Model Client
                     |
                Root Aggregator
                 /       |        \
                Google  Jira    Salesforce
                Drive  Server    Server

                Namespace: google_drive.*, jira.*, salesforce.*

  C.2 Industrial IoT with Edge Gateway

                    Model Client
                         |
                    Cloud Aggregator (AWS)
                         |
                    Edge Aggregator (Jetson)
                     /        |         \
                    PLC     Sensor    Actuator
                    (Modbus  Array    Controller
                    gateway) (BLE)    (UART/CBOR)

                    Irreversible-mutable actuator tools:
                    confirmation gate at cloud aggregator.

  C.3 Recursive Regional Hierarchy

               Model Client
                    |
               Global Aggregator
                /              \
               US Regional    EU Regional
                /      \        /      \
               US-E   US-W   EU-W    EU-E

               Namespace: global.us.east.*, global.us.west.*,
                          global.eu.west.*, global.eu.east.*

               Model infers geographic locality from namespace.

  Acknowledgments

     The authors gratefully acknowledge the designers of AgentX [RFC2741],
     whose architectural insights proved remarkably durable across a
     quarter-century gap and an entirely different application domain.
     The term "agent" has, it turns out, aged exceptionally well.






  Abbott                   Expires 5 November 2026               [Page 24]


  Internet-Draft                   MCP-AX                         May 2026


     The irreversibility gate mechanism draws on safety-critical HMI
     design principles and the concept of useful friction at
     irreversibility boundaries in autonomous agent planning systems.

  Author's Address

     Ira Abbott
     SoftOboros
     Ottawa Ontario
     Canada
     Email: ira@softoboros.com








































  Abbott                   Expires 5 November 2026               [Page 25]


name: draft-hood-agtp-api
rev: 00
title: AGTP-API: Verbs, Paths, Endpoints, and Synthesis
time: 2026-05-12T05:08:01Z
group_uri: /api/v1/group/group/1027/
expires: 2026-11-13T05:08:01Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["A2A protocols", "Data formats/interop", "Policy/governance"]
tags: []
fetched_at: 2026-05-22T09:24:50.092729+00:00
source: ietf
abstract:
  This document specifies AGTP-API: the contract layer that the Agent
     Transfer Protocol (AGTP) [AGTP] relies on to govern interactions
     between autonomous agents and AGTP servers.  AGTP-API defines a
     curated approved method catalog (with versioned evolution and
     graceful deprecation), path grammar rules that prevent method-name
     leakage into paths, the endpoint primitive (the structural unit a
     server exposes to agents), the semantic block carried by every
     endpoint, schema validation requirements, the server manifest format
     that exposes a server's endpoint catalog, the per-server method
     policy carried as a sub-block of the manifest, the PROPOSE-and-
     synthesis runtime contract negotiation mechanism, the three handler
     binding kinds (composition, registered_function, external_service),
     and the structural rejection status codes (404, 405, 459, 460) that
     together cover the contract-level failure surface.  This document
     supersedes the AGIS Internet-Draft (draft-hood-independent-agis-01)
     and the previously-proposed AGTP-Methods Internet-Draft, both of
     which are deprecated.  AGTP-API is the unified companion
     specification they were splitting concerns across.

full_text:
  Independent Submission                                           C. Hood
  Internet-Draft                                             Nomotic, Inc.
  Intended status: Informational                               12 May 2026
  Expires: 13 November 2026


              AGTP-API: Verbs, Paths, Endpoints, and Synthesis
                           draft-hood-agtp-api-00

  Abstract

     This document specifies AGTP-API: the contract layer that the Agent
     Transfer Protocol (AGTP) [AGTP] relies on to govern interactions
     between autonomous agents and AGTP servers.  AGTP-API defines a
     curated approved method catalog (with versioned evolution and
     graceful deprecation), path grammar rules that prevent method-name
     leakage into paths, the endpoint primitive (the structural unit a
     server exposes to agents), the semantic block carried by every
     endpoint, schema validation requirements, the server manifest format
     that exposes a server's endpoint catalog, the per-server method
     policy carried as a sub-block of the manifest, the PROPOSE-and-
     synthesis runtime contract negotiation mechanism, the three handler
     binding kinds (composition, registered_function, external_service),
     and the structural rejection status codes (404, 405, 459, 460) that
     together cover the contract-level failure surface.  This document
     supersedes the AGIS Internet-Draft (draft-hood-independent-agis-01)
     and the previously-proposed AGTP-Methods Internet-Draft, both of
     which are deprecated.  AGTP-API is the unified companion
     specification they were splitting concerns across.

  Status of This Memo

     This Internet-Draft is submitted in full conformance with the
     provisions of BCP 78 and BCP 79.

     Internet-Drafts are working documents of the Internet Engineering
     Task Force (IETF).  Note that other groups may also distribute
     working documents as Internet-Drafts.  The list of current Internet-
     Drafts is at https://datatracker.ietf.org/drafts/current/.

     Internet-Drafts are draft documents valid for a maximum of six months
     and may be updated, replaced, or obsoleted by other documents at any
     time.  It is inappropriate to use Internet-Drafts as reference
     material or to cite them other than as "work in progress."

     This Internet-Draft will expire on 13 November 2026.





  Hood                    Expires 13 November 2026                [Page 1]


  Internet-Draft                  AGTP-API                        May 2026


  Copyright Notice

     Copyright (c) 2026 IETF Trust and the persons identified as the
     document authors.  All rights reserved.

     This document is subject to BCP 78 and the IETF Trust's Legal
     Provisions Relating to IETF Documents (https://trustee.ietf.org/
     license-info) in effect on the date of publication of this document.
     Please review these documents carefully, as they describe your rights
     and restrictions with respect to this document.

  Table of Contents

     1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
       1.1.  Why the Contract Belongs in the Protocol  . . . . . . . .   4
       1.2.  Document Lineage  . . . . . . . . . . . . . . . . . . . .   5
       1.3.  Requirements Language . . . . . . . . . . . . . . . . . .   6
     2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   6
     3.  Method Catalog  . . . . . . . . . . . . . . . . . . . . . . .   7
       3.1.  Catalog Structure . . . . . . . . . . . . . . . . . . . .   7
       3.2.  Method Rules  . . . . . . . . . . . . . . . . . . . . . .   8
       3.3.  Custom Methods  . . . . . . . . . . . . . . . . . . . . .   8
       3.4.  Catalog Evolution Overview  . . . . . . . . . . . . . . .   9
       3.5.  Catalog Version Exposure  . . . . . . . . . . . . . . . .   9
       3.6.  Legacy Verb Support . . . . . . . . . . . . . . . . . . .   9
     4.  Catalog Evolution . . . . . . . . . . . . . . . . . . . . . .  10
       4.1.  Versioning Scheme . . . . . . . . . . . . . . . . . . . .  10
       4.2.  Deprecation Metadata  . . . . . . . . . . . . . . . . . .  10
       4.3.  Manifest Catalog Declaration  . . . . . . . . . . . . . .  11
       4.4.  Runtime Deprecation Signaling . . . . . . . . . . . . . .  11
       4.5.  Removal Behavior  . . . . . . . . . . . . . . . . . . . .  12
       4.6.  Cross-Server Version Negotiation  . . . . . . . . . . . .  12
       4.7.  Tooling . . . . . . . . . . . . . . . . . . . . . . . . .  13
       4.8.  Multi-Version Catalog Support . . . . . . . . . . . . . .  13
       4.9.  Catalog Publishing  . . . . . . . . . . . . . . . . . . .  14
     5.  Path Grammar  . . . . . . . . . . . . . . . . . . . . . . . .  14
       5.1.  Path Rules  . . . . . . . . . . . . . . . . . . . . . . .  14
       5.2.  Path Grammar ABNF . . . . . . . . . . . . . . . . . . . .  14
       5.3.  Permissiveness  . . . . . . . . . . . . . . . . . . . . .  15
       5.4.  Path Pattern Matching . . . . . . . . . . . . . . . . . .  16
       5.5.  Query Strings . . . . . . . . . . . . . . . . . . . . . .  16
       5.6.  Fragments . . . . . . . . . . . . . . . . . . . . . . . .  17
       5.7.  No Reserved Path Prefixes . . . . . . . . . . . . . . . .  17
       5.8.  Server Metadata via AGTP Methods  . . . . . . . . . . . .  17
     6.  The Endpoint Primitive  . . . . . . . . . . . . . . . . . . .  18
       6.1.  Endpoint Definition . . . . . . . . . . . . . . . . . . .  18
       6.2.  Required Fields . . . . . . . . . . . . . . . . . . . . .  19
       6.3.  Field Semantics . . . . . . . . . . . . . . . . . . . . .  19



  Hood                    Expires 13 November 2026                [Page 2]


  Internet-Draft                  AGTP-API                        May 2026


       6.4.  Endpoint Deprecation  . . . . . . . . . . . . . . . . . .  21
     7.  The Semantic Block  . . . . . . . . . . . . . . . . . . . . .  22
       7.1.  Required Semantic Block Fields  . . . . . . . . . . . . .  22
     8.  Server Manifest . . . . . . . . . . . . . . . . . . . . . . .  23
       8.1.  Purpose . . . . . . . . . . . . . . . . . . . . . . . . .  23
       8.2.  Manifest Structure  . . . . . . . . . . . . . . . . . . .  23
       8.3.  Server Block  . . . . . . . . . . . . . . . . . . . . . .  25
       8.4.  Methods Inventory . . . . . . . . . . . . . . . . . . . .  26
       8.5.  Agents Disclosure . . . . . . . . . . . . . . . . . . . .  26
       8.6.  Protocol and API Surface  . . . . . . . . . . . . . . . .  26
       8.7.  Policies Block  . . . . . . . . . . . . . . . . . . . . .  27
       8.8.  Manifest Signature  . . . . . . . . . . . . . . . . . . .  27
       8.9.  Endpoint Projection . . . . . . . . . . . . . . . . . . .  28
       8.10. Manifest Retrieval  . . . . . . . . . . . . . . . . . . .  29
       8.11. Manifest Caching  . . . . . . . . . . . . . . . . . . . .  29
     9.  Method Policy . . . . . . . . . . . . . . . . . . . . . . . .  29
       9.1.  Purpose . . . . . . . . . . . . . . . . . . . . . . . . .  29
       9.2.  Policy Shape  . . . . . . . . . . . . . . . . . . . . . .  29
       9.3.  Example . . . . . . . . . . . . . . . . . . . . . . . . .  30
       9.4.  Catalog-Graceful Skip Semantics . . . . . . . . . . . . .  31
       9.5.  Discovery . . . . . . . . . . . . . . . . . . . . . . . .  31
     10. PROPOSE and Synthesis . . . . . . . . . . . . . . . . . . . .  31
       10.1.  Purpose  . . . . . . . . . . . . . . . . . . . . . . . .  32
       10.2.  Negotiation Flow . . . . . . . . . . . . . . . . . . . .  32
       10.3.  Server-Side Synthesis Evaluation . . . . . . . . . . . .  32
       10.4.  Synthesis-Composed Endpoints . . . . . . . . . . . . . .  33
       10.5.  Session-Scoped vs Persistent Synthesis . . . . . . . . .  33
     11. Status Codes  . . . . . . . . . . . . . . . . . . . . . . . .  34
     12. Handler Binding . . . . . . . . . . . . . . . . . . . . . . .  35
       12.1.  Composition  . . . . . . . . . . . . . . . . . . . . . .  35
       12.2.  Registered Function  . . . . . . . . . . . . . . . . . .  36
       12.3.  External Service . . . . . . . . . . . . . . . . . . . .  37
     13. Conformance . . . . . . . . . . . . . . . . . . . . . . . . .  39
       13.1.  Single Tier  . . . . . . . . . . . . . . . . . . . . . .  39
       13.2.  Validation Timing  . . . . . . . . . . . . . . . . . . .  40
       13.3.  Schema Strictness  . . . . . . . . . . . . . . . . . . .  42
       13.4.  Conformance Test Suite . . . . . . . . . . . . . . . . .  42
     14. Relationship to OpenAPI . . . . . . . . . . . . . . . . . . .  43
       14.1.  OpenAPI as an Authoring Source . . . . . . . . . . . . .  43
       14.2.  OpenAPI as an Export Target  . . . . . . . . . . . . . .  43
       14.3.  OpenAPI as a Coexistence Layer . . . . . . . . . . . . .  44
     15. What AGTP-API Does Not Specify  . . . . . . . . . . . . . . .  44
     16. Security Considerations . . . . . . . . . . . . . . . . . . .  44
       16.1.  Verb-Path Tampering  . . . . . . . . . . . . . . . . . .  45
       16.2.  Synthesis Authority Preservation . . . . . . . . . . . .  45
       16.3.  Method Policy Tampering  . . . . . . . . . . . . . . . .  45
       16.4.  Wildcard Abuse . . . . . . . . . . . . . . . . . . . . .  45
       16.5.  Verb List Trust  . . . . . . . . . . . . . . . . . . . .  45



  Hood                    Expires 13 November 2026                [Page 3]


  Internet-Draft                  AGTP-API                        May 2026


     17. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  46
       17.1.  AGTP-API Status Code Assignments . . . . . . . . . . . .  46
       17.2.  Media Type Registrations . . . . . . . . . . . . . . . .  46
       17.3.  AGTP-API Method Catalog Reference  . . . . . . . . . . .  47
       17.4.  AGTP-API Response Headers  . . . . . . . . . . . . . . .  47
     18. Open Items  . . . . . . . . . . . . . . . . . . . . . . . . .  47
     19. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .  49
     20. References  . . . . . . . . . . . . . . . . . . . . . . . . .  49
       20.1.  Normative References . . . . . . . . . . . . . . . . . .  49
       20.2.  Informative References . . . . . . . . . . . . . . . . .  50
     Appendix A.  Implementation Guidance (Informative)  . . . . . . .  50
       A.1.  Endpoint Authoring  . . . . . . . . . . . . . . . . . . .  50
       A.2.  Runtime Dispatch Pattern  . . . . . . . . . . . . . . . .  51
       A.3.  Tooling . . . . . . . . . . . . . . . . . . . . . . . . .  52
       A.4.  Operator Notes on Catalog Versioning  . . . . . . . . . .  52
     Appendix B.  Migration Paths (Informative)  . . . . . . . . . . .  53
       B.1.  Wrap-and-Expose . . . . . . . . . . . . . . . . . . . . .  53
       B.2.  Translate-and-Rehost  . . . . . . . . . . . . . . . . . .  53
       B.3.  Coexist-Permanently . . . . . . . . . . . . . . . . . . .  54
       B.4.  Path Selection  . . . . . . . . . . . . . . . . . . . . .  54
     Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  54

  1.  Introduction

     AGTP [AGTP] is a transport protocol designed for AI agent traffic.
     It establishes identity, authority, attribution, and a twelve-method
     protocol-level floor.  Beyond that floor, the question of what an
     AGTP server actually exposes -- what endpoints it presents, what
     verbs are valid, what paths are permitted, what schemas govern input
     and output, what authority is required for invocation -- is the
     contract layer.  This document specifies the contract layer.

  1.1.  Why the Contract Belongs in the Protocol

     The architectural goal AGTP is designed around is runtime contract
     negotiation between autonomous agents (RCNS).  An agent encountering
     an AGTP server must be able to:

     *  Discover what endpoints the server exposes, with full structural
        detail, in a single call.

     *  Reason about whether an endpoint matches its intent based on the
        endpoint's declared semantic block.

     *  Verify that its identity carries the authority required to invoke
        the endpoint.

     *  Propose new endpoints when its needs are not met by existing ones.



  Hood                    Expires 13 November 2026                [Page 4]


  Internet-Draft                  AGTP-API                        May 2026


     *  Compose endpoints across servers while preserving authority
        through the composition.

     None of this works if the contract lives in middleware.  A protocol
     that does not know what an interaction means cannot govern it.  When
     an agent invokes a method on a path, the protocol must verify
     identity, confirm permissions cover the method-on-path combination,
     confirm server policy allows the combination, validate the request
     body against the endpoint's input schema, apply scope checks, log the
     invocation, and -- if the request triggers synthesis -- ensure each
     composed step preserves authority.  Each of these checks requires the
     protocol to know what the method-on-path combination means.

     This is the load-bearing claim of AGTP-API.  The contract is a first-
     class protocol concept rather than something inferred from
     documentation, OpenAPI specs, or framework conventions.  Operational
     concerns -- rate limiting, observability, caching, custom
     authentication strategies, request transformation, deployment
     topology -- remain middleware territory because they are operational
     decisions specific to a deployment.  The protocol governs contracts;
     middleware governs operations.  Neither layer pretends to be the
     other.

  1.2.  Document Lineage

     AGTP-API supersedes two previously-separate drafts:

     *  AGIS (the Agentive Grammar and Interface Specification, draft-
        hood-independent-agis-01) -- deprecated.  Retained as a historical
        citation source for the empirical research informing the verb-
        class semantics.  ("Verb" here is the linguistic category — the
        catalog is a vocabulary of action-intent verbs.  See Section 2.)

     *  AGTP-Methods (the proposed Standard Extended Method Vocabulary,
        draft-hood-agtp-standard-methods-01) -- folded into this document.
        There is no separate method-catalog specification.

     The previously-proposed AMG (Agent Method Grammar) draft is also
     deprecated; it never reached publication.  The grammar framing is
     replaced by the contract framing throughout.  This document assumes
     the reader understands AGTP [AGTP] v07 or later.










  Hood                    Expires 13 November 2026                [Page 5]


  Internet-Draft                  AGTP-API                        May 2026


  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.

  2.  Terminology

     Method:  The action component of an AGTP request: an uppercase ASCII
        token appearing in the AGTP-API approved catalog or in a server's
        the server's policies.methods as a custom method.  The method
        field on every endpoint declaration carries this token.  The
        protocol-level term used throughout the wire format, manifest, and
        conformance language.

     Verb:  A descriptive synonym for "method" used when discussing the
        catalog as a vocabulary of action-intent verbs.  The catalog at
        agtp.io/api/methods.json is a glossary of verbs; an operator picks
        a verb from the catalog and declares it as the method on an
        endpoint.  Method is the field name; verb is the linguistic
        category that explains why the field carries imperative-form
        action-intent words.

     Path:  The resource portion of an AGTP request, beginning with a
        forward slash.  Subject to the path grammar rules in Section 5.

     Endpoint:  A method-and-path pair exposed by an AGTP server, together
        with its semantic block, input schema, output schema, error
        declarations, and handler binding.  The deployable unit of an AGTP
        service.  Endpoints are first-class protocol concepts.

     Semantic Block:  Required structural metadata for every endpoint:
        intent, actor, outcome, capability classification, confidence
        guidance, impact tier, and idempotency.  Encodes machine-readable
        intent so that agents can reason about endpoint applicability
        before invoking.  Carried on the endpoint as the semantic field.

     Server Manifest:  The machine-readable document an AGTP server
        publishes to declare its endpoint catalog, hosted agents, hosted
        protocols, and policies.  The authoritative source for what a
        server offers.

     Method Policy:  A per-server policy block declaring allowed methods,
        disallowed methods, legacy verb opt-in, and server-local method-
        to-method redirects.  Carried as the policies.methods sub-block of
        the server manifest.  See Section 9.



  Hood                    Expires 13 November 2026                [Page 6]


  Internet-Draft                  AGTP-API                        May 2026


     Synthesis:  The runtime instantiation of an endpoint in response to a
        PROPOSE request, composing the requested behavior from existing
        endpoints while preserving authority through the composition.

     Wildcards:  An ad-hoc method invocation mode in which an agent
        invokes a method outside the server's declared endpoint catalog.
        Subject to mutual consent: requires wildcards: true in the agent
        identity document and wildcards_accepted: true in server policy.

  3.  Method Catalog

     AGTP-API defines a curated catalog of approved methods maintained at
     https://agtp.io/api/methods.json.  The catalog is the canonical
     source for what method names are recognized.  Method names not
     appearing in the catalog are rejected with status 459 Method
     Violation.

     The catalog is a vocabulary of action-intent verbs: imperative-form
     words that describe what an operation does (BOOK, RESERVE, AUDIT,
     QUERY).  A verb in the catalog becomes a _method_ when an operator
     picks it from the catalog and declares it as the method field on an
     endpoint.  The two terms are related: verbs are the linguistic
     content of the catalog; methods are the protocol-level identifier on
     each endpoint and request.

  3.1.  Catalog Structure

     The catalog is a versioned JSON document with five top-level keys:

     version  Semantic version of the catalog as a whole.  See Section 4.

     embedded  The 12 protocol-floor verbs every AGTP server *MUST*
        support: six cognitive (QUERY, DISCOVER, DESCRIBE, SUMMARIZE,
        PLAN, PROPOSE) and six mechanics (EXECUTE, DELEGATE, ESCALATE,
        CONFIRM, SUSPEND, NOTIFY).

     legacy  The five HTTP-style verbs (GET, POST, PUT, DELETE, PATCH),
        each carrying a preferred mapping to its canonical AGTP
        replacement (FETCH, CREATE, REPLACE, REMOVE, MODIFY).  Legacy
        verbs are opt-in per server through the manifest's
        policies.methods block.  See Section 3.6.

     categories  The taxonomy used to classify verbs: discovery,
        retrieval, analysis, transaction, modification, creation,
        notification, mechanics, domain_spanning.

     verbs  The catalog of approved verbs, each with categories,




  Hood                    Expires 13 November 2026                [Page 7]


  Internet-Draft                  AGTP-API                        May 2026


        description, and optional deprecation metadata (deprecated_in,
        removed_in, successor).

     The catalog is published in machine-readable form at the URL above
     and is intentionally maintained as an open living artifact rather
     than a closed IANA registry.  Curation is performed by the AGTP-API
     maintainers in public; the version of the catalog in effect at any
     given moment is declared in the catalog_version field of every server
     manifest.  A closed IANA registry would freeze the verb vocabulary at
     the cadence of IETF process; AGTP-API verbs need to evolve at the
     cadence of agent deployments.  The IANA registries that AGTP-API does
     request (Section 17) cover the structural status codes, the media
     types, and the response headers — all of which benefit from IANA's
     conservative cadence.  The catalog itself does not.

  3.2.  Method Rules

     Method names *MUST* be uppercase ASCII single tokens matching the
     regex ^[A-Z]+$, length 3 to 32 characters inclusive.  Method names
     *MUST* appear in the catalog, or in the legacy set when the server's
     policies.methods.legacy opts into legacy verbs.

     The catalog is curated to contain only imperative-form action-intent
     verbs that:

     *  Express a command or action, not a state, an attribute, or a noun
        (RESERVE is valid; RESERVATION is not).

     *  Carry a single intent (verbs with compound intent are decomposed
        into separate verbs).

     *  Are not HTTP method names.

     These are curatorial principles applied during verb addition, not
     runtime checks performed by AGTP servers.  Servers validate verbs
     against the catalog membership and the lexical regex; semantic class
     adherence is the responsibility of the catalog maintainers.

  3.3.  Custom Methods

     Servers *MAY* accept additional methods beyond the catalog by listing
     them in the manifest's policies.methods block.  Custom methods follow
     the same lexical rules in Section 3.2 but are server-specific and are
     not interoperable across organizations without explicit acceptance.
     Custom methods are not added to the catalog; they exist only within
     the publishing server's surface.





  Hood                    Expires 13 November 2026                [Page 8]


  Internet-Draft                  AGTP-API                        May 2026


  3.4.  Catalog Evolution Overview

     The catalog evolves under semver discipline:

     *  *Patch* (1.0.0 → 1.0.1) — description or category metadata changes
        only.

     *  *Minor* (1.0.0 → 1.1.0) — verbs added; existing verbs unchanged.
        Minor revisions *MAY* introduce new deprecation flags on existing
        verbs.

     *  *Major* (1.0.0 → 2.0.0) — verbs removed or renamed.

     Per-verb deprecation uses three optional fields: deprecated_in
     (catalog version that flagged the verb), removed_in (version
     scheduled for removal), and successor (recommended replacement).  A
     deprecated verb remains admitted by the dispatcher; the response
     carries an AGTP-Catalog-Warning advisory header.  See Section 4 for
     the full lifecycle, runtime semantics, removal behavior, cross-server
     version negotiation, and the agtp-catalog-diff tooling.

  3.5.  Catalog Version Exposure

     The catalog version is exposed on the server manifest under
     catalog_version and catalog_versions_supported so clients can detect
     mismatches between their local catalog and the server's.  See
     Section 8.

  3.6.  Legacy Verb Support

     AGTP-API recognizes GET, POST, PUT, DELETE, and PATCH as legacy verbs
     with reframed semantics for transitional deployments.  Legacy verb
     support is opt-in per server through the manifest's policies.methods
     block:

     legacy_verbs: enabled

     When legacy verbs are enabled, the server *MUST* treat them as
     follows:

     *  GET maps to QUERY for read operations against a known path.

     *  POST maps to EXECUTE for state-changing operations.

     *  PUT maps to EXECUTE with idempotency_key.

     *  DELETE maps to EXECUTE with action: "delete".




  Hood                    Expires 13 November 2026                [Page 9]


  Internet-Draft                  AGTP-API                        May 2026


     *  PATCH maps to EXECUTE with action: "modify".

     These mappings are conveniences for migration.  Legacy verbs *MUST
     NOT* be used in new endpoint definitions; servers *SHOULD* deprecate
     legacy support over time.

  4.  Catalog Evolution

     The AGTP-API approved method catalog is versioned.  This section
     specifies how catalog versioning works, how deprecation is signaled,
     and how servers and agents negotiate over catalog versions.

  4.1.  Versioning Scheme

     The method catalog is versioned as semver MAJOR.MINOR.PATCH:

     *  *PATCH* — editorial changes (clarifications, typo fixes,
        description rewordings).  No verb additions, removals, or
        deprecations.

     *  *MINOR* — additions and deprecations.  Verbs may be added; verbs
        may be marked deprecated.  No verbs are removed in a minor
        revision.

     *  *MAJOR* — removals.  Verbs marked deprecated in earlier minor
        revisions may be removed.

     Servers and agents using a given catalog MAJOR version are guaranteed
     that no verb available in that MAJOR will disappear without warning;
     removal requires a MAJOR bump.

  4.2.  Deprecation Metadata

     Each verb in the catalog *MAY* carry deprecation metadata:

     {
       "name": "AUDIT_LEGACY",
       "category": "compute",
       "deprecated_in": "1.2.0",
       "removed_in": "2.0.0",
       "successor": "AUDIT"
     }

     deprecated_in:  The catalog version at which the verb became
        deprecated.

     removed_in:  The anticipated catalog version at which the verb will




  Hood                    Expires 13 November 2026               [Page 10]


  Internet-Draft                  AGTP-API                        May 2026


        be removed. *MAY* be absent if removal is anticipated but the
        target version has not been chosen.

     successor:  A catalog verb name that callers should migrate to. *MAY*
        be absent if no single successor applies; clients should consult
        the verb's description for migration guidance.

  4.3.  Manifest Catalog Declaration

     Every server manifest *MUST* declare:

     catalog_version:  The catalog version the server validates incoming
        method names against.

     catalog_versions_supported:  A list of catalog versions the server
        can validate against.  The current catalog_version *MUST* appear
        in this list.  Multi- version support is anticipated; v00 servers
        commonly list a single version.

     Agents reading a manifest learn which catalog version they should use
     for outbound requests against this server.  Mismatches are handled at
     request time per the runtime semantics below.

  4.4.  Runtime Deprecation Signaling

     When a server processes a request whose method is deprecated in the
     catalog version the server is using, the server *MUST* include the
     AGTP-Catalog-Warning header on the response:

     AGTP-Catalog-Warning: deprecated; successor=AUDIT; removed_in=2.0.0

     Header fields:

     *  deprecated — keyword token indicating the warning class.

     *  successor=NAME — the recommended replacement verb.  Omitted if the
        catalog metadata does not declare a successor.

     *  removed_in=VERSION — the target removal version.  Omitted if not
        declared.

     The header is advisory, not a rejection.  The request *MUST* still
     process.  Agents and CLIs that surface the header to their users
     allow operators to schedule migration before forced removal.







  Hood                    Expires 13 November 2026               [Page 11]


  Internet-Draft                  AGTP-API                        May 2026


     A server that receives a request whose method is in the catalog at
     all (deprecated or not) *MUST NOT* return 459 Method Violation. 459
     is reserved for verbs that are not in the catalog at all.  Deprecated
     verbs are still in the catalog.

  4.5.  Removal Behavior

     When a verb is removed in a MAJOR catalog revision, servers upgrading
     to that revision *MUST*:

     1.  Reject inbound requests for the removed verb with 459 Method
         Violation, citing the catalog version the server is now using.

     2.  Refuse to load endpoint TOMLs declaring removed verbs at startup,
         logging which endpoints are affected.

     3.  Invalidate any active synthesis plans whose steps reference
         removed verbs, returning a structured failure on the next
         synthesis tick.

     4.  Skip policies.methods entries (allow, disallow, redirects) that
         reference removed methods, logging each skip.

     This is graceful degradation: the server starts, serves the endpoints
     that are still valid, and surfaces what was lost.  The operator
     decides whether to roll back, fix the affected endpoints, or accept
     the reduced surface.

  4.6.  Cross-Server Version Negotiation

     When an agent talks to a server whose catalog_version differs from
     the agent's own preferred version, the agent *SHOULD*:

     1.  Read catalog_versions_supported from the manifest.

     2.  If the agent's preferred version is in the list, use it; the
         server will validate against that version.

     3.  If not, downgrade to the highest mutually-supported version.

     4.  If no overlap exists, abandon the connection or escalate to the
         principal.

     Servers *MAY* support multiple catalog versions concurrently; servers
     *MAY* support only the single version they declare in
     catalog_version.  Agents adapt to the server's capabilities.





  Hood                    Expires 13 November 2026               [Page 12]


  Internet-Draft                  AGTP-API                        May 2026


  4.7.  Tooling

     A reference agtp-catalog-diff tool is published alongside the method
     catalog.  The tool diffs two catalog versions, reports added /
     removed / newly-deprecated methods, and *MAY* scan a deployment
     directory (endpoint TOMLs, recipe registry, agtp-server.toml) to
     identify which deployment artifacts would break under a candidate
     catalog upgrade.  See Appendix A.

     Tool invocation:

    agtp-catalog-diff old.json new.json [--against-deployment <directory>]

     The tool produces a structured diff showing methods added in the new
     catalog, methods removed, methods newly deprecated, path-grammar
     conflicts (existing endpoint paths containing newly-added method
     names), endpoint conflicts (existing endpoints declaring removed
     methods), recipe conflicts (existing recipes referencing removed
     methods), and policy conflicts (existing policy directives
     referencing removed methods).

     Operators *SHOULD* run this tool before upgrading a server's catalog
     version.  The tool's exit code indicates whether breaking changes
     exist: 0 (no breakage), 1 (breakage in deployment context), 2 (parse
     errors).

     The tool is implementation-provided; alternative implementations
     *MAY* ship equivalents.  The diff format is specified by the
     implementation's documentation rather than normatively by this
     section.

  4.8.  Multi-Version Catalog Support

     Future revisions of AGTP-API may specify how servers can validate
     against multiple catalog versions simultaneously, allowing graceful
     migration during transitions.  The catalog_versions_supported
     manifest field is reserved for this purpose.

     For v00 conforming servers, catalog_versions_supported *MUST* be a
     single-element array containing only the server's current
     catalog_version.










  Hood                    Expires 13 November 2026               [Page 13]


  Internet-Draft                  AGTP-API                        May 2026


  4.9.  Catalog Publishing

     The canonical AGTP method catalog is published at
     https://agtp.io/api/methods.json.  The catalog is versioned
     independently of AGTP-API itself; a server may implement AGTP-API v00
     against catalog version 1.0.0 today, and against catalog version
     1.1.0 after a minor catalog update.

     Servers *MAY* validate against alternative catalogs (industry-
     specific catalogs, internal-only catalogs, etc.) by configuring their
     build to use a different catalog document.  The catalog_version
     exposed in the manifest reflects whichever catalog the server
     actually validates against.

     Catalog updates follow a coordinated release process: the publisher
     announces the upcoming version, operators run the diff tool against
     their deployments, the new catalog is published, operators upgrade
     their servers.  Specific governance for the canonical catalog
     (proposal process, approval cadence, etc.) is documented separately
     and is out of scope for this specification.

  5.  Path Grammar

     AGTP path grammar prevents method-name leakage — the situation where
     a method token ends up in a path segment instead of on the request
     line.  The grammar enforces that one rule plus structural minimums;
     everything else is operator judgment.

  5.1.  Path Rules

     A request path *MUST* begin with /. A request path *MUST NOT* end
     with / unless the path is exactly / (the bare root).  No path segment
     *MAY* match an approved AGTP method name (case-insensitive, after
     stripping - and _).  Parameter segments wrapped in {...} are exempt
     from the method-token check.

     Any violation *MUST* return status *460 Endpoint Violation* with the
     offending segment in the response body.

  5.2.  Path Grammar ABNF

     The path component of the request line follows this grammar:









  Hood                    Expires 13 November 2026               [Page 14]


  Internet-Draft                  AGTP-API                        May 2026


     path           = "/" [ segment-nz *( "/" segment ) ]
     segment        = *segment-char
     segment-nz     = 1*segment-char
     segment-char   = unreserved / pct-encoded / sub-delims
                    / ":" / "@"
     parameter      = "{" parameter-name "}"
     parameter-name = 1*( ALPHA / DIGIT / "_" )
     unreserved     = ALPHA / DIGIT / "-" / "." / "_" / "~"
     pct-encoded    = "%" HEXDIG HEXDIG
     sub-delims     = "!" / "$" / "&" / "'" / "(" / ")"
                    / "*" / "+" / "," / ";" / "="
                                             ; per RFC 3986

     A segment *MAY* be a literal segment (matching segment-nz with no {
     or } characters) or a parameter segment (matching the parameter
     production exactly).  Mixing literal and parameter forms within a
     single segment (e.g., prefix-{id}) is *NOT* supported in v00; future
     revisions *MAY* specify mixed-form templates.

     Parameter names within a path *MUST* be unique.  A path containing
     two parameters with the same name *MUST* be rejected at endpoint
     registration time.

  5.3.  Permissiveness

     Mixed case, underscores, hyphens, and any segment depth are valid.
     The protocol does not impose style preferences.  Casing conventions,
     kebab-vs-snake-case, and parameter-naming style are operator
     decisions.

     Path templates support typed parameters in curly braces:

     /customers/{customer_id}
     /orders/{order_id}/line-items/{line_item_id}
     /products/category/{category_slug}

     The {name} form is the only template syntax v00 admits.  URI Template
     ([RFC6570]) syntax (e.g., {?query,page}, {+reserved}, {#fragment}) is
     *NOT* supported; servers encountering a path template that uses
     anything other than the basic {name} form *MUST* reject the endpoint
     at registration time.  The conservative single-form rule keeps
     endpoint dispatch deterministic and predictable; future revisions
     *MAY* broaden the template grammar.








  Hood                    Expires 13 November 2026               [Page 15]


  Internet-Draft                  AGTP-API                        May 2026


     Template parameters *MUST* be declared in the endpoint's input_schema
     as JSON Schema properties of the same name.  A template parameter
     that is not declared in input_schema *MUST* cause registration to
     fail.  Parameter values arrive at the handler as part of the
     validated input alongside body parameters.

  5.4.  Path Pattern Matching

     Servers match an incoming request path against registered endpoints
     in three passes:

     1.  *Exact match.* If the request path exactly equals a registered
         literal path (no template parameters), the matching endpoint is
         selected.

     2.  *Template match.* If no exact match, the request path is matched
         against registered templates.  A template matches when the path
         has the same number of segments as the template and every literal
         segment matches exactly while every {param} segment captures the
         corresponding request segment as a parameter value.

     3.  *No match.* If neither pass matches, the server *MUST* return 404
         Not Found.

     When multiple templates would match the same request path, the server
     *MUST* select the template with the fewest parameter segments (most
     specific wins).  If two templates have the same number of parameter
     segments and both match, registration *MUST* have failed at startup
     with a path-ambiguity error; the dispatcher *MUST NOT* be reached in
     this state.

  5.5.  Query Strings

     Paths *MAY* carry a query string after a ?:

     AGTP/1.0 SCHEDULE /meeting?date=050526&attendees=alice%2Cbob

     The wire layer splits the request-target at the first ? per
     [RFC3986]: the path is everything from the leading / up to the first
     ? or end-of-line; the query string is everything after the first ?.
     Path-grammar enforcement (method-name leakage check, template
     matching) applies to the path component only; query strings carry no
     semantic constraints from this grammar.

     Query parameters merge into the request input alongside body
     parameters before schema validation.  On key conflicts, body
     parameters take precedence.  Repeated query keys collapse to the last
     value; multi-valued shapes ride in the body.



  Hood                    Expires 13 November 2026               [Page 16]


  Internet-Draft                  AGTP-API                        May 2026


     Servers *MUST* percent-decode query parameter values per [RFC3986]
     Section 2.1 before schema validation.

  5.6.  Fragments

     URI fragments (#anchor) are *REJECTED* at the wire layer.  AGTP
     traffic carries no client-side anchoring use case; a # in the request
     line is always malformed.  Servers *MUST* return 400 Bad Request with
     error code invalid-request-line for any request line containing #.

  5.7.  No Reserved Path Prefixes

     AGTP reserves no path prefixes.  There is no /.well-known/ discovery
     surface and no /_agtp/ namespace.  AGTP is its own protocol; HTTP-
     style discovery conventions do not apply.

  5.8.  Server Metadata via AGTP Methods

     Server-internal metadata is exposed via AGTP methods at AGTP-native
     paths, registered as built-in endpoints alongside operator-authored
     endpoints.  Servers *MUST* expose DISCOVER /methods, returning a
     compact inventory of every endpoint the server has registered:

     [
       {
         "method": "QUERY",
         "path": "/catalog",
         "description": "Returns the current product catalog."
       },
       {
         "method": "BOOK",
         "path": "/room",
         "description": "Books a room for the named guest at the named property."
       },
       {
         "method": "DISCOVER",
         "path": "/methods",
         "description": "Lists all registered endpoints on this server."
       }
     ]

     The response is a JSON array of objects, each with method, path, and
     description.  The verb is DISCOVER because the response carries
     endpoints to talk to (the AGTP semantics for DISCOVER, see [AGTP])
     rather than data to consume; agents use the response to drive follow-
     on invocations against the listed endpoints.





  Hood                    Expires 13 November 2026               [Page 17]


  Internet-Draft                  AGTP-API                        May 2026


     The DISCOVER /methods response is a lightweight inventory; agents
     that need full endpoint definitions (semantic blocks, schemas,
     deprecation metadata, handler types) *MUST* retrieve the full server
     manifest via target-less DISCOVER (Section 8).  The built-in exists
     as a cheap, low-bandwidth probe for endpoint shape — useful for
     clients that need to know what to ask for without loading the full
     manifest.

     Built-in endpoints appear in the server manifest like any other
     endpoint (including DISCOVER /methods itself, which is one of the
     entries returned by its own invocation), are subject to the same
     dispatcher gates (catalog, path grammar, policy), and *MAY* be
     overridden by operator-authored TOML at the same (method, path) pair.
     Operators that override a built-in are responsible for preserving the
     documented response contract.

     Future revisions of this specification *MAY* define additional built-
     in endpoints (e.g., QUERY /catalog-version for catalog version
     negotiation).  Built-ins are protocol-level conventions, not
     deployment-level extensions.

  6.  The Endpoint Primitive

  6.1.  Endpoint Definition

     An endpoint is the structural unit an AGTP server exposes.  Every
     endpoint is identified by the pair (method, path) and carries the
     fields specified below.

     {
       "method": "BOOK",
       "path": "/room",
       "description": "Books a room for the named guest at the named property.",
       "namespace": "reservations",

       "semantic": {
         "intent": "Reserve a room for the named guest at the named property.",
         "actor": "agent",
         "outcome": "A confirmed reservation_id is returned for the guest.",
         "capability": "transaction",
         "confidence": 0.85,
         "impact": "irreversible",
         "is_idempotent": false
       },

       "input_schema": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",



  Hood                    Expires 13 November 2026               [Page 18]


  Internet-Draft                  AGTP-API                        May 2026


         "properties": {
           "guest_id": { "type": "string", "format": "uuid" },
           "room_id":  { "type": "string" },
           "arrival":  { "type": "string", "format": "date" },
           "departure":{ "type": "string", "format": "date" }
         },
         "required": ["guest_id", "room_id", "arrival", "departure"],
         "additionalProperties": false
       },

       "output_schema": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",
         "properties": {
           "reservation_id": { "type": "string", "format": "uuid" }
         },
         "required": ["reservation_id"],
         "additionalProperties": true
       },

       "errors": ["room_unavailable", "invalid_dates"],

       "handler": { "type": "registered_function" },

       "required_scopes": ["booking:room", "calendar:write"],

       "deprecated": {
         "deprecated_in": "2.1.0",
         "removed_in": "3.0.0",
         "successor": { "method": "RESERVE", "path": "/rooms" }
       }
     }

  6.2.  Required Fields

     Every endpoint *MUST* carry: method, path, description, semantic,
     input_schema, output_schema, errors, handler.  The remaining fields
     (namespace, required_scopes, deprecated) are optional.

  6.3.  Field Semantics

     method:  An AGTP method drawn from the approved catalog at the
        server's declared catalog_version, or a custom method declared in
        the server's policies.methods.  See Section 3.3.  The method name
        satisfies the lexical rules of Section 3.2.

     path:  A path conforming to the path grammar of Section 5.




  Hood                    Expires 13 November 2026               [Page 19]


  Internet-Draft                  AGTP-API                        May 2026


     description:  Operator-facing prose.  A single sentence describing
        what the endpoint does.  Distinct from the semantic block:
        description is for humans reading the manifest; the semantic block
        is for agents reasoning about applicability.

     namespace:  Optional free-form grouping label.  Servers exposing many
        endpoints *MAY* organize them by namespace (e.g., "reservations",
        "billing", "inventory") for catalog navigation.  Namespace has no
        protocol-level effect.

     semantic:  The structural metadata block defined in Section 7.
        Required by every endpoint with all required fields populated.

     input_schema:  A Draft 2020-12 JSON Schema [JSON-SCHEMA] describing
        the request body. *MUST* declare "type": "object" and *MUST* set
        "additionalProperties": false; see Section 13.3.  Query-string
        parameters (Section 5.5) are merged into the body before
        validation; the same schema covers both.  Schemas are inline in
        v00; cross-endpoint schema sharing is anticipated in a future
        revision.

     output_schema:  A Draft 2020-12 JSON Schema describing the successful
        response body. *SHOULD* set "additionalProperties": true so
        handlers can return forward-compat fields without bumping the
        contract; see Section 13.3.

     errors:  An array of named error condition strings (e.g.,
        "room_unavailable", "invalid_dates").  The dispatcher returns
        these as 422 Unprocessable Entity responses with structured bodies
        identifying the condition.  The error name is the protocol-level
        identifier; status-code mapping is a response-construction
        concern, not part of the contract.  The list *MAY* be empty for
        endpoints with no business-level errors.  Composition handlers
        *MUST* include "composition_failed"; external-service handlers
        *MUST* include the upstream-failure codes specified in
        Section 12.3.

     handler:  An object declaring the binding kind: {"type":
        "registered_function" | "composition" | "external_service"}. The
        handler's full reference (Python dotted path, recipe name,
        upstream URL, etc.) is server-internal implementation detail and
        *MUST NOT* appear in the manifest.  See Section 8.9 and
        Section 12.

     required_scopes:  An array of scope identifiers the invoking agent






  Hood                    Expires 13 November 2026               [Page 20]


  Internet-Draft                  AGTP-API                        May 2026


        *MUST* declare in its Authority-Scope.  Empty or omitted means no
        scope check; the endpoint inherits the server's default authority
        requirement.  Insufficient scope returns 455 Scope Violation per
        [AGTP].

     deprecated:  Optional per-endpoint deprecation metadata.  See
        Section 6.4.

  6.4.  Endpoint Deprecation

     The optional deprecated block follows the same shape as catalog-level
     deprecation:

     "deprecated": {
       "deprecated_in": "2.1.0",
       "removed_in": "3.0.0",
       "successor": { "method": "RESERVE", "path": "/rooms" }
     }

     Field semantics:

     deprecated_in:  The server's agtp_api_version (or operator-chosen
        version string) at which the endpoint became deprecated.

     removed_in:  Optional.  The version at which the endpoint will be
        removed. *MAY* be absent if removal is anticipated but the target
        version has not been chosen.

     successor:  Optional.  An object with method and/or path indicating
        the replacement endpoint callers should migrate to.  Either field
        *MAY* be absent: successor.method alone signals "use the same path
        with a different method"; successor.path alone signals "use the
        same method with a different path"; both together signal a full
        replacement endpoint.

     An endpoint *MAY* be deprecated even when its method and path remain
     valid in the catalog and grammar.  Operators deprecate endpoints when
     they migrate callers from one (method, path) pair to another,
     independent of catalog evolution.

     The dispatcher *MUST* stamp an AGTP-Endpoint-Warning advisory header
     on every response from a deprecated endpoint:

  AGTP-Endpoint-Warning: deprecated; successor=RESERVE /rooms; removed_in=3.0.0

     The header rides alongside AGTP-Catalog-Warning (Section 4) when both
     apply; both are advisory and the request still processes.  The
     successor token renders as METHOD /path when both fields are present;



  Hood                    Expires 13 November 2026               [Page 21]


  Internet-Draft                  AGTP-API                        May 2026


     just one is emitted bare. removed_in and successor are omitted from
     the header when the endpoint's deprecated block does not declare
     them.  The header fires on success and failure responses alike so
     callers always see the warning regardless of how the invocation
     resolves.

  7.  The Semantic Block

     The semantic block is the part of the endpoint definition that
     encodes machine-readable intent.  Agents reason about whether an
     endpoint matches their goal by interpreting the semantic block, not
     by parsing the verb and path alone.  The empirical evidence for
     intent-expressing semantic metadata is documented in [HOOD2026].

  7.1.  Required Semantic Block Fields

     intent:  A natural-language statement of what the endpoint
        accomplishes.  Single sentence.  Imperative form.  Subject is the
        actor; the verb reflects the endpoint's method; the object is the
        path resource.

     actor:  A short identifier of the agent class that should invoke this
        endpoint.  Freeform string; servers *MUST NOT* reject endpoints
        whose actor is not in a fixed enum.  Suggested values for
        interoperable authoring include agent, human, system, customer,
        staff, admin; domain-specific values (e.g., merchant, auditor,
        patient) are equally valid.  The field helps agents recognize
        whether an endpoint applies to their role but carries no protocol-
        level enforcement.

     outcome:  A natural-language statement of the post-condition produced
        by successful invocation.  Distinct from intent: intent is what
        the endpoint sets out to do; outcome is what is true after.

     capability:  The high-level effect class of the endpoint.  One of the
        catalog category values: discovery, retrieval, analysis,
        transaction, modification, creation, notification, mechanics,
        domain_spanning.  The same taxonomy used to classify methods in
        the catalog (Section 3); an endpoint inherits its capability class
        from the category of the method it exposes, though operators *MAY*
        override when the endpoint's specific behavior fits a different
        category.

     confidence:  A scalar on the closed interval 0.0 to 1.0 expressing
        how confident the server is that an agent invoking this endpoint
        with satisfying input will produce the declared outcome.
        Endpoints that are deterministic and well-tested score near 1.0;
        endpoints that involve nondeterministic resources or partial



  Hood                    Expires 13 November 2026               [Page 22]


  Internet-Draft                  AGTP-API                        May 2026


        failures score lower.  Agents *MAY* use the value to decide
        whether to ESCALATE for clarification before invoking.  The scale
        is advisory and not normatively defined beyond the endpoint
        bounds.

     impact:  The reversibility of the endpoint's effect.  One of
        informational, reversible, irreversible. informational endpoints
        return data without changing server state. reversible endpoints
        change state in ways that can be undone via a compensating method
        (e.g., CANCEL, REFUND). irreversible endpoints commit changes that
        cannot be programmatically undone (e.g., sending an email,
        charging a payment, shipping goods).  Governance frameworks *MAY*
        use this field to apply differential authorization, gating
        irreversible endpoints behind stricter scope checks.

     is_idempotent:  Boolean.  Whether repeated invocation with identical
        input produces identical effect.  Affects retry safety: idempotent
        endpoints *MAY* be retried freely; non-idempotent endpoints
        require an Idempotency-Key header per [AGTP] to be safely retried.

  8.  Server Manifest

  8.1.  Purpose

     The server manifest is the machine-readable document an AGTP server
     publishes to declare its identity, version posture, endpoint catalog,
     hosted agents, hosted protocols, and operational policies.  It is the
     authoritative answer to "what does this server offer."

  8.2.  Manifest Structure





















  Hood                    Expires 13 November 2026               [Page 23]


  Internet-Draft                  AGTP-API                        May 2026


     {
       "agtp_version": "1.0",
       "agtp_api_version": "1.0",
       "document_version": "v2",
       "catalog_version": "1.0.0",
       "catalog_versions_supported": ["1.0.0"],

       "server": {
         "server_id": "agents.acme.com",
         "domain": null,
         "operator": "Acme Retail",
         "contact": "ops@acme.com",
         "supported_features": ["endpoint-registry", "synthesis"],
         "issued": "2026-01-15T09:00:00Z",
         "updated": "2026-04-15T09:00:00Z"
       },

       "embedded_methods": [ /* twelve floor methods */ ],
       "custom_methods": [ /* server-specific methods declared in policies.methods */ ],
       "endpoints": [ /* array of endpoint definitions, projected */ ],

       "agent_disclosure": "public",
       "hosted_agents": [ /* agent identity references */ ],
       "agent_disclosure_notice": null,

       "apis": [ /* legacy HTTP APIs this server fronts, if any */ ],
       "hosted_protocols": [ /* MCP, A2A, ACP, etc. */ ],

       "policies": {
         "wildcards_accepted": false,
         "anonymous_discovery": true,
         "scope_required_for_invocation": true,
         "synthesis_enabled": true,
         "max_synthesis_depth": 10
       },

       "manifest_signature": null
     }

     The manifest carries three distinct version fields at the top level:

     agtp_version:  The AGTP wire-protocol version the server speaks
        (currently "1.0", corresponding to AGTP v07 of [AGTP]).  Pinned to
        the base protocol, separate from contract-layer evolution.

     agtp_api_version:  The AGTP-API contract-layer version the server





  Hood                    Expires 13 November 2026               [Page 24]


  Internet-Draft                  AGTP-API                        May 2026


        implements (currently "1.0" for v00 of this document).  Carries
        the endpoint primitive, semantic block, status code, and synthesis
        semantics the server adheres to.

     document_version:  This specific manifest's revision string.
        Operator-controlled; bumped on every meaningful change to the
        manifest content.  Permits agents to detect cache staleness
        without comparing the full body.

     catalog_version:  The method catalog version the server validates
        incoming method names against.  See Section 4.

     catalog_versions_supported:  List of catalog versions the server can
        validate against.  The current catalog_version *MUST* appear in
        this list.  Multi-version support is anticipated in a future
        revision but is not normatively specified in v00.

  8.3.  Server Block

     The server block carries operator-facing identity and timestamps:

     server_id:  The canonical identifier for this server. *MAY* be a
        hostname, an agtp:// URI, or an operator-defined string.  The
        value *MUST* be stable across manifest revisions.

     domain:  Optional operational host the server is reachable at, if
        different from server_id. *MAY* be null for servers whose
        server_id is itself a resolvable host.

     operator:  The human-readable name of the organization operating the
        server.

     contact:  An operator email address for security and operational
        issues.

     supported_features:  A non-normative array of feature tokens
        describing optional capabilities the server exposes (e.g.,
        "endpoint-registry", "synthesis", "openapi-export").  Agents and
        operators *MAY* use these tokens for capability negotiation.
        AGTP-API does not define a canonical feature-token registry;
        tokens are operator-defined.

     issued:  ISO 8601 timestamp of when the manifest was first issued.
        Preserved across manifest revisions; identifies the manifest's
        origin in time.

     updated:  ISO 8601 timestamp of the most recent manifest update.
        Bumped on every regeneration.



  Hood                    Expires 13 November 2026               [Page 25]


  Internet-Draft                  AGTP-API                        May 2026


  8.4.  Methods Inventory

     The embedded_methods array carries the twelve protocol-floor methods
     every AGTP server supports (see [AGTP] §6).  The custom_methods array
     carries any server-specific methods declared in policies.methods
     (Section 3.3).  The custom_methods field *MAY* be omitted when empty.

     These arrays are non-normatively populated; agents that want a
     complete picture of what the server invokes *SHOULD* consult the
     endpoints array, which is the authoritative source for what methods
     are bound on what paths.

  8.5.  Agents Disclosure

     The three agent-related fields describe what agents the server hosts
     and how they are exposed:

     agent_disclosure:  One of "public", "authenticated", "private".
        "public" means the hosted_agents array is populated and visible to
        all callers. "authenticated" means the array is populated only for
        callers presenting a verified identity. "private" means the array
        is empty in this manifest; the server does not disclose what
        agents it hosts.

     hosted_agents:  Array of agent identity references the server hosts.
        Format is operator-defined; typical entries include a canonical
        Agent-ID and a brief description.

     agent_disclosure_notice:  Optional human-readable note explaining the
        server's disclosure policy.  Useful when agent_disclosure is
        "authenticated" or "private" and the operator wishes to clarify
        how a caller can request elevated disclosure.

  8.6.  Protocol and API Surface

     apis:  Optional array of legacy HTTP API descriptors this server
        fronts (e.g., entries pointing at OpenAPI specifications).
        Servers that expose a parallel HTTP surface alongside AGTP list
        those HTTP endpoints here; the presence of entries in this array
        is the signal that the server operates a parallel HTTP face.

     hosted_protocols:  Optional array of higher-level agent protocols the
        server hosts on top of AGTP (e.g., MCP, A2A, ACP).  Each entry is
        an object with the protocol name and the AGTP method+path it is
        reachable via.  See the composition section in [AGTP].






  Hood                    Expires 13 November 2026               [Page 26]


  Internet-Draft                  AGTP-API                        May 2026


  8.7.  Policies Block

     The policies block carries five normative operational toggles:

     wildcards_accepted:  One of true, false.  Whether the server accepts
        ad-hoc method invocations against undeclared endpoints.  See
        Section 5.8.

     anonymous_discovery:  One of true, false.  Whether unauthenticated
        callers may retrieve the manifest and invoke read-only built-in
        endpoints.  Servers serving traffic from open networks typically
        set this to true; servers in trusted-network deployments *MAY* set
        this to false to require authenticated identity even on discovery.

     scope_required_for_invocation:  One of true, false.  Whether every
        endpoint invocation requires the agent to carry an Authority-Scope
        header. true is the default; the implementation *MUST NOT* invoke
        a handler when scope is required and absent.  Servers with no
        scope-gated endpoints *MAY* set this to false.

     synthesis_enabled:  One of true, false.  Whether the server
        participates in PROPOSE-and-synthesis runtime contract
        negotiation.  When false, PROPOSE requests *MUST* be refused with
        463 Proposal Rejected and the reason synthesis-disabled.

     max_synthesis_depth:  A positive integer specifying the maximum
        number of composed steps a synthesized endpoint *MAY* combine.
        Plans exceeding this depth are refused; the server falls through
        to counter-proposal or 463.  Default: 10.

  8.8.  Manifest Signature

     The manifest body *SHOULD* carry a manifest_signature field holding a
     JWS envelope over the canonical JSON encoding of the manifest body
     (with the manifest_signature field itself excluded from the signing
     input).  Clients *MAY* verify signatures when present and *SHOULD*
     warn when absent.

     A future revision of this specification will require
     manifest_signature (*MUST*); reference implementations are expected
     to ship signing support in alignment with that revision.  The signing
     algorithm, canonical encoding rules, and key-publication mechanism
     are specified separately in [AGTP-CERT].

     For v00, the manifest_signature field *MAY* be null or absent; a
     manifest without a valid signature *MUST NOT* be rejected by clients
     on signature grounds alone.




  Hood                    Expires 13 November 2026               [Page 27]


  Internet-Draft                  AGTP-API                        May 2026


  8.9.  Endpoint Projection

     The endpoints array in the manifest is a projection of the server's
     internal endpoint catalog.  The projection differs from the full
     endpoint definition in one important way: the handler's type-specific
     reference field (function, recipe, or url) and any other binding-
     specific implementation details are dropped, leaving only the binding
     kind under handler.type.

     Internal endpoint definition (on disk, in TOML or equivalent):

     {
       "method": "BOOK",
       "path": "/room",
       "description": "...",
       "semantic": { ... },
       "input_schema": { ... },
       "output_schema": { ... },
       "errors": [ ... ],
       "required_scopes": [ ... ],
       "handler": {
         "type": "registered_function",
         "function": "rooms.handlers.book_room"
       }
     }

     Manifest projection (over the wire):

     {
       "method": "BOOK",
       "path": "/room",
       "description": "...",
       "semantic": { ... },
       "input_schema": { ... },
       "output_schema": { ... },
       "errors": [ ... ],
       "required_scopes": [ ... ],
       "handler": { "type": "registered_function" }
     }

     The type-specific reference field (function, recipe, or url) and any
     other binding-specific implementation fields are server-internal and
     *MUST NOT* appear in the manifest projection.  Agents need to know
     the binding kind to reason about expected latency, retry behavior,
     and attribution; agents do not need to know which specific function,
     recipe, or upstream realizes the binding.

     Servers *MUST* apply this projection on every manifest response.



  Hood                    Expires 13 November 2026               [Page 28]


  Internet-Draft                  AGTP-API                        May 2026


  8.10.  Manifest Retrieval

     Agents retrieve the server manifest using the AGTP DISCOVER method
     without an Agent-ID header.  The absence of an Agent-ID header
     distinguishes a server-level discovery request (returns the manifest)
     from an agent-level discovery request (returns endpoint candidates
     matching specified criteria).

     The response *MUST* carry Content-Type application/
     vnd.agtp.manifest+json.  The manifest *SHOULD* be signed; see the
     Manifest Signature subsection above.

  8.11.  Manifest Caching

     Servers *SHOULD* include Cache-Control and ETag headers on manifest
     responses.  Agents *MAY* cache manifests according to those
     directives.  The server.updated timestamp and the document_version
     field permit agents to detect cache staleness without revalidation: a
     changed document_version means the manifest content has changed in a
     way the operator considers significant.

  9.  Method Policy

  9.1.  Purpose

     The method policy declares per-server constraints on which methods
     are accepted, which legacy verbs are opted in, and which methods on
     which paths are redirected to their canonical form.  The policy is
     the small, declarative complement to the endpoint catalog: the
     catalog says what an endpoint does; the policy says what the server
     accepts in the first place.

     In v00, the method policy is a sub-block of the manifest's policies
     (Section 8) carried at policies.methods.  There is no separate policy
     file format; the policy is part of the server's configuration and is
     exposed on the manifest like any other operational policy.

  9.2.  Policy Shape

     The policies.methods block is a JSON object with four optional
     fields:

     allow:  Either the string "*" (the server admits every method in the
        catalog plus any method it has registered an endpoint for), or an
        array of method names (the server admits only the listed methods
        plus the embedded twelve floor methods).  Default: "*".

     disallow:  Array of method names the server explicitly rejects.



  Hood                    Expires 13 November 2026               [Page 29]


  Internet-Draft                  AGTP-API                        May 2026


        Disallowed methods are rejected with 405 Method Not Allowed even
        when they would otherwise be permitted by allow.  Useful for
        narrowing the surface without enumerating an exhaustive allow
        list.  Default: empty array.

     legacy:  Either an array of legacy HTTP verb names the server opts
        into (e.g., ["GET", "POST"]), the string "*" (all five legacy
        verbs accepted), or the string "NONE" (no legacy support).
        Granular per-verb opt-in supersedes the binary enabled/disabled
        toggle.  Default: "NONE".

     redirects:  Array of method-and-path redirect entries.  Each entry
        has the shape:

        {
          "from_method": "BOOK",
          "from_path": "/room",
          "to_method": "RESERVE",
          "to_path": "/room"
        }

        Either from_path or to_path *MAY* be omitted, signaling "redirect
        on method-only without path matching" or "redirect to the same
        path as the request."  When a request matches a redirect entry,
        the server processes it as if the to_method/to_path had been
        requested instead.

  9.3.  Example

     A representative TOML deployment configuration:

     [policies.methods]
     allow = "*"
     disallow = ["PATCH", "TRANSFER"]
     legacy = ["GET"]

     [[policies.methods.redirects]]
     from_method = "BOOK"
     from_path = "/room"
     to_method = "RESERVE"
     to_path = "/room"

     The equivalent manifest projection:








  Hood                    Expires 13 November 2026               [Page 30]


  Internet-Draft                  AGTP-API                        May 2026


     "policies": {
       "methods": {
         "allow": "*",
         "disallow": ["PATCH", "TRANSFER"],
         "legacy": ["GET"],
         "redirects": [
           {
             "from_method": "BOOK",
             "from_path": "/room",
             "to_method": "RESERVE",
             "to_path": "/room"
           }
         ]
       }
     }

  9.4.  Catalog-Graceful Skip Semantics

     When the server loads policies.methods and an entry under allow,
     disallow, or redirects references a method removed from the catalog
     version the server has loaded, the entry *MUST* be skipped at load
     time with an operator-visible warning.  The server continues to
     operate; the policy entry has no effect.  This permits operators to
     upgrade the catalog without simultaneously rewriting the policy block
     to remove all references to retired methods.

     The legacy field continues to enforce the strict set of five HTTP
     verbs (GET, POST, PUT, DELETE, PATCH); typos or non-HTTP verbs in
     legacy *MUST* be rejected as a hard configuration error.

  9.5.  Discovery

     Agents discover the server's method policy by retrieving the server
     manifest via target-less DISCOVER (Section 8).  The policies.methods
     block is part of the manifest body and is covered by the manifest
     signature (Section 8) when present.

     Agents that need only an endpoint inventory (which methods on which
     paths are exposed, with one-line descriptions) *MAY* invoke DISCOVER
     /methods (Section 5.8) for a lightweight response that bypasses the
     full manifest weight.

  10.  PROPOSE and Synthesis








  Hood                    Expires 13 November 2026               [Page 31]


  Internet-Draft                  AGTP-API                        May 2026


  10.1.  Purpose

     PROPOSE is the AGTP method that triggers runtime contract
     negotiation.  An agent that needs an endpoint the server does not
     advertise submits a PROPOSE request carrying an AGTP-API-conformant
     endpoint 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 twelve floor methods defined in [AGTP].  Its
     parameter table is specified there.  This document specifies the
     synthesis semantics that govern server-side evaluation.

  10.2.  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 not declared
    Step 3:  Agent constructs an AGTP-API-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
               AGTP-API 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

  10.3.  Server-Side Synthesis Evaluation

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

     1.  *Method conformance.* Is the proposed method in the AGTP-API
         approved method catalog, or is it a custom method declared in the
         server's policies.methods (Section 3.3)?  If not, return 459
         Method Violation.

     2.  *Path conformance.* Does the proposed path satisfy Section 5?  If
         not, return 460 Endpoint Violation.





  Hood                    Expires 13 November 2026               [Page 32]


  Internet-Draft                  AGTP-API                        May 2026


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

     4.  *Schema conformance.* Are the input and output schemas valid JSON
         Schema documents?  If not, return 400 Bad Request.

     5.  *Authority sufficiency.* Does the proposing agent's declared
         Authority-Scope cover the proposed authority requirements?  If
         not, return 262 Authorization Required with body type scope-
         required.

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

     7.  *Policy acceptance.* Does the server's policy permit the proposed
         method-and-path combination?  If not, return 463 with reason:
         policy-refused.

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

  10.4.  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 does not hold, the synthesis *MUST* fail at evaluation time
     (step 5) rather than at execution time.

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




  Hood                    Expires 13 November 2026               [Page 33]


  Internet-Draft                  AGTP-API                        May 2026


  11.  Status Codes

     AGTP-API contributes the following structural rejection codes to the
     AGTP status code space.  The codes are registered with IANA per
     [AGTP] Section 9.3.

     +======+===============+============================================+
     | Code | Name          | Returned When                              |
     +======+===============+============================================+
     | 261  | Negotiation   | Server has accepted PROPOSE for            |
     |      | In Progress   | evaluation; agent polls via                |
     |      |               | QUERY /proposals/{proposal_id}             |
     |      |               | for terminal status                        |
     +------+---------------+--------------------------------------------+
     | 262  | Authorization | Request requires credential                |
     |      | Required      | establishment, additional                  |
     |      |               | Authority-Scope, wildcards                 |
     |      |               | consent, or authenticated                  |
     |      |               | identity that is not yet present           |
     +------+---------------+--------------------------------------------+
     | 263  | Proposal      | Server has synthesized and                 |
     |      | Approved      | instantiated the proposed                  |
     |      |               | endpoint                                   |
     +------+---------------+--------------------------------------------+
     | 404  | Not Found     | The path does not exist on this            |
     |      |               | server                                     |
     +------+---------------+--------------------------------------------+
     | 405  | Method Not    | Method and path are valid but              |
     |      | Allowed       | server policy does not expose              |
     |      |               | this combination                           |
     +------+---------------+--------------------------------------------+
     | 459  | Method        | The method is not in the AGTP-             |
     |      | Violation     | API approved catalog                       |
     +------+---------------+--------------------------------------------+
     | 460  | Endpoint      | The path violates AGTP-API path            |
     |      | Violation     | grammar (method-name leakage)              |
     +------+---------------+--------------------------------------------+
     | 463  | Proposal      | Server cannot or will not                  |
     |      | Rejected      | synthesize the proposed endpoint           |
     +------+---------------+--------------------------------------------+

                         Table 1: AGTP-API Status Codes

     The four structural rejection codes 404, 405, 459, 460 form the
     contract-level failure surface.  Each code is independently
     actionable and addresses a distinct failure mode:





  Hood                    Expires 13 November 2026               [Page 34]


  Internet-Draft                  AGTP-API                        May 2026


     *  *404* -- the path does not exist.  The agent has the wrong
        resource locator.

     *  *405* -- the method and path are individually valid but the server
        does not expose this combination.  The agent *MAY* try a different
        method on the same path, or *MAY* PROPOSE the combination if it is
        not a policy refusal.

     *  *459* -- the method itself is the problem.  The agent *MUST* pick
        a different method from the AGTP-API catalog.  PROPOSE will not
        succeed because the method name is not legal.

     *  *460* -- the path violates path grammar.  The agent *MUST*
        restructure the path so that no path segment matches an approved
        method name.

     These codes are not interchangeable.  A 405 is a policy decision; a
     459 is a vocabulary violation; a 460 is a structural violation.
     Servers *MUST* return the most specific code that applies.

     The 405 response body *MUST* carry the following fields:

     allowed_methods_for_path:  The list of methods the server's policy or
        registry exposes on the path.  Permits the agent to retry with a
        method the server actually accepts.

     redirects_for_path:  A map of method-to-method redirects from
        policies.methods (Section 9) that apply to this path. *MAY* be
        empty if the server has no redirects configured.  Permits the
        agent to learn that, for example, BOOK is redirected to RESERVE on
        this server, and to retry under the canonical method directly.

     These fields together let the agent recover from a 405 without an
     out-of-band catalog lookup or a second round-trip.

  12.  Handler Binding

     The handler binding declares how an endpoint's behavior is realized
     at runtime.  AGTP-API defines three binding types.

  12.1.  Composition

     A composition handler exposes a derived endpoint whose behavior is
     realized by orchestrating one or more other endpoints declared on the
     same server.  No application code is invoked; the server's synthesis
     runtime executes the composition steps in order, threading outputs
     into subsequent inputs while preserving authority through the
     composition.



  Hood                    Expires 13 November 2026               [Page 35]


  Internet-Draft                  AGTP-API                        May 2026


     Composition handlers reference a named recipe:

     "handler": {
       "type": "composition",
       "recipe": "audit-via-query-and-summarize"
     }

     The recipe value is the name of a recipe defined in the server's
     recipe registry (typically in an agtp-recipes.toml file loaded at
     server startup).  Recipes are reusable units of composition logic;
     one recipe *MAY* back multiple endpoints.  Inline composition steps
     are not supported in v00; every composition endpoint *MUST* reference
     a registered recipe by name.

     A composition handler whose recipe value does not resolve to a recipe
     registered at the server *MUST* cause registration to fail.

     Composition endpoints *MUST* include composition_failed in their
     errors list.  This is the named error returned when a composition
     step fails (any underlying step returns a non-success status).  The
     error response carries details with the recipe identifier, the failed
     step number, the underlying step method, the underlying status, and
     any captured outputs from preceding steps.

     Authority *MUST* be preserved through the composition.  The agent's
     Authority-Scope *MUST* be sufficient for every underlying endpoint
     the composition invokes.  Authority sufficiency is verified at
     registration time when possible (when step paths are statically
     known) and at invocation time for parameterized step paths.

     This is the binding type most commonly produced by PROPOSE +
     synthesis: a synthesized endpoint is a composition of existing
     endpoints, and *MAY* be promoted to a permanent declared composition
     by adding its recipe to the server's recipe registry and writing an
     endpoint TOML that references it by name.

  12.2.  Registered Function

     "handler": {
       "type": "registered_function",
       "function": "rooms.handlers.book_room"
     }









  Hood                    Expires 13 November 2026               [Page 36]


  Internet-Draft                  AGTP-API                        May 2026


     The endpoint binds to a Python function loaded by the server.  The
     function value is a dotted path identifying the module and the
     callable within it; the server imports the module at registration
     time and resolves the function attribute.  Single dotted-path form is
     normative; separate module and function fields are not supported in
     v00.

     The function receives the validated input and returns the response
     payload.  The handler API contract is specified separately (see the
     reference implementation's handler documentation).  This is the
     binding type used for endpoints whose logic exceeds what composition
     can express.

  12.3.  External Service

     "handler": {
       "type": "external_service",
       "url": "https://internal.acme.tld/booking",
       "method": "POST",
       "headers": {
         "Authorization": "Bearer ${BOOKING_API_TOKEN}",
         "Content-Type": "application/json"
       },
       "input_transform": {
         "guest_id": "guestId",
         "room_type": "roomType"
       },
       "output_transform": {
         "confirmation_code": "confirmationNumber"
       },
       "error_map": {
         "404": "room_not_found",
         "409": "room_unavailable"
       },
       "timeout_seconds": 30
     }

     The endpoint binds to an HTTPS-reachable external service.  The
     server proxies the request to the external endpoint and returns the
     response.  Useful for AGTP frontends to existing HTTP-based services.
     The external service is not part of the AGTP contract; the AGTP
     server presents a contract-compliant facade.

     External service fields:

     url:  The fully-qualified URL of the upstream HTTP endpoint.  The URL
        *MUST* use the https:// scheme.  Plain HTTP *MUST NOT* be accepted
        at registration time.



  Hood                    Expires 13 November 2026               [Page 37]


  Internet-Draft                  AGTP-API                        May 2026


     method:  The HTTP method to invoke on the upstream.  One of GET,
        POST, PUT, PATCH, DELETE, HEAD, OPTIONS. *REQUIRED*.

     headers:  Optional map of HTTP headers to send to the upstream on
        every request.  Values *MAY* include ${VAR} placeholders that are
        resolved against process environment variables at server startup.
        Unresolved placeholders *MUST* cause registration to fail.

     input_transform:  Optional map renaming AGTP request fields to the
        upstream's expected field names.  Maps AGTP-side name to upstream-
        side name.  Fields not in the map pass through unchanged. v00
        supports key-rename only; value transformation is anticipated in a
        future revision.

     output_transform:  Optional map renaming upstream response fields to
        AGTP-side names.  The map is inverted at response time: the
        upstream-side name is the source, the AGTP-side name is the
        target.  Fields not in the map pass through unchanged.

     error_map:  Map of upstream HTTP status code (as a string) to AGTP
        error code declared in the endpoint's errors list.  Servers
        *SHOULD* configure error_map for every external_service binding;
        without it, upstream HTTP errors surface to agents as generic
        upstream_error.  Every value in error_map *MUST* appear in the
        endpoint's errors; registration *MUST* fail otherwise.

     timeout_seconds:  Positive number specifying the upstream request
        timeout.  Servers *SHOULD* set this explicitly.  Default if
        absent: 30 seconds.  Production deployments *SHOULD NOT* rely on
        the default; explicit timeouts make upstream-dependency posture
        inspectable.

     External service endpoints *MUST* declare the following five
     upstream-failure error codes in their errors list, in addition to any
     business-level errors:
















  Hood                    Expires 13 November 2026               [Page 38]


  Internet-Draft                  AGTP-API                        May 2026


     +================================+==================================+
     | Error Code                     | Returned When                    |
     +================================+==================================+
     | upstream_timeout               | Upstream did not respond         |
     |                                | within timeout_seconds           |
     +--------------------------------+----------------------------------+
     | upstream_connection_error      | DNS, connection, or TLS          |
     |                                | failure reaching the upstream    |
     +--------------------------------+----------------------------------+
     | upstream_malformed_response    | Upstream returned a 2xx          |
     |                                | response whose body is not       |
     |                                | valid JSON                       |
     +--------------------------------+----------------------------------+
     | upstream_authentication_failed | Upstream returned 401 or 403     |
     |                                | not covered by error_map         |
     +--------------------------------+----------------------------------+
     | upstream_error                 | Upstream returned 4xx or 5xx     |
     |                                | not covered by error_map         |
     +--------------------------------+----------------------------------+

                Table 2: Mandatory External Service Error Codes

     Without these declarations, transport-level upstream failures would
     surface to the calling agent as opaque server errors.  Mandating them
     makes the failure surface inspectable.

     Agent identity is *NOT* propagated to the upstream by default.  This
     is a security default: an upstream HTTP service has no mechanism to
     validate AGTP agent credentials, and forwarding them would expose
     principal identity to systems outside the AGTP trust boundary.
     Servers wishing to propagate identity to a specific upstream *MAY* do
     so via explicit header configuration in the headers map (e.g., a
     server-issued bearer token), but *MUST NOT* forward AGTP-Agent-ID or
     AGTP-Principal-ID by default.

  13.  Conformance

  13.1.  Single Tier

     A conforming AGTP server implements:

     1.   The full endpoint primitive (Section 6).

     2.   Method validation against the AGTP-API approved catalog at the
          server's declared catalog_version.

     3.   Path validation against the AGTP-API path grammar.




  Hood                    Expires 13 November 2026               [Page 39]


  Internet-Draft                  AGTP-API                        May 2026


     4.   Method policy enforcement at dispatch time per the
          policies.methods sub-block of the manifest (Section 9).

     5.   A server manifest retrievable via DISCOVER without an Agent-ID
          header, carrying agtp_version, agtp_api_version,
          document_version, catalog_version, and
          catalog_versions_supported per Section 8.

     6.   The endpoint projection of Section 8.9: manifest responses
          expose handler.type only, not the full handler binding.

     7.   PROPOSE handling with the synthesis evaluation flow specified in
          this document, gated by policies.synthesis_enabled.

     8.   The structural rejection status codes 404, 405, 459, 460, plus
          the contract-negotiation codes 261, 262, 263, 463.

     9.   The semantic block on every published endpoint.

     10.  Schema validation for input and output, with the strictness
          asymmetry of Section 13.3 (inputs strict, outputs permissive by
          default).

     11.  The AGTP-Catalog-Warning response header on every response whose
          method is deprecated in the catalog version in use.

     12.  The AGTP-Endpoint-Warning response header on every response from
          a deprecated endpoint (Section 6.4).

     13.  The DISCOVER /methods built-in endpoint defined in Section 5.8,
          returning a compact inventory of the server's registered
          endpoints.

     There is no halfway tier.  Servers that implement only method
     dispatch without endpoints are not AGTP-conformant; they are
     something else, perhaps a method-based RPC layer that happens to use
     AGTP framing.

  13.2.  Validation Timing

     Conforming servers perform two distinct categories of validation,
     which *SHOULD* occur at different times.

     *Manifest validation at startup.* Before accepting traffic, a
     conforming server *SHOULD* validate every endpoint declared in its
     manifest:





  Hood                    Expires 13 November 2026               [Page 40]


  Internet-Draft                  AGTP-API                        May 2026


     *  The method appears in the AGTP-API approved catalog (or is a
        custom method declared in the server's policies.methods).

     *  The path conforms to the path grammar of Section 5.

     *  The semantic block carries every required field.

     *  The input and output schemas are syntactically valid JSON Schema
        documents.

     *  The handler binding (Section 12) is resolvable: a composition's
        referenced steps exist; a registered_function's module and
        function are importable; an external_service's URL is well-formed
        and reachable (or marked deferred).

     A server that detects manifest validation failures at startup
     *SHOULD* reject the offending endpoints with clear logs and *SHOULD
     NOT* silently ignore them.  Servers *MAY* choose to fail startup
     entirely on manifest validation failure or to start serving with the
     valid subset of endpoints; the choice is a deployment policy
     decision.

     *Request validation at runtime.* Once serving, the server validates
     each inbound request against the endpoint's input schema before
     invoking the handler:

     *  Input body validates against the endpoint's input_schema.  On
        failure, the server returns 422 Unprocessable Entity with a schema
        validation error report.

     *  The agent's Authority-Scope covers the endpoint's required_scopes
        declarations.  On failure, the server returns 455 Scope Violation
        per [AGTP].

     *  The verb-and-path combination is exposed by the server's current
        policy.  On failure, the server returns the appropriate structural
        rejection code (404, 405, 459, or 460).

     Validation *MUST* complete before handler invocation.  Servers *MUST
     NOT* invoke the handler with input that has not satisfied schema
     validation; this guarantee is what allows handler authors to assume
     their context structure is well-formed.









  Hood                    Expires 13 November 2026               [Page 41]


  Internet-Draft                  AGTP-API                        May 2026


     The startup-vs-runtime split is a recommendation, not a strict
     requirement.  Servers *MAY* defer startup validation if their
     endpoint catalog is dynamic (e.g., a PROPOSE-driven server that only
     synthesizes endpoints on demand).  Such servers *MUST* still validate
     at the moment an endpoint is registered or synthesized, just not at
     process start.

  13.3.  Schema Strictness

     Schema validation is asymmetric between inputs and outputs.

     Input schemas *MUST* be validated with additionalProperties: false.
     Fields not declared in the schema *MUST* cause validation to fail
     with 422.  This catches typos and version mismatches early and
     prevents agents from sending unrecognized fields under the mistaken
     assumption that the server will silently ignore them.

     Output schemas *SHOULD* be validated with additionalProperties: true.
     A handler that returns more fields than the schema declared is
     forward-compatible: agents can ignore extra fields.  A handler that
     returns missing required fields fails validation either way.  Servers
     *MAY* opt into strict output validation as a deployment policy.

     This asymmetry is normative because it has interoperability
     consequences.  An agent submitting a request to two different servers
     can rely on both rejecting unrecognized input fields.  An agent
     consuming a response from two different servers can rely on forward-
     compatible field handling without the version of one server breaking
     integration with the other.

  13.4.  Conformance Test Suite

     The AGTP-API conformance test suite is maintained at:

     https://agtp.io/api/conformance

     The test suite exercises every conformance requirement in this
     section.  Servers claiming AGTP-API conformance *MUST* pass the test
     suite at the version they declare in their manifest's
     agtp_api_version field.











  Hood                    Expires 13 November 2026               [Page 42]


  Internet-Draft                  AGTP-API                        May 2026


  14.  Relationship to OpenAPI

     OpenAPI and AGTP-API perform similar work for different consumers.
     OpenAPI describes HTTP APIs for human developers and code generators.
     AGTP-API describes agent-grade endpoints for autonomous agents.  The
     two formats overlap substantially: both have method, path, request
     schema, response schema, errors, and descriptions.  AGTP-API does not
     compete with OpenAPI; the two formats are complementary, and AGTP-API
     deployments commonly interoperate with OpenAPI-described HTTP
     services in three distinct ways.

  14.1.  OpenAPI as an Authoring Source

     A developer with an existing OpenAPI specification can convert it to
     AGTP-API endpoint declarations.  The HTTP method maps to an AGTP verb
     (with translation: GET maps to QUERY or DISCOVER depending on intent;
     POST maps to EXECUTE, BOOK, PURCHASE, or another action verb
     depending on the operation).  The path remains.  The request schema
     becomes input_schema.  The response schema becomes output_schema.
     Errors become the errors list.  The OpenAPI description becomes the
     foundation of the semantic block's intent.

     Conversion tooling *MAY* automate this translation with reasonable
     defaults, flagging cases where verb mapping requires human judgment.
     The AGTP-API approved method catalog (Section 3) is the canonical
     source for HTTP-verb-to-AGTP-verb conversions: tooling *MUST* select
     target verbs from the list rather than inventing ad-hoc names, which
     is what makes converted endpoints interoperable with native AGTP-API
     endpoints.

     Servers *SHOULD NOT* treat machine-converted endpoints as
     authoritative until a human reviewer has confirmed the semantic block
     fields, particularly intent, outcome, and impact.  Conversion tooling
     has no reliable way to infer impact from HTTP semantics; that is
     judgment work.

  14.2.  OpenAPI as an Export Target

     AGTP servers *MAY* render their endpoint catalog as an OpenAPI
     document for HTTP consumers that do not yet speak AGTP.  The reverse
     translation: AGTP verb to HTTP method (mappings are imperfect; some
     AGTP verbs have no clean HTTP analog and are best exposed via the
     legacy verb compatibility mode of Section 3.6); path remains; schemas
     pass through unchanged.







  Hood                    Expires 13 November 2026               [Page 43]


  Internet-Draft                  AGTP-API                        May 2026


     The exported OpenAPI document is a compatibility surface, not the
     authoritative description of the service.  Servers exporting OpenAPI
     *SHOULD* mark the export as derived from the AGTP-API manifest and
     *SHOULD* publish a link to the manifest in the OpenAPI info section.

  14.3.  OpenAPI as a Coexistence Layer

     A server *MAY* run AGTP and HTTP side by side.  The AGTP endpoint's
     handler is the same code that the HTTP endpoint invokes.  OpenAPI
     documents the HTTP face; the AGTP-API manifest documents the agent
     face.  The handler does not know which protocol invoked it.  This
     deployment posture is signaled in the manifest by populating the apis
     array (Section 8) with descriptors pointing at the server's OpenAPI
     documents.

     Coexistence is the path most large organizations will take during
     transition: AGTP is added as a parallel face without requiring
     modification to existing HTTP infrastructure.  Implementation
     guidance for coexistence deployments is provided in Appendix A.

  15.  What AGTP-API Does Not Specify

     AGTP-API explicitly excludes the following operational concerns,
     which remain middleware territory:

     *  Rate limiting strategies and policies.

     *  Observability mechanisms (metrics, logs, traces).

     *  Caching strategies beyond manifest caching.

     *  Custom authentication beyond AGTP agent identity.

     *  Request and response transformation.

     *  Server deployment topology and scaling.

     *  HTTP middleware integration patterns.

     These are addressed by reference middleware repositories that ship
     separately and non-normatively.  The contract-plumbing distinction is
     intentional: the protocol governs contracts; middleware governs
     operations.

  16.  Security Considerations






  Hood                    Expires 13 November 2026               [Page 44]


  Internet-Draft                  AGTP-API                        May 2026


  16.1.  Verb-Path Tampering

     A malicious server could declare endpoints whose semantic blocks
     misrepresent the actual behavior.  Agents that rely on semantic
     blocks for authorization decisions *MUST* also enforce Authority-
     Scope checks against actual outcomes, not declared outcomes.

  16.2.  Synthesis Authority Preservation

     The synthesis evaluation step (step 5 in Section 10.3) *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 should not be permitted 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.

  16.3.  Method Policy Tampering

     The method policy is carried as the policies.methods sub-block of the
     server manifest and is covered by the manifest signature (Section 8)
     when present.  Agents that retrieve the manifest over AGTP transport
     (which mandates TLS 1.3 or higher per [AGTP]) and verify the manifest
     signature when present are protected against policy substitution.
     Agents that accept manifest content without signature verification
     are vulnerable to substitution of the method policy along with the
     rest of the manifest.

  16.4.  Wildcard Abuse

     The wildcards: true consent on the agent identity document and
     wildcards_accepted: true on the server policy are mutual consents
     that enable ad-hoc method invocation.  Agents *SHOULD NOT* declare
     wildcards: true by default; servers *SHOULD NOT* declare
     wildcards_accepted: true for any operation with non-trivial impact
     tier.  The 262 Authorization Required response with body type
     wildcards-required is the safe default.

  16.5.  Verb List Trust

     Agents trust the AGTP-API approved method catalog as published at
     https://agtp.io/api/methods.json.  The catalog *MUST* be served over
     HTTPS with content integrity verification.  Agents *MAY* pin the
     catalog version they have validated and refuse upgrades without
     explicit operator approval.






  Hood                    Expires 13 November 2026               [Page 45]


  Internet-Draft                  AGTP-API                        May 2026


  17.  IANA Considerations

     This document defines the following AGTP-API-specific allocations.
     The corresponding AGTP IANA registry entries are recorded in [AGTP]
     Section 9.

  17.1.  AGTP-API Status Code Assignments

     The following codes are registered in the AGTP Status Code Registry
     with AGTP-API as the authoritative reference:

     *  261 Negotiation In Progress

     *  262 Authorization Required

     *  263 Proposal Approved

     *  405 Method Not Allowed (AGTP-API semantics)

     *  459 Method Violation

     *  460 Endpoint Violation

     *  463 Proposal Rejected

  17.2.  Media Type Registrations

     This document defines two media types and requests their registration
     in the IANA Media Types registry.  Full registration templates are
     provided in the appendices.  The master registry of all AGTP-family
     media types is maintained in [AGTP].

        +========================+===================+===============+
        | Media Type             | Use               | IANA Status   |
        +========================+===================+===============+
        | application/           | AGTP server       | Planned (this |
        | vnd.agtp.manifest+json | manifest format   | document)     |
        +------------------------+-------------------+---------------+
        | application/           | AGTP-API endpoint | Planned (this |
        | vnd.agtp.endpoint+json | definition format | document)     |
        +------------------------+-------------------+---------------+

                   Table 3: Media Types Defined by AGTP-API

     application/vnd.agtp.manifest+json  The AGTP server manifest format.
        Carried on responses to a server-level DISCOVER request (DISCOVER
        without an Agent-ID header).  The registration application will be
        filed concurrent with publication of this document.



  Hood                    Expires 13 November 2026               [Page 46]


  Internet-Draft                  AGTP-API                        May 2026


     application/vnd.agtp.endpoint+json  The AGTP-API endpoint definition
        format.  Used in PROPOSE request bodies and in 263 Proposal
        Approved response bodies.  The registration application will be
        filed concurrent with publication of this document.

     Until the IANA registrations complete, the reference implementation
     *MAY* continue to emit application/json for manifest and endpoint
     responses.  Implementations are encouraged to emit the AGTP-specific
     types as soon as they are accepted by IANA so that content
     negotiation and MIME-based routing can distinguish AGTP traffic from
     generic JSON.

  17.3.  AGTP-API Method Catalog Reference

     This document does *NOT* request establishment of an IANA AGTP-API
     Verb List Registry.  As specified in Section 3.1, the verb list is
     intentionally maintained as an open living artifact at
     https://agtp.io/api/methods.json rather than as a closed IANA
     registry, so that the catalog can evolve at the cadence of agent
     deployment rather than the cadence of IETF process.  The structural
     status codes, the media types, and the response headers below are
     appropriate for IANA registration; the method catalog is not.

  17.4.  AGTP-API Response Headers

     This document requests registration of the following response headers
     in the IANA HTTP Field Name Registry (or equivalent AGTP-specific
     registry where applicable):

     AGTP-Catalog-Warning:  Advisory header surfaced on responses where
        the request method is deprecated in the catalog version the server
        is using.  Format and semantics specified in Section 4.

     AGTP-API-Version:  Header surfacing the AGTP-API specification
        version a manifest or endpoint definition conforms to.

  18.  Open Items

     The following items are explicitly out of scope for this revision and
     are anticipated in future revisions:

     *  Mandatory manifest signing. v00 specifies manifest_signature as
        *SHOULD*; a future revision will make it *MUST*. The signing
        algorithm, canonical encoding rules for JWS over the manifest
        body, key-publication mechanism, and rotation semantics will be
        specified separately in [AGTP-CERT].  Reference implementations
        are expected to ship signing support in alignment with that
        revision.



  Hood                    Expires 13 November 2026               [Page 47]


  Internet-Draft                  AGTP-API                        May 2026


     *  Cross-endpoint shared schema definitions. v00 requires schemas to
        be inline in each endpoint's input_schema and output_schema.  A
        future revision may add a schemas block to the manifest carrying
        named, reusable JSON Schema fragments referenceable by $ref from
        endpoint schemas.  This is a manifest-size and authoring-
        convenience concern; the wire-level contract is unchanged.

     *  Config-driven document_version.  The reference implementation
        hardcodes document_version to a single value; an operator workflow
        that bumps document_version on every meaningful manifest change is
        anticipated.  The wire contract permits any string; the operator
        workflow is implementation-specific.

     *  The full text of the initial method catalog (approximately 435
        methods). v00 references the published JSON at agtp.io/api/
        methods.json rather than embedding the catalog inline.  A future
        revision may include a curated subset as a non-normative appendix;
        the authoritative catalog remains the published JSON per
        Section 3.1.

     *  Detailed schema for the synthesis_log returned with 263 Proposal
        Approved, recording which underlying endpoints were composed.

     *  Federation model for multi-server synthesis (composing endpoints
        from different servers in a single synthesized endpoint).

     *  Multi-version concurrent catalog support. v00 specifies
        catalog_versions_supported as a list, but the runtime semantics
        for a server processing a request against a non-default catalog
        version are not specified.  Most servers list a single version.

     *  Conformance test suite specification (currently described by
        reference to the agtp.io implementation).

     *  Authentication passthrough for external_service handlers
        (forwarding agent identity to upstream services).  Out of scope by
        security default in v00; future revisions may specify opt-in
        passthrough patterns.

     *  Hot reload of recipes, endpoints, and policies.methods
        configuration without server restart.

     *  Wildcard opt-in implementation.  The spec defines the consent
        model (wildcards: true on the agent identity document and
        wildcards_accepted: true in server policy) and the 262
        Authorization Required response with body type wildcards-required
        for unsatisfied consent.  The default behavior in v00 is refuse:
        ad-hoc method invocations against undeclared endpoints are



  Hood                    Expires 13 November 2026               [Page 48]


  Internet-Draft                  AGTP-API                        May 2026


        rejected as 459 Method Violation when the method is not in the
        AGTP-API catalog, or as 405 Method Not Allowed when the method is
        in the catalog but no endpoint exists for the method-and-path
        combination.  The opt-in path that activates 262 with wildcards-
        required (when an agent or server has consented to wildcards but
        the other side has not) is anticipated as an implementation
        extension in a future revision.

  19.  Acknowledgments

     This document was developed in response to implementation experience
     with the AGTP v06 and v07 builds.  The architectural decision to
     unify the contract layer under a single companion specification was
     articulated in the AGTP-API Position Paper (May 2026).  The empirical
     evidence for the action-intent semantic class is documented in
     [HOOD2026].

  20.  References

  20.1.  Normative References

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

     [JSON-SCHEMA]
                Wright, A., Andrews, H., Hutton, B., and G. Dennis, "JSON
                Schema: A Media Type for Describing JSON Documents", Work
                in Progress, Internet-Draft, draft-bhutton-json-schema-01,
                2020, <https://datatracker.ietf.org/doc/html/draft-
                bhutton-json-schema-01>.

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

     [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
                Resource Identifier (URI): Generic Syntax", STD 66,
                RFC 3986, DOI 10.17487/RFC3986, January 2005,
                <https://www.rfc-editor.org/rfc/rfc3986>.

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





  Hood                    Expires 13 November 2026               [Page 49]


  Internet-Draft                  AGTP-API                        May 2026


     [RFC9110]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
                Ed., "HTTP Semantics", STD 97, RFC 9110,
                DOI 10.17487/RFC9110, June 2022,
                <https://www.rfc-editor.org/rfc/rfc9110>.

  20.2.  Informative References

     [AGTP-CERT]
                Hood, C., "AGTP Agent Certificate Extension", Work in
                Progress, Internet-Draft, draft-hood-agtp-agent-cert-00,
                2026, <https://datatracker.ietf.org/doc/html/draft-hood-
                agtp-agent-cert-00>.

     [AGTP-MERCHANT]
                Hood, C., "AGTP Merchant Identity and Agentic Commerce
                Binding", Work in Progress, Internet-Draft, draft-hood-
                agtp-merchant-identity-01, 2026,
                <https://datatracker.ietf.org/doc/html/draft-hood-agtp-
                merchant-identity-01>.

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

     [HOOD2026] Hood, C., "Semantic Method Naming and LLM Agent Accuracy:
                A Controlled Benchmark of REST/CRUD versus Agentive API
                Interface Design", Working Paper Available by request.
                March 2026., 2026.

     [RFC6570]  Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
                and D. Orchard, "URI Template", RFC 6570,
                DOI 10.17487/RFC6570, March 2012,
                <https://www.rfc-editor.org/rfc/rfc6570>.

  Appendix A.  Implementation Guidance (Informative)

     This appendix is non-normative.  It describes how a typical AGTP-API
     server is built and operated, in support of the normative spec.
     Implementations are not required to follow these patterns; they are
     documented here to give developers a starting point and to make the
     intended deployment posture concrete.

  A.1.  Endpoint Authoring

     A common pattern for endpoint authoring uses one declaration file per
     endpoint, dropped into a directory the server scans at startup:



  Hood                    Expires 13 November 2026               [Page 50]


  Internet-Draft                  AGTP-API                        May 2026


     *  A human-editable declaration format (such as TOML, YAML, or JSON)
        carries the endpoint's verb, path, semantic block, schemas,
        errors, and handler reference.

     *  A handler function in the server's implementation language carries
        the business logic, with a uniform signature that takes a context
        object and returns a structured response or named error.

     *  The server scans the endpoints directory at startup, validates
        every declaration per Section 13.2, imports the referenced handler
        modules, and registers the valid endpoints in memory.

     The reference Python implementation of an AGTP-API server uses TOML
     for endpoint declarations and a context → response | error handler
     signature.  The exact TOML schema and handler patterns are documented
     at:

     https://agtp.io/api/reference/authoring

     The TOML format is one serialization of the endpoint primitive
     defined normatively in Section 6.  Other implementations are free to
     use other serializations (YAML, JSON, programmatic registration,
     database-backed registries) provided the in-memory endpoint structure
     conforms to this specification.

  A.2.  Runtime Dispatch Pattern

     A typical request lifecycle in a conforming server:

     1.  The server receives an AGTP request and parses the verb and path.

     2.  The dispatcher matches verb-and-path against the endpoint
         registry.

     3.  On match, the dispatcher validates the request body against the
         endpoint's input_schema.

     4.  The dispatcher checks the agent's Authority-Scope against the
         endpoint's required_scopes declaration.

     5.  The dispatcher constructs a context object containing validated
         input and agent identity, and invokes the handler.

     6.  The handler executes business logic and returns a structured
         response or named error.

     7.  The dispatcher translates the result into an AGTP response.




  Hood                    Expires 13 November 2026               [Page 51]


  Internet-Draft                  AGTP-API                        May 2026


     This pattern keeps contract enforcement in the dispatcher and
     business logic in the handler.  Handlers do not perform schema
     validation, authority checks, or status code translation; the
     dispatcher does those uniformly across all endpoints.

  A.3.  Tooling

     The reference implementation publishes tooling at agtp.io/api/tools:

     *  An OpenAPI → AGTP-API conversion tool that reads an OpenAPI 3.x
        specification and produces a directory of endpoint declarations
        with external_service handlers pointing at the original HTTP
        endpoints.  Where method mapping requires judgment, the tool flags
        the endpoint for human review with suggestions from the AGTP-API
        approved method catalog.

     *  An AGTP-API → OpenAPI export tool for servers that need to publish
        HTTP-side documentation derived from their AGTP manifest.

     *  A manifest validator that checks server manifests against this
        specification.

     *  A conformance test runner that exercises the conformance
        requirements of Section 13.1 against a deployed server.

     *  An agtp-catalog-diff tool that diffs two catalog versions and
        optionally scans a deployment directory to identify endpoints,
        recipes, and policies.methods entries that would break under a
        candidate catalog upgrade.  See Section 4.

     These tools are non-normative reference implementations.  Other
     parties *MAY* publish equivalent tools.

  A.4.  Operator Notes on Catalog Versioning

     The catalog version a server declares in its manifest is the version
     the server validates incoming method names against.  Operators
     upgrading the on-disk verb catalog (typically by regenerating
     methods.json from a new catalog release) *SHOULD* restart the server
     to pick up the new version.  Long-running servers that have not been
     restarted after a catalog upgrade may continue validating against the
     previous version they loaded at startup.









  Hood                    Expires 13 November 2026               [Page 52]


  Internet-Draft                  AGTP-API                        May 2026


     The reference agtp-catalog-diff tool is the recommended way to
     preview the impact of a catalog upgrade against a deployment
     directory before restarting.  Run it as a deployment gate to surface
     endpoint-removal conflicts, recipe-step references to removed
     methods, and policies.methods entries that would be silently skipped
     under the new version.

  Appendix B.  Migration Paths (Informative)

     This appendix is non-normative.  It describes deployment strategies
     for organizations adopting AGTP-API on top of existing HTTP services,
     and for organizations building AGTP-API services from scratch.

  B.1.  Wrap-and-Expose

     The lowest-effort path for an organization with an existing HTTP API.
     The HTTP API stays where it is.  The organization writes AGTP-API
     endpoint declarations whose handler binding is external_service
     (Section 12.3), pointing at the existing HTTP endpoints.  AGTP-API
     becomes a thin agent-facing facade over the existing HTTP backend.
     Request translation maps AGTP-API input fields to HTTP request
     shapes; response translation maps HTTP responses back to AGTP-API
     output shapes.

     The OpenAPI → AGTP-API conversion tool (Appendix A) produces this
     kind of deployment by default: it reads an OpenAPI specification and
     generates a directory of endpoint declarations with external_service
     handlers.  A 200-endpoint HTTP service can be made AGTP-discoverable
     in a single working session.

     Wrap-and-expose deployments *SHOULD* populate the manifest's apis
     array (Section 8) with the HTTP API descriptor so agents that need
     the underlying HTTP documentation can locate it.

  B.2.  Translate-and-Rehost

     A medium-effort path.  The organization reimplements its HTTP API as
     native AGTP-API endpoints, moving the handler logic into the AGTP-API
     server's implementation language directly.  The HTTP layer goes away,
     or is retained only for legacy clients that have not migrated.

     The conversion tool generates endpoint declarations and handler stubs
     from the existing OpenAPI specification, leaving the organization to
     fill in the business logic.  The work is conversion, not greenfield
     development.






  Hood                    Expires 13 November 2026               [Page 53]


  Internet-Draft                  AGTP-API                        May 2026


     Translate-and-rehost deployments leave the apis array empty once the
     HTTP layer retires; during transition, the array continues to
     reference the HTTP face alongside the native AGTP endpoints.

  B.3.  Coexist-Permanently

     No migration.  The HTTP API stays as the primary interface; AGTP-API
     is added as a parallel face for agent traffic.  New agent-facing
     features go in the AGTP-API layer; existing HTTP traffic continues
     unaffected.  Two interfaces, one backend, indefinite coexistence.

     This is the path most large enterprises will take when regulatory,
     contractual, or customer-relationship commitments make a forced
     migration impractical.  AGTP-API is additive in this posture, not
     replacing.

     Coexist-permanently deployments populate apis with HTTP API
     descriptors that include http_documentation URLs pointing at the
     HTTP-side OpenAPI specifications.

  B.4.  Path Selection

     The right path depends on organizational constraints, not protocol
     preferences.  Wrap-and-expose is the path that scales: it is the one
     that can move millions of existing APIs to AGTP-API discoverability
     at low cost.  Translate-and-rehost is the right target for
     organizations committing to AGTP-API as the long-term primary
     surface.  Coexist-permanently is the honest answer for organizations
     that want agent access without disruption to existing systems.

  Author's Address

     Chris Hood
     Nomotic, Inc.
     Email: chris@nomotic.ai
     URI:   https://agtp.io















  Hood                    Expires 13 November 2026               [Page 54]


name: draft-borthwick-msebenzi-environment-state
rev: 00
title: Verifiable Intent -- environment.* Constraint Family
time: 2026-05-12T19:56:59Z
group_uri: /api/v1/group/group/1027/
expires: 2026-11-13T19:56:59Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["A2A protocols", "Agent identity/auth", "Data formats/interop"]
tags: []
fetched_at: 2026-05-22T09:24:50.092736+00:00
source: ietf
abstract:
  The Verifiable Intent (VI) mandate format authorises autonomous
     agents to act on behalf of human principals through cryptographically
     signed constraint instances bound into Layer 2 mandates.  VI's
     existing constraint families describe properties of the transaction
     itself — what is being purchased, by whom, for how much, against
     which credential.  They do not describe properties of the environment
     in which the transaction is executed: whether the venue is open,
     whether the source of funds is funded, whether other relevant
     external conditions hold at the moment of execution.

     This document specifies the environment.* constraint family for the
     Verifiable Intent mandate vocabulary.  It defines the membership
     criterion under which a constraint type qualifies as a member of the
     family, the family-wide vocabulary every member uses, the composition
     discipline by which family members compose with each other and with
     constraints from other families, the register discipline under which
     family-wide and per-type prose is written, the family-wide security
     considerations, and the IANA registry mechanics under which new
     family members are registered.  It does not define any individual
     constraint type.  Two reference type specifications
     (environment.market_state and environment.wallet_state) are
     referenced informatively in Appendix A.

full_text:
  Independent Submission                                      D. Borthwick
  Internet-Draft                                                InsumerAPI
  Intended status: Informational                               M. Msebenzi
  Expires: 12 November 2026                                Headless Oracle
                                                               11 May 2026


            Verifiable Intent — environment.* Constraint Family
               draft-borthwick-msebenzi-environment-state-00

  Abstract

     The Verifiable Intent (VI) mandate format authorises autonomous
     agents to act on behalf of human principals through cryptographically
     signed constraint instances bound into Layer 2 mandates.  VI's
     existing constraint families describe properties of the transaction
     itself — what is being purchased, by whom, for how much, against
     which credential.  They do not describe properties of the environment
     in which the transaction is executed: whether the venue is open,
     whether the source of funds is funded, whether other relevant
     external conditions hold at the moment of execution.

     This document specifies the environment.* constraint family for the
     Verifiable Intent mandate vocabulary.  It defines the membership
     criterion under which a constraint type qualifies as a member of the
     family, the family-wide vocabulary every member uses, the composition
     discipline by which family members compose with each other and with
     constraints from other families, the register discipline under which
     family-wide and per-type prose is written, the family-wide security
     considerations, and the IANA registry mechanics under which new
     family members are registered.  It does not define any individual
     constraint type.  Two reference type specifications
     (environment.market_state and environment.wallet_state) are
     referenced informatively in Appendix A.

  Status of This Memo

     This Internet-Draft is submitted in full conformance with the
     provisions of BCP 78 and BCP 79.

     Internet-Drafts are working documents of the Internet Engineering
     Task Force (IETF).  Note that other groups may also distribute
     working documents as Internet-Drafts.  The list of current Internet-
     Drafts is at https://datatracker.ietf.org/drafts/current/.







  Borthwick & Msebenzi    Expires 12 November 2026                [Page 1]


  Internet-Draft                environment.*                     May 2026


     Internet-Drafts are draft documents valid for a maximum of six months
     and may be updated, replaced, or obsoleted by other documents at any
     time.  It is inappropriate to use Internet-Drafts as reference
     material or to cite them other than as "work in progress."

     This Internet-Draft will expire on 12 November 2026.

  Copyright Notice

     Copyright (c) 2026 IETF Trust and the persons identified as the
     document authors.  All rights reserved.

     This document is subject to BCP 78 and the IETF Trust's Legal
     Provisions Relating to IETF Documents (https://trustee.ietf.org/
     license-info) in effect on the date of publication of this document.
     Please review these documents carefully, as they describe your rights
     and restrictions with respect to this document.

  Table of Contents

     1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
       1.1.  Motivation  . . . . . . . . . . . . . . . . . . . . . . .   4
       1.2.  Scope . . . . . . . . . . . . . . . . . . . . . . . . . .   5
       1.3.  Relationship to Verifiable Intent . . . . . . . . . . . .   6
       1.4.  Document Organisation . . . . . . . . . . . . . . . . . .   7
     2.  Terminology and References  . . . . . . . . . . . . . . . . .   7
       2.1.  Conventions and Definitions . . . . . . . . . . . . . . .   7
       2.2.  Terms . . . . . . . . . . . . . . . . . . . . . . . . . .   8
       2.3.  References  . . . . . . . . . . . . . . . . . . . . . . .  10
         2.3.1.  Normative References  . . . . . . . . . . . . . . . .  10
         2.3.2.  Informative References  . . . . . . . . . . . . . . .  10
     3.  The environment.* Constraint Family . . . . . . . . . . . . .  11
       3.1.  Family Definition . . . . . . . . . . . . . . . . . . . .  11
       3.2.  Membership Criterion  . . . . . . . . . . . . . . . . . .  11
       3.3.  Namespace . . . . . . . . . . . . . . . . . . . . . . . .  12
       3.4.  Adding New Family Members . . . . . . . . . . . . . . . .  13
       3.5.  Handling of Weakened Type Specifications  . . . . . . . .  14
       3.6.  Relationship to Other Constraint Families . . . . . . . .  14
     4.  Family-Wide Vocabulary  . . . . . . . . . . . . . . . . . . .  15
       4.1.  Family-Wide Fields  . . . . . . . . . . . . . . . . . . .  16
         4.1.1.  attestation_url . . . . . . . . . . . . . . . . . . .  16
         4.1.2.  max_attestation_age . . . . . . . . . . . . . . . . .  16
       4.2.  Field-Scope Taxonomy  . . . . . . . . . . . . . . . . . .  17
         4.2.1.  Scope Declarations for Family-Wide Fields . . . . . .  18
         4.2.2.  Scope Declarations for Per-Type Fields  . . . . . . .  18
         4.2.3.  Adding Scope Categories . . . . . . . . . . . . . . .  19
       4.3.  Algorithm Agility . . . . . . . . . . . . . . . . . . . .  19
     5.  Family Composition  . . . . . . . . . . . . . . . . . . . . .  20



  Borthwick & Msebenzi    Expires 12 November 2026                [Page 2]


  Internet-Draft                environment.*                     May 2026


       5.1.  Conjunction Semantics . . . . . . . . . . . . . . . . . .  20
       5.2.  Mixed Pass/Fail . . . . . . . . . . . . . . . . . . . . .  21
       5.3.  L3 Execution Gate and Completeness  . . . . . . . . . . .  21
       5.4.  Per-Member Diagnostic Output  . . . . . . . . . . . . . .  22
       5.5.  Composition with Other Families . . . . . . . . . . . . .  23
       5.6.  Rationale . . . . . . . . . . . . . . . . . . . . . . . .  23
     6.  Register Discipline . . . . . . . . . . . . . . . . . . . . .  24
       6.1.  Normative Register  . . . . . . . . . . . . . . . . . . .  25
       6.2.  Descriptive Register  . . . . . . . . . . . . . . . . . .  25
       6.3.  Redundancy Avoidance  . . . . . . . . . . . . . . . . . .  26
       6.4.  Scope of Application  . . . . . . . . . . . . . . . . . .  26
       6.5.  Forward Rule for New Sections and New Specifications  . .  27
       6.6.  Relationship to Section 2.1 Conventions . . . . . . . . .  27
       6.7.  Open Questions  . . . . . . . . . . . . . . . . . . . . .  27
     7.  Security Considerations . . . . . . . . . . . . . . . . . . .  28
       7.1.  Attestation Replay  . . . . . . . . . . . . . . . . . . .  28
       7.2.  Issuer Trust Bootstrapping  . . . . . . . . . . . . . . .  29
       7.3.  Constraint Stripping and Insertion  . . . . . . . . . . .  30
       7.4.  Substitution of Attestation Endpoints . . . . . . . . . .  30
       7.5.  Mandate-Issuer-Versus-Attestation-Issuer Trust
             Separation  . . . . . . . . . . . . . . . . . . . . . . .  31
       7.6.  Time Synchronisation  . . . . . . . . . . . . . . . . . .  32
       7.7.  SSRF and Other Verifier-Initiated Fetch Risks . . . . . .  32
       7.8.  Signer Failure Handling . . . . . . . . . . . . . . . . .  33
     8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  34
       8.1.  The environment.* Namespace . . . . . . . . . . . . . . .  35
       8.2.  The environment.* Constraint Type Registry  . . . . . . .  35
       8.3.  Expert Review Criteria  . . . . . . . . . . . . . . . . .  36
       8.4.  Status Field Lifecycle  . . . . . . . . . . . . . . . . .  37
       8.5.  Updates to This Document  . . . . . . . . . . . . . . . .  38
     9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  38
       9.1.  Normative References  . . . . . . . . . . . . . . . . . .  39
       9.2.  Informative References  . . . . . . . . . . . . . . . . .  39
     Appendix A.  Reference Type Specifications  . . . . . . . . . . .  40
       A.1.  environment.market_state  . . . . . . . . . . . . . . . .  41
       A.2.  environment.wallet_state  . . . . . . . . . . . . . . . .  41
       A.3.  Disclaimer  . . . . . . . . . . . . . . . . . . . . . . .  42
     Appendix B.  Reserved . . . . . . . . . . . . . . . . . . . . . .  42
     Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  42
     Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  42











  Borthwick & Msebenzi    Expires 12 November 2026                [Page 3]


  Internet-Draft                environment.*                     May 2026


  1.  Introduction

     Autonomous agents executing financial transactions on behalf of human
     principals require cryptographic awareness of external state at the
     moment of execution.  This requirement exists independently of the
     constraints that authorize what the agent may do.  An agent holding a
     valid mandate to purchase a specific asset for a specific amount must
     additionally know, at execution time, whether the venue at which it
     intends to execute is open and whether the source of funds it intends
     to draw from still satisfies the conditions under which the mandate
     was issued.  Neither question is answered by the mandate itself.
     Both must be answered, with cryptographic evidence, before execution
     proceeds.

     This document defines a constraint family — environment.* — for the
     Verifiable Intent (VI) mandate vocabulary that addresses this class
     of requirement.  It does not specify any individual constraint type
     in detail.  Instead, it defines the membership criterion under which
     a constraint type qualifies as a member of the environment.* family,
     the vocabulary by which family members compose with each other and
     with constraints from other families, and the discipline under which
     new family members may be added by future revisions or by independent
     implementations.

  1.1.  Motivation

     The Verifiable Intent specification [VI-CONSTRAINTS] defines mandate
     constraints under a single transactional namespace, mandate.*, with
     two sub-namespaces: mandate.checkout.* declares what the agent may
     purchase (allowed merchants, line items), and mandate.payment.*
     declares how the agent may settle (allowed payees, amount ranges,
     budgets, recurrence, payment-mandate reference).  These transactional
     constraint families are sufficient to authorize an agent's intended
     action and to bind that authorization cryptographically to a
     credential the agent presents at the moment of execution.
















  Borthwick & Msebenzi    Expires 12 November 2026                [Page 4]


  Internet-Draft                environment.*                     May 2026


     They are not sufficient to bind the agent's action to the state of
     the world at the moment of execution.  An agent can present a valid
     mandate to purchase shares of a security listed on a venue that is
     currently halted; the mandate is cryptographically valid and the
     action is unauthorized in the real world.  An agent can present a
     valid mandate to settle a payment in a stablecoin from a wallet that
     no longer holds sufficient balance; the mandate is cryptographically
     valid and the settlement will fail or, worse, succeed against an
     unintended source.  These failure modes are not exotic edge cases.
     They are the autonomous-execution analog of well-documented races in
     financial markets and on-chain settlement, including market-execution
     events such as the 2010 Flash Crash and circuit-breaker session-
     boundary races, and on-chain TOCTOU exploits in the flash-loan-
     enabled class.

     Existing transactional constraint families cannot close this gap
     because they describe properties of the transaction — what is being
     done, by whom, for how much, against what credential.  The gap
     concerns properties of the environment in which the transaction is
     executed — whether the venue is open, whether the source is funded,
     and, by extension, whether other relevant conditions of the world
     hold at execution time.  These properties are not under the control
     of any party to the transaction and cannot be asserted by the agent.
     They must be observed and signed by an entity outside the transaction
     whose identity and signing key are bound into the mandate at issuance
     time.

     A constraint family is therefore the right primitive: each member
     type targets a specific environmental property, signed by an external
     attester, and verified at execution time before the transactional
     constraints are evaluated.  This document defines the family.
     Specific member types are defined in their own specifications;
     reference implementations are cited in Appendix A.

  1.2.  Scope

     This document defines:

     (1) the membership criterion under which a constraint type qualifies
     as a member of the environment.* family;

     (2) the vocabulary used by family members, including required and
     optional fields whose semantics are family-wide;

     (3) the composition discipline by which family members compose with
     each other and with constraints from other families;





  Borthwick & Msebenzi    Expires 12 November 2026                [Page 5]


  Internet-Draft                environment.*                     May 2026


     (4) the register discipline (RFC 2119 keyword usage, normative versus
     informative material) under which family-wide and per-type prose is
     written.

     This document does not define:

     (1) any individual environment.* constraint type.  Two reference type
     specifications (environment.market_state and
     environment.wallet_state) are documented in their own working-group
     submissions and are referenced informatively in Appendix A;

     (2) any algorithm for canonicalising signed attestation payloads.
     Per-type canonicalisation is the responsibility of each type
     specification;

     (3) any specific signing algorithm.  Algorithm agility is family-
     wide; per-type MUST-implement declarations are made by each type
     specification;

     (4) any specific attestation issuer, attestation endpoint, or
     operational detail of any reference implementation;

     (5) any change to the transactional constraint families (mandate.*)
     defined in [VI-CONSTRAINTS].  Family composition is the only surface
     at which environment.* interacts with transactional constraints, and
     this composition is unidirectional: environment.* constraints gate
     execution; transactional constraints are evaluated after
     environment.* constraints have passed.

     The deliberate narrowness of this scope reflects the family's design
     discipline: the document is the contract under which independent type
     authors and implementers can extend the family without coordinating
     with each other or with the authors of this document, provided they
     satisfy the membership criterion and respect the family-wide
     vocabulary and composition rules.

  1.3.  Relationship to Verifiable Intent

     This document is a vocabulary specification for the Verifiable Intent
     mandate format.  It does not modify the Verifiable Intent
     specification itself.  It declares a constraint-family namespace
     (environment.*) and the rules under which constraint types within
     that namespace operate, in the same manner that any extension of an
     existing vocabulary declares its own namespace and rules without
     modifying the host vocabulary's grammar.






  Borthwick & Msebenzi    Expires 12 November 2026                [Page 6]


  Internet-Draft                environment.*                     May 2026


     An open mandate, as used in this document and in
     [VI-CREDENTIAL-FORMAT], Section 4.5, is a Layer 2 mandate carrying
     constraints rather than final values, identified by a vct value with
     the .open suffix. environment.* constraints appear only in open
     mandates.

     VI mandate validators that do not recognize the environment.*
     namespace MUST reject open mandates containing environment.*
     constraints, per [VI-CONSTRAINTS], Section 5.4: open mandates with
     unknown constraint types fail closed regardless of strictness mode,
     because an unevaluable constraint in an open mandate leaves agent
     authority unbounded.  Because environment.* constraints appear only
     in open mandates, the rejection rule applies uniformly to every
     mandate in which environment.* constraints can appear.

     Validators implementing this document MUST evaluate environment.*
     constraints in the order specified in Section 5 and MUST treat any
     failure as terminal for the mandate.

  1.4.  Document Organisation

     Section 2 establishes terminology and references.  Section 3 defines
     the constraint family and its membership criterion.  Section 4
     specifies family-wide vocabulary including the fields that appear,
     with identical semantics, on every member type, the field-scope
     taxonomy under which fields are classified, and the algorithm-agility
     framework under which signing-algorithm choice is made.  Section 5
     specifies family composition: conjunction semantics across family
     members, the L3 execution gate and its completeness rule, per-member
     diagnostic output, and the membership-criterion rationale these rules
     collectively encode.  Section 6 specifies register discipline.
     Section 7 covers Security Considerations specific to family-wide
     concerns.  Section 8 covers IANA Considerations including the
     proposed environment.* namespace registry.  Appendix A documents the
     relationship between this specification and the two existing
     reference type specifications.  Appendix B is reserved for future
     family-charter material per Section 6.7 Q3.

  2.  Terminology and References

  2.1.  Conventions and Definitions

     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
     "SHOULD", "SHOULD NOT", "RECOMMENDED", "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.




  Borthwick & Msebenzi    Expires 12 November 2026                [Page 7]


  Internet-Draft                environment.*                     May 2026


     This document distinguishes between normative register and
     descriptive register, per the discipline catalogued at Section 6.
     Normative register uses RFC 2119 keywords in all capitals to bind
     implementers to specific behaviour.  Descriptive register uses
     lowercase synonyms (or explicit non-keyword phrasing) when the prose
     explains intent, rationale, or context rather than imposing a
     requirement.  The distinction is not stylistic; it determines what is
     conformance-checkable.

  2.2.  Terms

     The following terms are defined for use in this document and in any
     specification of an environment.* constraint type that claims
     membership in the family.

     Constraint family.  A set of constraint types that share a common
     membership criterion, a common composition discipline, and a common
     family-wide vocabulary.  The environment.* family is the family this
     document defines.  The mandate.checkout.* and mandate.payment.*
     groupings within [VI-CONSTRAINTS] are not constraint families in the
     sense of this document; they are sub-namespaces of the transactional
     constraint vocabulary that share a prefix but do not share a
     membership criterion.

     Membership criterion.  A property that a constraint type MUST satisfy
     to qualify as a member of a constraint family.  Membership in the
     environment.* family requires that the constraint type's failure mode
     be gating: a failure of the constraint MUST terminate execution
     rather than degrade gracefully.  Section 3 specifies the criterion in
     normative detail.

     Transactional constraint.  A constraint that describes a property of
     the transaction itself — what is being purchased, by whom, for how
     much, against which credential.  The constraint families
     mandate.checkout.* and mandate.payment.* defined in [VI-CONSTRAINTS]
     are transactional.  Transactional constraints are evaluated against
     fulfillment values derived from Layer 3 mandates.  They do not
     require any external state observation at evaluation time.

     Environmental constraint.  A constraint that describes a property of
     the environment in which the transaction is executed — whether a
     venue is open, whether a wallet is funded, whether other relevant
     external conditions hold.  Environmental constraints are evaluated
     against external state observations attested by an entity outside the
     transaction.  The environment.* family is the set of environmental
     constraint types that satisfy the membership criterion of this
     document.




  Borthwick & Msebenzi    Expires 12 November 2026                [Page 8]


  Internet-Draft                environment.*                     May 2026


     Attestation.  A signed statement, issued by an entity outside the
     transaction, asserting that a specified environmental property held
     at a specified time.  Attestations carry a binding to a subject
     (whose property is described), a binding to an issuer (whose key
     signed the statement), a freshness window (within which the
     attestation is acceptable), and an evaluation result (the property
     held or did not hold).  The wire format and signing algorithm of an
     attestation are per-type concerns, specified by each constraint type.
     The role of the attestation in the verification path is family-wide
     and is specified by this document.

     Issuer.  The entity that produces an attestation by observing
     external state and signing the result.  Each constraint type
     specification names the trust-root mechanism by which a verifier
     discovers an issuer's signing key (for example, [RFC7517] JWKS or
     [RFC8615] well-known key registry).  The mandate-level binding to a
     specific issuer's signing key is enforced by the constraint instance,
     not by the family.

     Mandate issuer.  The party that constructs the Layer 2 mandate
     carrying environment.* constraints.  The mandate issuer selects the
     constraint instances, populates per-instance fields (including the
     trust-root binding to a specific attestation issuer), and signs the
     mandate per [VI-CREDENTIAL-FORMAT].  The mandate issuer and the
     attestation issuer are distinct roles; an entity MAY occupy both
     roles in a deployment but the security analysis treats them
     separately.

     Verifier.  The party that evaluates an environment.* constraint at
     the moment of execution.  A verifier fetches a fresh attestation per
     the constraint's binding, verifies the attestation signature against
     the issuer's published key, applies the family-wide vocabulary checks
     specified in Section 4 (including freshness against the constraint's
     max_attestation_age), and applies the per-type checks specified by
     the constraint type's specification.  A verifier MUST NOT accept an
     agent's claim of constraint satisfaction in place of independent
     verification.

     Agent.  The autonomous principal that constructs Layer 3 mandates
     under the authority delegated by a Layer 2 mandate.  In the family's
     evaluation path, an agent is a pre-Layer-3 verifier: it MUST itself
     satisfy every environment.* constraint before constructing Layer 3,
     with the agent-side discipline specified in Section 5.








  Borthwick & Msebenzi    Expires 12 November 2026                [Page 9]


  Internet-Draft                environment.*                     May 2026


     Type specification author.  The party that drafts and submits a
     constraint type specification proposing membership in the
     environment.* family.  The type specification author is bound by the
     requirements of Section 3.4 and Section 4.2.2 governing how new types
     are specified.

     Layer 2, Layer 3.  Credential layers as defined in
     [VI-CREDENTIAL-FORMAT].  Layer 2 carries the user-signed mandate that
     includes constraint instances; Layer 3 carries the agent-signed
     fulfillment that the verifier accepts or rejects against the
     constraint instances.  The terms are used in this document only to
     identify the points in the credential lifecycle at which family rules
     apply; this document does not modify the layer definitions.

     Open mandate.  A Layer 2 mandate carrying constraints rather than
     final values, identified by a vct value with the .open suffix per
     [VI-CREDENTIAL-FORMAT], Section 4.5. environment.* constraints appear
     only in open mandates.  The unknown-constraint rejection rule of
     [VI-CONSTRAINTS], Section 5.4 applies uniformly to every mandate in
     which environment.* constraints can appear.

     Family-wide field.  A field whose semantics are identical across
     every constraint type in the family, independent of trust-root or
     evaluation mechanism.  Family-wide fields are specified in this
     document.

     Per-type field.  A field whose semantics depend on the constraint
     type's trust-root mechanism or evaluation mechanism.  Per-type fields
     are specified by each constraint type's specification under the
     field-scope taxonomy of Section 4.

  2.3.  References

     Citations in this section are short forms; the canonical reference
     list is in Section 9.

  2.3.1.  Normative References

     [RFC2119], [RFC8174], [RFC8126], [VI-CONSTRAINTS],
     [VI-CREDENTIAL-FORMAT].

  2.3.2.  Informative References

     [RFC1918], [RFC7517], [RFC7646], [RFC7800], [RFC8615], [RFC8725],
     [RFC8914], [RFC9421], [RFC6982], [RFC-SD-JWT],
     [ENVIRONMENT-MARKET-STATE], [ENVIRONMENT-WALLET-STATE].





  Borthwick & Msebenzi    Expires 12 November 2026               [Page 10]


  Internet-Draft                environment.*                     May 2026


  3.  The environment.* Constraint Family

     This section defines the environment.* constraint family.  It
     specifies the membership criterion under which a constraint type
     qualifies as a member of the family, the namespace under which family
     members are named, and the discipline under which new family members
     may be added.

  3.1.  Family Definition

     The environment.* constraint family is the set of Verifiable Intent
     constraint types that:

     (1) declare a property of the environment in which a transaction is
     executed, rather than a property of the transaction itself;

     (2) are evaluated against an attestation produced by an entity
     outside the transaction, rather than against fulfillment values
     derived from a Layer 3 mandate;

     (3) gate execution unconditionally on the result of that attestation;
     and

     (4) are named under the environment.* namespace.

     Constraint types satisfying these four properties MAY claim
     membership in the family by publishing a constraint type
     specification that conforms to this document.  Constraint types that
     satisfy fewer than all four properties are not members of the family,
     regardless of how their type identifier is named.

  3.2.  Membership Criterion

     The membership criterion of the environment.* family is that the
     constraint type's failure mode MUST be gating.  A constraint type's
     failure mode is gating if and only if every defined failure path of
     the type's verification algorithm produces termination of execution
     rather than partial fulfillment, retry, or graceful degradation.













  Borthwick & Msebenzi    Expires 12 November 2026               [Page 11]


  Internet-Draft                environment.*                     May 2026


     A constraint type whose failure mode is OR-tolerable — that is, a
     type whose failure can be survived by composition with other passing
     constraints, or whose failure leads to a permitted reduced-
     functionality execution path — is by definition outside this family.
     The reasoning is structural: a constraint that does not gate
     execution is not load-bearing for execution safety, and a constraint
     that is not load-bearing for execution safety does not require the
     family-wide vocabulary, composition discipline, or trust-root
     machinery this document specifies.  Such a constraint may belong to
     some other family, or to no family at all, but it does not belong
     here.

     The membership criterion is not a per-type design choice that the
     type specification author makes when proposing a new type.  It is a
     property the type specification author MUST establish before
     proposing the type for the family.  A proposed type whose failure
     mode is not demonstrably gating MUST be rejected from the family on
     this ground alone.

  3.3.  Namespace

     Family members are named under the environment.* namespace, using the
     dot-notation pattern of [VI-CONSTRAINTS].  The first component of the
     type identifier is the literal string environment; the second
     component identifies the specific environmental property the type
     addresses; further components MAY be used by future revisions for
     sub-classification.

     The environment.* namespace is registered for this purpose by
     Section 8 (IANA Considerations).  Names within the namespace SHOULD
     be chosen to identify the environmental property addressed (for
     example, market_state, wallet_state, regulatory_status) rather than
     the implementation, the issuer, or the wire format.

     IANA MUST NOT register a type identifier within the environment.*
     namespace that does not satisfy the membership criterion of
     Section 3.2.  The namespace and the criterion are coupled by design:
     a registered type within environment.* is, by registration, a member
     of the family in good standing, and a verifier encountering an
     environment.* identifier MAY rely on the family's discipline holding
     for that type.  Permitting the namespace to contain types that do not
     satisfy the criterion would defeat this property and is non-
     conforming.








  Borthwick & Msebenzi    Expires 12 November 2026               [Page 12]


  Internet-Draft                environment.*                     May 2026


  3.4.  Adding New Family Members

     A new constraint type MAY be proposed for the environment.* family by
     a type specification author publishing a constraint type
     specification that:

     (1) demonstrates that the proposed type satisfies the membership
     criterion of Section 3.2;

     (2) specifies a trust-root mechanism (for example, [RFC7517] JWKS,
     [RFC8615] well-known key registry, or another mechanism with
     comparable security properties — meaning a mechanism that provides
     cryptographically authenticated key discovery, supports key rotation,
     and binds the discovered key to a specific issuer identity) under
     which a verifier discovers the issuer's signing key;

     (3) specifies a verification algorithm that consumes attestations
     produced under the trust-root mechanism and produces either
     constraint-satisfied or constraint-violated as terminal states, with
     no other terminal states;

     (4) declares the per-type fields the type adds to the family-wide
     vocabulary, classifying each under the field-scope taxonomy of
     Section 4.2;

     (5) declares the per-type MUST-implement signing algorithm and the
     per-type SHOULD/MAY extension set under the algorithm-agility
     framework of Section 4.3;

     (6) declares the per-type distinguishing field used for per-member
     diagnostic disambiguation under the family composition discipline of
     Section 5.4, with a fallback specified for cases where the
     distinguishing field is not present in a failing instance; and

     (7) conforms to the register discipline of Section 6 throughout.

     These seven requirements correspond to the Expert Review criteria
     specified in Section 8.3 for IANA registry purposes.  A constraint
     type specification meeting all seven requirements is conforming.  A
     specification missing any requirement is not conforming and the
     proposed type MUST NOT be registered until the gap is closed.

     The relationship among Section 3.1, Section 3.2, and this section is
     as follows.  Section 3.1 specifies the four properties that
     characterise a family member.  Section 3.2 names the gating-failure-
     mode property — property (3) of Section 3.1 — as the membership
     criterion.  This section's seven requirements establish the
     operational obligations a type specification must satisfy to



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 13]


  Internet-Draft                environment.*                     May 2026


     demonstrate the four properties: requirement (1) demonstrates
     property (3) of Section 3.1 directly; requirements (2) and (3)
     establish the operational basis for property (2) (attestation-driven
     evaluation); requirements (4) through (7) establish the family-wide
     vocabulary, composition, and register obligations a member type must
     respect.  Property (1) of Section 3.1 (environmental, not
     transactional) and property (4) (named under the environment.*
     namespace) are pre-conditions that the type specification author
     asserts before invoking the seven requirements.  Together, Sections
     3.1, 3.2, and 3.4 specify the same family membership relation from
     descriptive, normative, and operational viewpoints respectively.

     This document does not prescribe the working-group process under
     which a conforming specification is reviewed and registered; that
     process is the responsibility of the standards body owning the
     environment.* registry.  This document specifies only the technical
     conditions a specification MUST meet to be eligible for registration.

  3.5.  Handling of Weakened Type Specifications

     A registered family member's specification may be revised over its
     lifetime.  If a revision weakens the type's failure mode below
     gating, the type's specification no longer satisfies the membership
     criterion of Section 3.2, even though the type's registration in the
     environment.* registry still asserts membership.  This is a
     contradiction between registry state and specification content that
     this document does not resolve directly; resolution is a working-
     group concern, typically through deprecation per Section 8.4 followed
     by registration of a successor type.

     Implementations MUST NOT silently accept the weakened semantics.  If
     an implementation determines that a registered type's current
     specification no longer satisfies the membership criterion, the
     implementation MUST reject mandates containing instances of that type
     and SHOULD report the contradiction to the working group rather than
     continue verification under the weakened specification.  The MUST is
     the family's fail-closed posture; the SHOULD is on discoverability of
     the contradiction by the registry's governance body.

  3.6.  Relationship to Other Constraint Families

     The environment.* family is one constraint family among potentially
     many in the Verifiable Intent ecosystem.  The mandate.checkout.* and
     mandate.payment.* groupings defined by [VI-CONSTRAINTS] are sub-
     namespaces of the transactional constraint vocabulary; they are not
     constraint families in the sense of this document because they do not
     share a single membership criterion across their members.  A future
     specification MAY define additional constraint families under the



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 14]


  Internet-Draft                environment.*                     May 2026


     same family-definition discipline this document establishes, with
     their own namespaces, membership criteria, and per-family
     vocabularies.

     Composition of environment.* constraints with constraints from other
     families is specified in Section 5.  The family relationship is
     unidirectional: environment.* constraints gate execution and are
     evaluated before transactional constraints; transactional constraints
     do not gate environment.* evaluation.  This ordering is normative
     regardless of whether other families are defined in the future.

     Constraint frameworks that bind agent authority to credential layers
     via Selective Disclosure JWT [RFC-SD-JWT] or HTTP Message Signatures
     [RFC9421], including Verifiable Intent's Layer 2 mandate format and
     similar agent-authorization protocols, are interoperable with the
     environment.* family without modification to either side.  An
     environment.* constraint instance, embedded in the Layer 2 mandate's
     constraint list and covered by the mandate's JWS signature, inherits
     the mandate's [RFC7800] cnf-claim binding to the agent's proof-of-
     possession key.  The verifier's evaluation path under Section 5.5
     (environment.* before transactional constraints) sequences correctly
     with the host framework's own Layer-2-to-Layer-3 verification path:
     environment.* constraints gate the entire mandate evaluation,
     including any transactional constraints the host framework specifies.
     No registration of environment.* identifiers in the host framework's
     constraint registry is required for this interoperability;
     recognition of the environment.* namespace is sufficient for a host
     framework's verifier to delegate evaluation to an environment.*-aware
     verification path.  Per [VI-CONSTRAINTS], Section 5.4 and Section 1.3
     of this document, host frameworks whose validators encounter
     environment.* constraint instances without recognizing the namespace
     will reject the containing open mandates.  This rejection is
     automatic; environment.*-aware verification paths operate against
     open mandates that the host-framework validator does recognize,
     without requiring host-framework registration of the environment.*
     namespace as a precondition.

  4.  Family-Wide Vocabulary

     This section specifies the vocabulary that all environment.*
     constraint types share.  Three classes of vocabulary are family-wide:

     (1) fields whose semantics are identical across every member type,
     specified in Section 4.1;

     (2) the field-scope taxonomy under which fields are classified as
     family-wide or per-type, specified in Section 4.2;




  Borthwick & Msebenzi    Expires 12 November 2026               [Page 15]


  Internet-Draft                environment.*                     May 2026


     (3) the algorithm-agility framework under which signing-algorithm
     choice is made, specified in Section 4.3.

     Per-type vocabulary — fields, signing algorithms, evaluation outputs,
     distinguishing identifiers — is specified by each constraint type's
     specification under the framework this section establishes.  This
     section does not specify per-type vocabulary.

  4.1.  Family-Wide Fields

     The following fields appear, with identical semantics, on every
     environment.* constraint instance.

  4.1.1.  attestation_url

     Type: string (HTTPS URL).  Required: Yes.

     The HTTPS endpoint at which the verifier fetches the signed
     attestation for this constraint instance.  The semantic role of
     attestation_url is identical across every environment.* constraint
     type: it names the location at which a fresh attestation can be
     obtained.  Per-type variance in the wire protocol (HTTP method,
     request body shape, response envelope) is carried by per-type fields
     and per-type interface specifications under Section 4.2.3, not by
     attestation_url.

     Verifiers MUST reject constraint instances whose attestation_url does
     not use the https scheme.  This rejection is fail-closed: an
     attestation fetched over an unencrypted channel is by definition
     untrusted, and the constraint instance carrying such a URL is
     malformed regardless of whether the unencrypted endpoint would have
     returned a valid signature.  Verifiers SHOULD apply additional
     transport-layer protections appropriate to the deployment context,
     including but not limited to rejection of URLs resolving to private
     address ranges, strict request timeouts, and bounded redirect
     handling.  The specifics of these protections are deployment-defined.

     The security implications of attestation_url — including server-side
     request forgery considerations and connection-time defences — are
     addressed in Section 7.7.

  4.1.2.  max_attestation_age

     Type: integer (seconds).  Required: Yes.

     The maximum age in seconds, measured from the attestation's signing
     time to the verifier's evaluation time, beyond which the attestation
     MUST NOT be accepted.  The mandate issuer declares this value at



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 16]


  Internet-Draft                environment.*                     May 2026


     constraint-instance construction time.  Verifiers MUST reject
     attestations whose age exceeds max_attestation_age, regardless of
     whether the attestation's own expiry has not yet passed.

     max_attestation_age MUST be a positive integer.  A constraint
     instance lacking an explicit max_attestation_age is malformed and
     verifiers MUST reject it.  There is no default value at the family
     layer; specifications adding default values per constraint type are
     non-conforming because the freshness window is the family's primary
     security property, and a default at any layer recreates the implicit-
     freshness exposure the family is designed to close.

     The freshness window is the primary exploitable surface of any
     environment.* constraint.  The window is the period during which a
     signed attestation, valid at the moment of signing, may no longer
     reflect the current state of the property the constraint addresses.
     An attestation that is technically still inside its issuer's TTL but
     is operationally stale — that is, its signing time predates a
     relevant change in the underlying environmental property — is the
     canonical failure case: market state can change between signing and
     execution, wallet state can change between signing and execution, and
     any environmental property the family addresses can change between
     signing and execution.  The mandate issuer is the party best
     positioned to declare the maximum tolerable window for the gated
     decision; max_attestation_age is the field through which that
     declaration is made.

     The attestation issuer's TTL (the issuer-side time after which the
     issuer no longer claims the attestation is valid) and
     max_attestation_age (the consumer-side time after which the verifier
     no longer accepts the attestation) serve different parties and MUST
     be independently configurable.  A verifier MUST honour both: an
     attestation that has passed either bound is unacceptable.  The
     narrower of the two governs in practice.

     The security implications of max_attestation_age — including
     attestation replay considerations — are addressed in Section 7.1.

  4.2.  Field-Scope Taxonomy

     The environment.* constraint family contains fields that appear under
     identical names in multiple constraint types.  A shared field name
     does not, by itself, imply shared semantics: some fields carry
     identical meaning across types, while others have parallel-but-
     mechanism-specific meaning tied to each type's trust-root or
     evaluation mechanism.  To prevent ambiguity, each field in the family
     MUST be classified by its specification author under one of the
     categories defined below.



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 17]


  Internet-Draft                environment.*                     May 2026


     The family currently recognises three scope categories:

     family-wide-trust-root-agnostic.  The field carries identical
     semantics across every environment.* constraint type, independent of
     the trust-root mechanism each type uses.  A single verification code
     path handles the field for every type in the family.

     per-type-trust-root-mechanism-bound.  The field's operational
     semantics depend on the specific trust-root mechanism of the
     constraint type ([RFC7517] JWKS, [RFC8615] well-known key registry,
     or another mechanism).  The field name may appear in multiple
     specifications with parallel but mechanism-specific semantics.

     per-type-evaluation-mechanism-bound.  The field's operational
     semantics depend on the constraint type's evaluation mechanism: the
     output shape the evaluator produces or the wire-protocol binding to
     the evaluator.  The field name may appear in multiple specifications
     with parallel but evaluation-specific semantics; distinct from per-
     type-trust-root-mechanism-bound in that the binding is to how the
     attestation is produced and shaped, not to how the signing key is
     discovered.

     Within Section 4.2, the term "field" encompasses both constraint
     schema fields and, where operationally relevant, claims within the
     signed attestation payload.

  4.2.1.  Scope Declarations for Family-Wide Fields

     The family-wide fields specified in Section 4.1 are classified as
     follows:

     attestation_url: family-wide-trust-root-agnostic.  Its semantic role
     — the HTTPS endpoint at which the verifier fetches the signed
     attestation — is identical across every environment.* constraint
     type.  Per-type variance in HTTP method or request body is carried by
     neighbouring per-type fields, not by the URL field itself.

     max_attestation_age: family-wide-trust-root-agnostic.  The freshness
     window is a temporal property of the attestation signing event,
     independent of how the verifier retrieves the signing key.

  4.2.2.  Scope Declarations for Per-Type Fields

     Type specification authors MUST declare the scope of every per-type
     field they introduce.  Declarations MUST appear in a Field Scope
     Declaration section of the type specification.  The declaration MUST
     classify the field under one of the three categories of Section 4.2
     and MUST justify the classification in prose.



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 18]


  Internet-Draft                environment.*                     May 2026


     The type specifications referenced in Appendix A carry such
     declarations for the per-type fields they introduce.  This document
     does not enumerate those fields, because doing so would couple the
     family-definition layer to the current set of registered types in a
     way that future revisions of either type's specification could
     invalidate.

  4.2.3.  Adding Scope Categories

     The three categories of Section 4.2 are sufficient for every field
     introduced by every member type registered at the time of this
     document's publication.  Type specification authors proposing new
     fields SHOULD place them under one of the three existing categories.

     A type specification author MAY propose a new scope category.  Such a
     proposal is a working-group revision of this document, not a per-type
     design choice.  The proposing specification MUST demonstrate that no
     existing category is sufficient for the field's classification, and
     the working group MUST converge on the new category's definition and
     integration with the existing three before any registered type uses
     it.

  4.3.  Algorithm Agility

     The environment.* constraint family is algorithm-agnostic at the
     family layer.  This document does not name a signing algorithm that
     all family members must use, and it does not prefer any algorithm
     over any other.  Algorithm choice is a per-type concern, made by each
     constraint type specification under the framework this section
     establishes.

     The framework follows the discipline of [RFC8725], Section 3.1: each
     constraint type specification MUST declare a single MUST-implement
     signing algorithm that all conformant verifiers for that type MUST
     support, and MAY declare a SHOULD-implement extension set and a MAY-
     implement extension set.  Verifiers negotiate the algorithm per
     constraint instance by reading the attestation's algorithm
     declaration and confirming that the declared algorithm is in their
     supported set for the constraint type.  Verifiers MUST reject
     attestations whose algorithm is not in the type's supported set; this
     rejection is fail-closed and is not a permitted silent downgrade.

     Algorithm deprecation within a registered family member is a per-type
     concern.  Type specification authors SHOULD specify, in the type's
     specification, a deprecation mechanism for the type's MUST-implement
     algorithm before that algorithm is needed — including the conditions
     under which the algorithm is deprecated, the timeline for verifier
     migration to a successor MUST-implement, and the backward-



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 19]


  Internet-Draft                environment.*                     May 2026


     compatibility guarantees during the transition.  The family-wide
     obligation is structural: every type specification MUST declare its
     current MUST-implement algorithm, and verifiers MUST honour the
     declaration without fallback.  Deprecation discipline ensures that
     the family does not inherit a brittle commitment to any specific
     algorithm beyond the cryptographic lifetime that algorithm provides.

     The framework is deliberately minimal at the family layer because the
     security properties of signing-algorithm choice are well-specified by
     the JOSE family of specifications and by [RFC8725].  The family-layer
     obligation is structural: every type specification MUST declare its
     choice explicitly, and verifiers MUST honour the declaration without
     fallback.  This obligation prevents the family from accidentally
     inheriting a single-algorithm constraint by implementation
     convergence rather than by specification.

     A type specification's choice of MUST-implement algorithm is not
     constrained by this document.  The choice is properly made on the
     basis of the reference implementation's signing stack, the wider VI
     ecosystem's existing JWS infrastructure, the operational properties
     of the algorithm at the type's expected verification volume, and the
     security properties relevant to the type's threat model.  This
     document is silent on these factors because they are per-type
     concerns; it requires only that the choice be made, declared, and
     respected.

  5.  Family Composition

     This section specifies how environment.* constraints compose with
     each other and with constraints from other families.  Six concerns
     are addressed: conjunction semantics across family members
     (Section 5.1), mixed pass/fail handling (Section 5.2), the L3
     execution gate and its completeness rule (Section 5.3), per-member
     diagnostic output (Section 5.4), composition with other families
     (Section 5.5), and the rationale these rules collectively encode
     (Section 5.6).

  5.1.  Conjunction Semantics

     The environment.* family is a conjunction.  A mandate satisfies the
     family's gate if and only if every environment.* constraint instance
     in the mandate passes.  There is no partial-fulfillment path within
     the family, no quorum across members, and no precedence by which one
     member can override another.

     This semantic is family-wide and is not a per-type design choice.  A
     constraint type whose composition with sibling family members is
     anything other than conjunction is by definition outside the family,



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 20]


  Internet-Draft                environment.*                     May 2026


     because the membership criterion of Section 3.2 requires that each
     type's failure mode be gating, and a gating failure cannot be
     survived by composition with passing siblings.

  5.2.  Mixed Pass/Fail

     When one environment.* constraint instance passes and another fails
     in the same mandate, the family's gate fails.  The passing instance
     does not rescue the failing instance.  This rule applies regardless
     of:

     (1) whether the instances are of the same type or different types;

     (2) whether the instances bind to the same subject or to different
     subjects;

     (3) the order in which the instances appear in the mandate; and

     (4) the order in which the verifier evaluated the instances.

     A verifier that returns a passing result for a mandate containing one
     passing and one failing environment.* constraint is non-conforming.

  5.3.  L3 Execution Gate and Completeness

     The environment.* family gates Layer 3 acceptance.  A verifier MUST
     NOT accept a Layer 3 mandate whose Layer 2 mandate carries any failed
     environment.* constraint, regardless of whether the verifier
     evaluated the failed constraint first, last, or in any other order.

     The verifier MUST evaluate every environment.* constraint in the
     mandate to completion before refusing Layer 3, even after the first
     failure has been observed.  This is the completeness requirement.
     Short-circuit evaluation of environment.* constraints — terminating
     the family-evaluation pass at the first failure without evaluating
     subsequent members — is non-conforming because it denies downstream
     consumers the per-member evidence the family's diagnostic output
     (Section 5.4) depends on.













  Borthwick & Msebenzi    Expires 12 November 2026               [Page 21]


  Internet-Draft                environment.*                     May 2026


     The completeness requirement applies to the verifier-side
     L3-acceptance evaluation path.  It does not apply to the agent-side
     pre-L3-creation evaluation path.  An agent constructing Layer 3 MUST
     itself satisfy every environment.* constraint before constructing
     Layer 3, and an agent that observes any environment.* failure during
     pre-L3-creation evaluation MUST halt construction at the first
     failure as a fail-closed agent-side response.  The agent's halt is
     operationally distinct from the verifier's diagnostic-completeness
     obligation: the agent's purpose is to avoid producing a Layer 3 that
     the verifier would refuse; the verifier's purpose is to produce
     complete diagnostic output even when refusing.

     Evaluation of constraints from other families (for example,
     transactional constraints under mandate.*) after a confirmed
     environment.* failure remains implementation-defined.  A verifier MAY
     evaluate them for diagnostic completeness or MAY skip them for
     efficiency, provided the resulting refusal of Layer 3 is unambiguous.

  5.4.  Per-Member Diagnostic Output

     Each failed environment.* constraint MUST produce its own entry in
     the verifier's violations output.  Verifiers MUST NOT collapse
     multiple environment.* failures into a single generic violation
     entry.

     Each violation entry MUST carry two identifiers:

     (1) the array index of the failing constraint within the mandate's
     constraints array, as the primary machine identifier.  The index is
     unambiguous across any combination of constraint types and across
     mandates containing multiple instances of the same type;

     (2) a human-readable identifier derived from the failing constraint's
     distinguishing field, as the secondary identifier intended for
     operator diagnostics and dispute resolution.

     The selection of the distinguishing field is a per-type obligation.
     Each constraint type specification author MUST declare which field of
     the type is the distinguishing field, and MUST specify a fallback
     when the distinguishing field is not present in the failing instance
     (for example, when the constraint's signed attestation could not be
     obtained at all).  The reference type specifications cited in
     Appendix A carry such declarations for their respective types.








  Borthwick & Msebenzi    Expires 12 November 2026               [Page 22]


  Internet-Draft                environment.*                     May 2026


     The diagnostic output requirement is family-wide because the family's
     audit value depends on it.  A mandate carrying multiple environment.*
     constraints — whether multiple instances of the same type or
     instances of multiple types — produces, at refusal, an audit record
     showing exactly which environmental conditions failed and which held.
     Collapsing per-member diagnostics destroys that record.

  5.5.  Composition with Other Families

     environment.* constraints MUST be evaluated before constraints from
     other families in the same mandate.  If any environment.* constraint
     fails, the verifier MUST refuse Layer 3 regardless of how constraints
     from other families would evaluate.  The ordering is one-directional:
     environment.* gates execution, and other families do not gate
     environment.* evaluation.

     The rationale is structural.  Evaluating transactional constraints
     (allowed merchants, allowed payees, amount ranges) before confirming
     the execution environment is valid exposes the verifier to a time-of-
     check-to-time-of-use race in which a transactional constraint passes
     against a Layer 3 that names an environment the verifier has not yet
     attested. environment.* evaluation precedes transactional evaluation
     so that the environment is established before the transaction is
     authorised against it.

     This ordering is normative regardless of whether other constraint
     families exist at the time of this document's publication or are
     added later.  A future family with its own membership criterion and
     its own family-definition specification MUST document its own
     ordering relationship to environment.*, but environment.* itself is
     not subject to ordering preemption by any other family.

  5.6.  Rationale

     The composition rules of Sections 5.1 through 5.5 are not arbitrary.
     Two arguments, co-equal and reinforcing, motivate them.

     The semantic argument: each member of the environment.* family
     answers an independent question about the world at the moment of
     execution — is this venue open? is this wallet funded? does this
     counterparty's regulatory status hold?  Because the questions are
     independent, their answers compose as conjunction, not disjunction: a
     failure on any member removes the basis for execution.  There is no
     construction in which "the venue is open OR the wallet is funded" is
     the correct gate for an autonomous transaction.  Both must hold.






  Borthwick & Msebenzi    Expires 12 November 2026               [Page 23]


  Internet-Draft                environment.*                     May 2026


     The architectural argument: conjunction also falls out of the
     family's membership criterion (Section 3.2) directly.  A constraint
     type whose failure mode is OR-tolerable is, by the criterion, outside
     the family.  If a constraint's failure is survivable by composition
     with passing siblings, the constraint is not gating execution; if it
     is not gating execution, it does not satisfy the membership
     criterion; if it does not satisfy the criterion, it is not in the
     family.  Conjunction is therefore not a design choice the working
     group makes when registering each new type — it is a consequence of
     the membership criterion the type satisfied to enter the family in
     the first place.

     The two arguments meet at the same conclusion from independent
     directions.  The semantic argument applies regardless of how the
     family is defined.  The architectural argument applies regardless of
     what the family means.  That both arguments converge on conjunction
     is the strongest evidence that conjunction is the right composition
     rule for environment.*.

     The per-member diagnostic requirement of Section 5.4 follows from the
     same logic.  Collapsing per-member diagnostics would destroy the
     audit trail that makes the family load-bearing for downstream dispute
     resolution.  Preserving per-member diagnostics makes every signed
     attestation recoverable from the verifier's output, and makes dispute
     resolution an application-layer concern with complete evidence rather
     than a debugging exercise.  Both type specifications cited in
     Appendix A already encode this discipline; this document promotes it
     from per-type rationale to family-wide normative requirement so that
     every future family member inherits it without re-litigation.

  6.  Register Discipline

     This section specifies the discipline under which RFC 2119 keywords
     are used in this document and in any specification of an
     environment.* constraint type that claims membership in the family.
     The discipline distinguishes normative register from descriptive
     register and constrains the use of each.

     The discipline is family-wide.  A constraint type specification that
     does not conform to this section is non-conforming as a family
     member, regardless of the soundness of its technical content, because
     mixed register defeats the conformance-checkability that makes the
     family's normative statements actionable for implementers.








  Borthwick & Msebenzi    Expires 12 November 2026               [Page 24]


  Internet-Draft                environment.*                     May 2026


  6.1.  Normative Register

     Normative register uses RFC 2119 keywords (MUST, MUST NOT, REQUIRED,
     SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED,
     MAY, OPTIONAL) in all capitals, per [RFC2119] and [RFC8174], to bind
     implementers to specific behaviour.

     Normative register specifies behaviour that an implementation either
     satisfies or fails to satisfy; it is conformance-checkable.  Any RFC
     2119 keyword in all capitals MUST appear only in a sentence that
     imposes a requirement on a named implementer (an agent, a verifier, a
     mandate issuer, an attestation issuer, a type specification author,
     IANA, or a designated expert).  The Section 2.1 boilerplate per
     [RFC8174] binds the interpretation throughout this document.

  6.2.  Descriptive Register

     Descriptive register explains intent, rationale, precedent, context,
     or structural reasoning.  It uses lowercase synonyms (or explicit
     non-keyword phrasing) where RFC 2119 keywords would otherwise appear.

     Descriptive register is not conformance-checkable.  It exists to make
     the normative register actionable: a reader of normative requirements
     is better served by descriptive prose explaining why the requirement
     holds than by the requirement standing alone without context.
     Descriptive prose SHOULD use lowercase synonyms ("must" rather than
     MUST, "should" rather than SHOULD, "may" rather than MAY) when no new
     requirement is being imposed.  Where the lowercase synonym would be
     ambiguous about whether it imposes a requirement, explicit non-
     keyword phrasing ("the section establishes", "the type specification
     author's choice is", "the framework requires") is preferred over
     either capitalisation.

     The discipline matters because a specification that mixes normative
     and descriptive register — for example, by using all-capitals MUST in
     a rationale paragraph that does not impose a requirement — produces
     ambiguous conformance: a reviewer or implementer reading prose with
     all-capitals keywords in descriptive context cannot tell whether the
     text imposes a requirement or merely describes one.  Resolving such
     ambiguity requires reading the surrounding sentences to infer intent,
     which is precisely the work the discipline is designed to avoid.










  Borthwick & Msebenzi    Expires 12 November 2026               [Page 25]


  Internet-Draft                environment.*                     May 2026


  6.3.  Redundancy Avoidance

     [RFC2119], Section 3 establishes that SHOULD and RECOMMENDED carry
     identical normative force; [RFC2119], Section 5 establishes that MAY
     and OPTIONAL carry identical normative force.  Field labels, section
     headers, and parenthetical qualifiers that duplicate the normative
     keyword present in the containing sentence add visual weight without
     adding normative content.

     A specification SHOULD NOT pair a label such as "(RECOMMENDED)" with
     a sentence whose verb is already SHOULD, and SHOULD NOT pair a label
     such as "(OPTIONAL)" with a sentence whose verb is already MAY.  The
     keyword in the containing sentence carries the requirement; the
     parenthetical label adds register noise.

     This rule applies to specification authors as a stylistic discipline.
     A specification that violates it remains technically conformant; the
     rule's purpose is to keep the document surface clean enough that the
     discipline of Sections 6.1 and 6.2 is visible to a reviewer scanning
     for register issues.

  6.4.  Scope of Application

     Normative requirements MUST name the implementer they bind.  A
     requirement that does not name its implementer is ambiguous and the
     ambiguity is not resolved by context.

     Where a requirement could be read at multiple layers of the stack —
     for example, "verifiers MUST re-verify" read as a network-transport
     obligation versus an application-layer obligation — the specification
     text MUST name the application-layer scope explicitly.  A sentence
     such as "verifiers MUST re-verify the attestation against the chain's
     then-current state at settlement time" reads ambiguously without
     scope: it could bind a chain client, an RPC layer, a cryptographic
     library, or the VI verifier's L3-acceptance logic.  The specification
     text MUST name which.

     The application-layer scope of family-wide requirements in this
     document is the VI verifier's L3-acceptance logic.  Requirements at
     other layers (network transport, cryptographic library, chain client)
     are out of this document's scope and are governed by the
     specifications appropriate to those layers.









  Borthwick & Msebenzi    Expires 12 November 2026               [Page 26]


  Internet-Draft                environment.*                     May 2026


  6.5.  Forward Rule for New Sections and New Specifications

     New sections introduced in future revisions of this document, and all
     sections of any constraint type specification that claims membership
     in the environment.* family, MUST apply the rules of Sections 6.1
     through 6.4 at introduction.

     Editorial register polish — conversion of all-capitals to lowercase
     in descriptive context, removal of RECOMMENDED/SHOULD redundancy,
     application-layer scope naming — is a patch-level revision and does
     not require a minor-version bump in any specification that adopts
     patch-level versioning.  The rule is not that the discipline be
     applied perfectly on first draft, but that it be applied without
     exception by the time a specification is presented for working-group
     adoption.

  6.6.  Relationship to Section 2.1 Conventions

     This section extends the Section 2.1 Conventions and Definitions
     statement.  Section 2.1 binds the interpretation of RFC 2119 keywords
     when they appear in all capitals per [RFC8174].  This Section 6
     specifies the editorial discipline for when RFC 2119 keywords SHOULD
     appear in all capitals (Section 6.1, normative register) versus when
     they SHOULD NOT (Section 6.2, descriptive register).  Together,
     Section 2.1 and Section 6 establish the register discipline of the
     environment.* family.

  6.7.  Open Questions

     This section reproduces three questions that the type specifications
     cited in Appendix A raise about register discipline and that the
     working group has not yet converged on.  The questions are reproduced
     here so that working-group review of this document addresses them as
     family-wide concerns rather than per-type concerns.  The current
     draft takes provisional positions on each; the working group is
     invited to revise.

     Q1.  Is this section informative — describing the discipline that the
     family's normative sections already follow — or normative — binding
     future type specifications to the rules at Sections 6.1 through 6.5?
     Provisional position: Sections 6.1 through 6.5 are treated as
     normative (with all-capitals RFC 2119 keywords throughout) and
     Sections 6.6 and 6.7 as informative.  The working group may
     reclassify any subsection.

     Q2.  Should the family adopt a formal register-discipline audit
     cadence — for example, a pre-release audit before each minor version
     of a type specification — or is the ad-hoc audit pattern established



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 27]


  Internet-Draft                environment.*                     May 2026


     by the type specifications cited in Appendix A sufficient?
     Provisional position: The current draft does not mandate a cadence;
     the rule of Section 6.5 is that the discipline be applied by the time
     a specification is presented for adoption.

     Q3.  What is the relationship between this section and other family-
     charter material that may be added to future revisions?  Provider
     neutrality, peer-author coordination discipline, patch-level
     versioning conventions, and lockstep commit patterns across sibling
     specifications are family-charter concerns that the type
     specifications cited in Appendix A have raised.  Provisional
     position: The working group decides whether such material
     consolidates into a future revision of this section, into a separate
     family-charter section, or into a hybrid structure; the current draft
     does not foreclose.

  7.  Security Considerations

     This section enumerates security concerns that apply family-wide to
     environment.* constraints.  Per-type security considerations — those
     tied to a specific trust-root mechanism, a specific signing
     algorithm, or a specific evaluation mechanism — are addressed by each
     constraint type's specification.  The family-wide concerns below
     apply to every member type and to every implementation of every
     member type.

  7.1.  Attestation Replay

     A signed attestation is a bearer artifact within its acceptance
     window.  Any party in possession of a valid signed attestation may
     present it to a verifier, and the verifier — applying only the
     cryptographic checks the attestation supports — will accept it.  The
     acceptance window is bounded by the attestation's expiry and further
     narrowed by the constraint instance's max_attestation_age
     (Section 4.1.2), but within that window the attestation is
     replayable.

     For deployment contexts where attestation reuse would authorise
     duplicate state changes (for example, payment execution, where an
     attestation justifying one settlement could otherwise justify a
     second settlement against the same wallet within the freshness
     window), verifiers MUST maintain a per-attestation deduplication
     cache keyed on the attestation's unique identifier.  For deployment
     contexts where attestation reuse is benign (for example, idempotent
     read-only operations), verifiers SHOULD maintain a per-attestation
     deduplication cache as defence in depth, but MAY rely on the
     freshness window alone.  The unique identifier and the cache TTL are
     per-type concerns: each constraint type specification names the field



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 28]


  Internet-Draft                environment.*                     May 2026


     its attestations carry as the unique identifier, and the cache TTL is
     bounded by max_attestation_age plus an implementation-defined margin
     to absorb clock skew.

     The replay surface is family-wide because it follows from the bearer-
     artifact property of signed attestations, which is itself family-
     wide: every environment.* attestation is a signed statement that a
     verifier accepts on the strength of the signature, and any signed
     statement that travels over the wire is replayable to any verifier
     that accepts the same signature.  The specific mitigation varies by
     deployment context.

  7.2.  Issuer Trust Bootstrapping

     The security of any environment.* constraint depends on the verifier
     correctly establishing the attestation issuer's signing key.  Each
     constraint type names a trust-root mechanism (Section 4.2) under
     which a verifier discovers the key — JWKS at a known HTTPS URL, a
     well-known key registry per [RFC8615], or another mechanism — but
     every trust-root mechanism reduces, eventually, to an out-of-band
     initial trust establishment.

     Verifiers SHOULD establish initial trust in an attestation issuer
     through at least one channel independent of the trust-root mechanism:
     DNSSEC for the issuer's domain, certificate transparency log
     inspection for the issuer's TLS certificates, published key
     fingerprints in a venue independent of the issuer's primary
     infrastructure, or out-of-band fingerprint comparison with a known-
     good party.  The specifics of initial-trust channels are deployment-
     defined; the family-wide requirement is that no implementation rely
     on the trust-root mechanism alone to bootstrap trust in a previously-
     unknown issuer.

     This concern is family-wide because the trust-root mechanism's job is
     to make ongoing key discovery secure once initial trust is
     established, not to establish initial trust ex nihilo.  A verifier
     that fetches an unknown issuer's JWKS over HTTPS and accepts whatever
     keys are returned has authenticated only that the JWKS was served by
     the host named in the URL.  It has not authenticated that the host
     named in the URL is the issuer the mandate intended.  Initial trust
     is the gap between those two facts.










  Borthwick & Msebenzi    Expires 12 November 2026               [Page 29]


  Internet-Draft                environment.*                     May 2026


  7.3.  Constraint Stripping and Insertion

     An attacker with the ability to modify a Layer 2 mandate could remove
     environment.* constraint instances from the mandate before the agent
     or verifier evaluates it.  A mandate with environment.* constraints
     stripped expands the agent's authority to environments the user did
     not authorise.

     The defence against constraint stripping is the Layer 2 signature,
     which covers the full constraint list as presented at issuance time.
     Any modification to the constraint list — including removal or
     insertion of an unauthorised constraint — invalidates the signature.
     Verifiers MUST reject any Layer 2 mandate whose signature does not
     validate over the full constraint list as presented, and
     implementations MUST NOT accept mandates whose verified signature
     covers only a subset of the declared constraints.

     The same defence applies to constraint insertion: a mandate issuer
     acting outside the user's authorisation cannot add a constraint
     instance to a user-signed mandate without invalidating the user's
     signature.  Note that this defence depends on the mandate issuer's
     honesty regarding what the user authorised at the time the mandate
     was signed; it does not protect against a mandate issuer who
     constructs a mandate with constraint instances the user did not
     authorise.  Trust in the mandate issuer's faithfulness to user intent
     is a deployment-level concern outside the scope of this document.

     This concern is family-wide because it follows from the family's
     insertion into Verifiable Intent's Layer 2 mandate format: any
     constraint in any family is subject to stripping and insertion, and
     the Layer 2 signature is the family-agnostic defence.  The family
     inherits the defence; it does not add new defences.

  7.4.  Substitution of Attestation Endpoints

     A more subtle attack than stripping is substitution: an attacker who
     can modify a Layer 2 mandate replaces a constraint's attestation_url
     with a URL pointing to an attacker-controlled endpoint that returns
     valid-looking signed responses.  The signature on the substituted
     attestation is, by construction, valid against whatever key the
     attacker chose; the trust-root mechanism's binding to a specific
     issuer's key is what defeats the attack.

     The defence is per-type, but its family-wide minimum is specified
     here.  Each constraint type specification MUST identify, at minimum,
     two binding fields signed into the Layer 2 mandate alongside
     attestation_url: an issuer-identifier binding (the field that names
     which attestation issuer's key is acceptable) and a key-identifier



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 30]


  Internet-Draft                environment.*                     May 2026


     binding (the field that names which specific key, within that
     issuer's key set, is acceptable).  For [RFC7517] JWKS-based types,
     this typically means a JWKS URL, a key identifier, and an issuer
     identifier; for [RFC8615] well-known key registry-based types, this
     typically means a key identifier together with the issuer identity
     from which the key registry URL is derived.  An attacker who
     substitutes attestation_url MUST also substitute every binding field
     to evade detection, and the substitution is detectable provided the
     verifier honours every binding.

     The family-wide minimum is that every constraint type's binding
     fields — at minimum, the issuer-identifier binding and the key-
     identifier binding — MUST be signed into the Layer 2 mandate by the
     mandate issuer at issuance time and MUST be honoured by verifiers at
     evaluation time.  A type specification whose verification algorithm
     does not honour every declared binding field, or whose declared
     binding fields do not satisfy the family-wide minimum, is non-
     conforming.  This minimum applies independent of trust-root
     mechanism: future trust-root mechanisms admitted under Section 3.4(2)
     ("comparable security properties") inherit the same issuer-identifier
     and key-identifier binding obligations.

  7.5.  Mandate-Issuer-Versus-Attestation-Issuer Trust Separation

     Section 2.2 distinguishes the mandate issuer (the party that
     constructs the Layer 2 mandate) from the attestation issuer (the
     party that signs the attestation the verifier evaluates against).
     The two roles are separately trusted and separately compromised.  A
     compromised mandate issuer could construct mandates with attestation
     bindings pointing to compromised attestation issuers; a compromised
     attestation issuer could sign valid attestations for false world-
     states.  Each compromise is independently consequential, and each
     role's trust establishment is independently the deployment's
     responsibility.

     The family does not specify formal trust-establishment procedures for
     either role; that work belongs in Verifiable Intent's threat model
     and in deployment-specific operational documentation.  The family-
     wide requirement is that the two roles MUST NOT be conflated by an
     implementation.  An implementation that treats a mandate issuer's
     signature as evidence about the attestation issuer's signing key — or
     vice versa — is non-conforming because the two signatures bind
     different facts and a verifier acting on one as evidence for the
     other has reduced its security to whichever role is currently more
     trusted.






  Borthwick & Msebenzi    Expires 12 November 2026               [Page 31]


  Internet-Draft                environment.*                     May 2026


     A concrete check that follows from this requirement: a verifier MUST
     NOT use the mandate issuer's identity (or any binding field attesting
     to the mandate issuer) as input to the verification of the
     attestation's signature.  The attestation signature is verified
     against the attestation issuer's key, discovered through the trust-
     root mechanism, with no mandate-issuer-derived inputs.  This check is
     conformance-testable.

     This concern is family-wide because the role distinction is family-
     wide: every environment.* constraint instance carries both a mandate-
     issuer signature (over the Layer 2 mandate) and an attestation-issuer
     signature (over the attestation the constraint binds to), and every
     verification path involves both signatures.  Conflating them is a
     verification-path error rather than a per-type error.

  7.6.  Time Synchronisation

     The freshness check of Section 4.1.2 (max_attestation_age) requires
     that the verifier's clock is reasonably synchronised with the
     attestation issuer's clock.  A clock skew exceeding
     max_attestation_age would cause the verifier to reject all
     attestations from a correctly-operating issuer.

     Implementations SHOULD use clock-synchronisation mechanisms
     appropriate to the deployment context (such as NTP) and SHOULD log
     clock-skew-related verification failures distinctly from other
     failure modes to aid diagnosis.  The family does not specify a clock-
     synchronisation mechanism; the family-wide requirement is that
     implementations use a mechanism whose accuracy is bounded below the
     smallest max_attestation_age value the implementation expects to
     encounter in production.

     This concern is family-wide because max_attestation_age is family-
     wide.  A constraint type specification that uses a clock-anchored
     field other than max_attestation_age inherits the same concern; this
     section's requirement applies to whichever clock-anchored field the
     type uses.

  7.7.  SSRF and Other Verifier-Initiated Fetch Risks

     The attestation_url field of every environment.* constraint instance
     is a mandate-controlled URL that the verifier will fetch.  Without
     protection, this is a server-side request forgery primitive: an
     attacker who can modify the Layer 2 mandate (or who can introduce
     constraint instances at mandate construction time) can direct the
     verifier to fetch arbitrary URLs.





  Borthwick & Msebenzi    Expires 12 November 2026               [Page 32]


  Internet-Draft                environment.*                     May 2026


     Verifiers MUST apply transport-layer protections appropriate to the
     deployment context.  Family-wide minimum requirements:

     (1) reject URLs that do not use the https scheme (already required by
     Section 4.1.1);

     (2) reject URLs whose hostnames resolve to address ranges not
     appropriate for outbound verifier traffic.  At minimum, this includes
     the [RFC1918] private address ranges (10.0.0.0/8, 172.16.0.0/12,
     192.168.0.0/16), loopback (127.0.0.0/8), link-local (169.254.0.0/16),
     and any deployment-specific exclusion list;

     (3) bound request timeouts to a value short enough that verifier-side
     SSRF attempts cannot extract significant information through timing
     observation;

     (4) bound redirect handling to at most one redirect, and apply the
     same address-range and scheme checks to redirect targets;

     (5) re-resolve the hostname at connection time and apply the address-
     range checks of (2) to the resolved IP, defending against DNS
     rebinding attacks where a domain resolves to a public IP at fetch-
     time and a private IP at connection-time.

     The specific timeout values, deployment-specific exclusion list
     extensions, and redirect-handling specifics beyond the minima above
     are deployment-defined.  Per-type specifications MAY tighten these
     requirements but MUST NOT relax them; a type specification that
     permits non-HTTPS URLs, omits any of the address-range exclusions in
     (2), or admits unbounded redirects is non-conforming.

     This concern is family-wide because every environment.* constraint
     instance carries an attestation_url and every verifier fetches it.
     The mitigation is family-wide minimum plus deployment-specific
     tightening.

  7.8.  Signer Failure Handling

     The trust-root mechanisms specified by per-type specifications (e.g.,
     [RFC7517] JWKS, [RFC8615] well-known key registry) provide
     cryptographically authenticated key discovery under correct
     operation.  They do not address the failure mode in which an
     attestation issuer publishes signatures or key material that, while
     cryptographically well-formed, are operationally incorrect — for
     example, signatures over stale or misconfigured state, or key-
     rotation events that publish keys in an inconsistent intermediate
     state.  Such failures are not theoretical: cryptographic
     infrastructure depending on similar trust-root mechanisms (DNSSEC



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 33]


  Internet-Draft                environment.*                     May 2026


     zone-signing key rollovers, certificate transparency log misissuance)
     has experienced documented outages of this class.

     A constraint type's verification algorithm under Section 3.4(3)
     terminates as constraint-satisfied or constraint-violated; it does
     not have a third terminal state for "issuer is currently
     malfunctioning."  Verifiers SHOULD therefore implement an
     application-layer mechanism analogous to the Negative Trust Anchor
     pattern of [RFC7646] under which a verifier MAY temporarily decline
     to validate against a specific issuer's keys when that issuer is
     known to be publishing incorrect attestations.  Verifiers SHOULD
     additionally surface the reason for declined verification through a
     mechanism analogous to Extended DNS Errors [RFC8914], so that
     downstream consumers (agents, mandate issuers, audit systems) can
     distinguish issuer-failure refusals from constraint-violation
     refusals.

     The family-wide requirement is operational rather than cryptographic:
     the verification algorithm continues to fail closed regardless of
     whether issuer-failure handling is implemented, and an agent
     observing any failure halts construction of Layer 3 per Section 5.3.
     The Negative Trust Anchor and Extended DNS Errors patterns do not
     weaken the failure-closed posture; they make the cause of refusal
     diagnosable by humans and audit systems.  Implementations choosing
     not to implement these patterns inherit a coarser failure mode in
     which all verifications against a malfunctioning issuer fail without
     distinguishing cause, which is conformant but operationally degraded.

     This concern is family-wide because every environment.* constraint
     type relies on a trust-root mechanism whose failure modes are
     external to the cryptographic verification path, and the operational
     consequences of those failures (mass agent halt, indistinguishable
     refusal causes) are family-wide regardless of which trust-root
     mechanism the type uses.

  8.  IANA Considerations

     This document requests that IANA establish a registry for
     environment.* constraint type identifiers and register this document
     as the family-definition document for the namespace.  The registry's
     scope, registration policy, and expert review criteria are specified
     below.









  Borthwick & Msebenzi    Expires 12 November 2026               [Page 34]


  Internet-Draft                environment.*                     May 2026


     The Verifiable Intent specification [VI-CONSTRAINTS] establishes a
     Constraint Type Registry for VI mandate constraint types.  The
     environment.* registry described here is either a sub-registry of
     that VI Constraint Type Registry or a separate registry coordinated
     with it; the working group's choice between these two structures does
     not affect the registration content this document specifies and is
     left to the working group at adoption time.

  8.1.  The environment.* Namespace

     IANA is requested to register the environment.* namespace as a
     constraint type prefix in the registry of Section 8.2.  The namespace
     is the literal string environment followed by a dot followed by one
     or more dot-separated components identifying a specific environmental
     property and, optionally, sub-classifications.

     This document is registered as the family-definition document for the
     environment.* namespace.  Specifications proposing new environment.*
     type identifiers MUST conform to this document.  IANA MUST NOT
     register a specification that does not conform, regardless of the
     technical merit of the proposed type.

  8.2.  The environment.* Constraint Type Registry

     IANA is requested to establish a registry titled "Verifiable Intent
     environment.* Constraint Types" (or a name the working group prefers)
     with the following structure.

     Registry fields.  Each registration entry has the following fields:

     *  Type identifier — the dot-separated string under the environment.*
        namespace (for example, environment.market_state,
        environment.wallet_state).

     *  Defined In — a reference to the constraint type specification
        document that defines the type.  The reference SHOULD be a stable
        identifier (RFC number, Internet-Draft name and revision, or a
        permanent published-document URL).

     *  Version — the version of the type specification at the time of
        registration.

     *  Status — one of: Provisional, Stable, Deprecated.








  Borthwick & Msebenzi    Expires 12 November 2026               [Page 35]


  Internet-Draft                environment.*                     May 2026


     *  Distinguishing Field — the field per Section 5.4 that the type's
        diagnostic output uses for per-member identification.  The
        fallback for cases where the distinguishing field is not present
        in a failing instance MUST be either listed here or referenced
        from the Defined-In document.

     *  MUST-Implement Algorithm — the per-type signing algorithm declared
        per Section 4.3.

     *  Notes — implementation-status references per [RFC6982], known-
        issues references, or coordination references with sibling
        specifications.  May be empty.

     Initial registry contents.  This document does not register any
     specific type identifier.  The two reference type specifications
     cited in Appendix A are expected to register environment.market_state
     and environment.wallet_state respectively under their own working-
     group-adoption procedures.  Registration of those types is the
     responsibility of their respective specifications, not of this
     document.

     Registration policy.  Registration follows the Specification Required
     policy of [RFC8126], Section 4.6 with Expert Review by designated
     experts the working group appoints.  The criteria the experts apply
     are specified in Section 8.3.

  8.3.  Expert Review Criteria

     Designated experts evaluating a proposed registration MUST verify
     that the proposed type satisfies all seven requirements of
     Section 3.4:

     (1) the type satisfies the membership criterion of Section 3.2
     (failure mode is gating);

     (2) the type's specification names a trust-root mechanism with
     comparable security properties as defined in Section 3.4(2);

     (3) the type's verification algorithm produces only constraint-
     satisfied or constraint-violated as terminal states;

     (4) the type's per-type fields are classified under the field-scope
     taxonomy of Section 4.2;

     (5) the type's per-type MUST-implement signing algorithm and
     extension sets are declared per Section 4.3;





  Borthwick & Msebenzi    Expires 12 November 2026               [Page 36]


  Internet-Draft                environment.*                     May 2026


     (6) the type's per-type distinguishing field for diagnostic
     disambiguation is declared per Section 5.4, with a fallback
     specified;

     (7) the type specification conforms to the register discipline of
     Section 6.

     A proposed registration that fails any of these checks MUST be
     rejected by the designated experts.  Rejection is not punitive; it
     indicates that the gap should be closed in the proposed specification
     before the registration is reconsidered.  Designated experts SHOULD
     provide specific feedback identifying which check the proposed
     registration failed and what closure of the gap would look like.

     Designated experts SHOULD also evaluate proposed registrations for:

     *  Namespace coherence.  The proposed identifier SHOULD identify the
        environmental property the type addresses (for example,
        market_state, wallet_state, regulatory_status), not the
        implementation, the issuer, or the wire format.  An identifier
        such as environment.fooissuer_jwt is poorly chosen even if its
        specification is technically conformant.

     *  Coordination with sibling types.  Where a proposed type's
        vocabulary overlaps with a registered type's vocabulary, the
        proposed specification SHOULD use the existing field name with the
        existing semantics, or SHOULD justify why a divergent name or
        semantics is necessary.  Proliferation of near-synonymous fields
        across types defeats the family's vocabulary discipline.

     *  Implementation status.  Proposed registrations from specifications
        that document at least one running implementation per [RFC6982]
        SHOULD be preferred over proposed registrations from
        specifications without running implementations, because the
        family's discipline depends on every member being implementable
        end-to-end with the family's vocabulary.

     These additional criteria are guidance for designated experts.  They
     are not normative requirements that proposed registrations MUST
     satisfy.

  8.4.  Status Field Lifecycle

     The Status field of Section 8.2 has three values:







  Borthwick & Msebenzi    Expires 12 November 2026               [Page 37]


  Internet-Draft                environment.*                     May 2026


     Provisional.  The type's specification has been adopted by the
     working group but has not yet been published as an RFC or equivalent
     stable document.  Implementations of provisional types are encouraged
     but should expect specification changes during the provisional
     period.

     Stable.  The type's specification has been published as an RFC or
     equivalent stable document.  Implementations rely on a stable
     contract; specification changes after the Stable transition follow
     normal protocol-evolution procedures (errata, new versions,
     deprecation).

     Deprecated.  The type's specification has been superseded or
     withdrawn.  Deprecation does not suspend the membership criterion of
     Section 3.2; a deprecated type whose specification still satisfies
     the criterion remains a family member in good standing for backward-
     compatibility purposes, while a deprecated type whose specification
     no longer satisfies the criterion enters the contradiction state of
     Section 3.5.  The Notes field SHOULD reference the superseding
     specification or document the reason for withdrawal.  Verifiers MAY
     continue to support deprecated types for backward compatibility but
     SHOULD log their use distinctly to surface candidates for migration.

     A type's Status field is updated by the working group as the type's
     specification matures, by the same Expert Review process specified in
     Section 8.2.  A status transition MUST NOT change a registered type's
     field-scope classifications (per Section 4.2) or its distinguishing
     field (per Section 5.4); changes to either are working-group
     revisions of the type's specification, not administrative status
     updates.

  8.5.  Updates to This Document

     Future revisions of this document that change the registry structure,
     the registration policy, or the Expert Review criteria are working-
     group revisions and MUST be processed by the working group through
     the same procedures that produced the current document.  Editorial
     revisions that do not change the registry's substantive structure are
     patch-level revisions per Section 6.5.

     A future revision that adds a new scope category to Section 4.2.3
     implicitly affects the Expert Review criteria of Section 8.3
     (criterion 4 is updated to include the new category).  Such a
     revision MUST update Section 8.3 explicitly so the criteria remain
     self-contained.

  9.  References




  Borthwick & Msebenzi    Expires 12 November 2026               [Page 38]


  Internet-Draft                environment.*                     May 2026


  9.1.  Normative References

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

     [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
                Writing an IANA Considerations Section in RFCs", BCP 26,
                RFC 8126, DOI 10.17487/RFC8126, June 2017,
                <https://www.rfc-editor.org/rfc/rfc8126>.

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

     [VI-CONSTRAINTS]
                Verifiable Intent Working Group, "Verifiable Intent —
                Constraint Type Definitions and Validation Rules", Work in
                Progress, Internet-Draft, v0.1-draft, February 2026,
                <https://verifiableintent.dev/spec/constraints/>.

     [VI-CREDENTIAL-FORMAT]
                Verifiable Intent Working Group, "Verifiable Intent —
                Credential Format Specification", Work in Progress,
                Internet-Draft, v0.1-draft, February 2026,
                <https://verifiableintent.dev/spec/credential-format/>.

  9.2.  Informative References

     [ENVIRONMENT-MARKET-STATE]
                Headless Oracle Project, "Verifiable Intent — External
                State Attestation Constraint Proposal
                (environment.market_state)", Work in
                Progress v0.5.11-draft, 2026.

     [ENVIRONMENT-WALLET-STATE]
                Borthwick, D., "Verifiable Intent — Wallet State
                Attestation Constraint Proposal
                (environment.wallet_state)", Work in
                Progress v0.6.5-draft, 2026.

     [RFC-SD-JWT]
                Fett, D., Yasuda, K., and B. Campbell, "Selective
                Disclosure for JWTs (SD-JWT)", Work in Progress, Internet-
                Draft, draft-ietf-oauth-selective-disclosure-jwt-22, 2025,
                <https://datatracker.ietf.org/doc/draft-ietf-oauth-
                selective-disclosure-jwt/>.



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 39]


  Internet-Draft                environment.*                     May 2026


     [RFC1918]  Rekhter, Y., Moskowitz, B., Karrenberg, D., de Groot, G.
                J., and E. Lear, "Address Allocation for Private
                Internets", BCP 5, RFC 1918, DOI 10.17487/RFC1918,
                February 1996, <https://www.rfc-editor.org/rfc/rfc1918>.

     [RFC6982]  Sheffer, Y. and A. Farrel, "Improving Awareness of Running
                Code: The Implementation Status Section", RFC 6982,
                DOI 10.17487/RFC6982, July 2013,
                <https://www.rfc-editor.org/rfc/rfc6982>.

     [RFC7517]  Jones, M., "JSON Web Key (JWK)", RFC 7517,
                DOI 10.17487/RFC7517, May 2015,
                <https://www.rfc-editor.org/rfc/rfc7517>.

     [RFC7646]  Ebersman, P., Kumari, W., Griffiths, C., Livingood, J.,
                and R. Weber, "Definition and Use of DNSSEC Negative Trust
                Anchors", RFC 7646, DOI 10.17487/RFC7646, September 2015,
                <https://www.rfc-editor.org/rfc/rfc7646>.

     [RFC7800]  Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-
                Possession Key Semantics for JSON Web Tokens (JWTs)",
                RFC 7800, DOI 10.17487/RFC7800, April 2016,
                <https://www.rfc-editor.org/rfc/rfc7800>.

     [RFC8615]  Nottingham, M., "Well-Known Uniform Resource Identifiers
                (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
                <https://www.rfc-editor.org/rfc/rfc8615>.

     [RFC8725]  Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best
                Current Practices", BCP 225, RFC 8725,
                DOI 10.17487/RFC8725, February 2020,
                <https://www.rfc-editor.org/rfc/rfc8725>.

     [RFC8914]  Kumari, W., Hunt, E., Arends, R., Hardaker, W., and D.
                Lawrence, "Extended DNS Errors", RFC 8914,
                DOI 10.17487/RFC8914, October 2020,
                <https://www.rfc-editor.org/rfc/rfc8914>.

     [RFC9421]  Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP
                Message Signatures", RFC 9421, DOI 10.17487/RFC9421,
                February 2024, <https://www.rfc-editor.org/rfc/rfc9421>.

  Appendix A.  Reference Type Specifications

     This appendix records the constraint type specifications that have
     proposed registration in the environment.* namespace at the time of
     this document's publication.  The appendix is informative, per
     [RFC6982].



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 40]


  Internet-Draft                environment.*                     May 2026


     This appendix is intended to be removed by the RFC Editor before
     final publication, per [RFC6982], Section 2.  The version-control
     history of this document retains the appendix permanently as evidence
     of the family's running-code state during working-group review.

  A.1.  environment.market_state

     [ENVIRONMENT-MARKET-STATE] proposes environment.market_state as a
     member of the environment.* family.  The type addresses market-
     session state at a named exchange, with an attestation issued by an
     exchange-state oracle and verified against an [RFC8615] well-known
     key registry.

     The reference implementation associated with
     [ENVIRONMENT-MARKET-STATE] is documented in that specification per
     [RFC6982] in its own Implementation Status appendix; this document
     does not duplicate that content.

     Conformance to this document by [ENVIRONMENT-MARKET-STATE] at
     v0.5.11-draft covers Sections 3.1 through 3.4 (family definition and
     addition rules), Section 4.1 (family-wide fields), Section 4.2
     (field-scope taxonomy), Section 4.3 (algorithm-agility framework),
     Section 5 (family composition, including conjunction, completeness,
     and per-member diagnostic output), Section 6 (register discipline),
     and the applicable subsections of Section 7 (Security
     Considerations).

  A.2.  environment.wallet_state

     [ENVIRONMENT-WALLET-STATE] proposes environment.wallet_state as a
     member of the environment.* family.  The type addresses on-chain
     wallet state under a specified condition predicate, with an
     attestation issued by an on-chain-state attestation issuer and
     verified against an [RFC7517] JWKS.

     The reference implementation associated with
     [ENVIRONMENT-WALLET-STATE] is documented in that specification per
     [RFC6982] in its own Implementation Status appendix; this document
     does not duplicate that content.

     Conformance to this document by [ENVIRONMENT-WALLET-STATE] at
     v0.6.5-draft covers Sections 3.1 through 3.4 (family definition and
     addition rules), Section 4.1 (family-wide fields), Section 4.2
     (field-scope taxonomy), Section 4.3 (algorithm-agility framework),
     Section 5 (family composition, including conjunction, completeness,
     and per-member diagnostic output), Section 6 (register discipline),
     and the applicable subsections of Section 7 (Security
     Considerations).  [ENVIRONMENT-WALLET-STATE] additionally specifies



  Borthwick & Msebenzi    Expires 12 November 2026               [Page 41]


  Internet-Draft                environment.*                     May 2026


     cross-chain temporal consistency at its own Section 6.9; the family-
     wide implications of cross-chain temporal consistency are out of this
     document's scope and are addressed at the type-specification layer.

  A.3.  Disclaimer

     Listing in this appendix does not imply endorsement of either type
     specification by the editors of this document, by the working group,
     or by IANA.  Each type specification is independently reviewed under
     the registration process of Section 8.  Verifiers MUST independently
     verify attestations from any implementation per the verification
     algorithm of the implementation's type specification.

  Appendix B.  Reserved

     This appendix is reserved for a future revision of this document.
     Per Section 6.7 Q3, broader family-charter material — provider
     neutrality, peer-author coordination discipline, patch-level
     versioning conventions, lockstep commit patterns across sibling
     specifications, and a catalog of register-discipline instances across
     registered family members — may be consolidated under this appendix
     in a future revision, may be relocated to a separate appendix, or may
     be distributed across the relevant specification sections.  The
     choice is a working-group decision the current revision does not
     foreclose.

     This appendix is informative.

  Acknowledgments

     The authors thank the Verifiable Intent Working Group for the host
     specification on which this family-definition document depends.  The
     authors additionally acknowledge the contributors and reviewers of
     [ENVIRONMENT-MARKET-STATE] and [ENVIRONMENT-WALLET-STATE], whose
     parallel review work converged the family-wide vocabulary,
     composition discipline, and register practices that this document
     formalises.

  Authors' Addresses

     Douglas Borthwick
     InsumerAPI
     New Canaan, CT
     United States of America
     Email: douglas@insumermodel.com
     URI:   https://insumermodel.com





  Borthwick & Msebenzi    Expires 12 November 2026               [Page 42]


  Internet-Draft                environment.*                     May 2026


     Michael Msebenzi
     Headless Oracle
     Midrand
     South Africa
     Email: info@bytecraftresults.com
     URI:   https://headlessoracle.com













































  Borthwick & Msebenzi    Expires 12 November 2026               [Page 43]


name: draft-han-ai-manifest
rev: 01
title: AI Manifest: Embedded Workflow Instructions for AI Agents
time: 2026-05-15T08:57:40Z
group_uri: /api/v1/group/group/1027/
expires: 2026-11-16T08:57:40Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["Human-agent interaction", "Data formats/interop", "AI safety/alignment"]
tags: []
fetched_at: 2026-05-22T09:24:50.092745+00:00
source: ietf
abstract:
  This document specifies the AI Manifest protocol, a JSON-based format
     for websites to declare step-by-step user interface (UI) workflow
     instructions readable by autonomous AI agents.  By embedding the
     manifest, website operators allow AI agents using browser-automation
     tools to execute multi-step transactions directly via Cascading Style
     Sheets (CSS) selectors, without repeated analysis of the full
     Document Object Model (DOM).  The specification defines three
     interoperable embedding methods, a SHA-256 canonical hash
     verification procedure via a central trust registry, and security
     mitigations against prompt injection attacks.

     Empirical results from a reference implementation demonstrate an
     81.9% reduction in input tokens consumed by the AI agent and an
     increase in task success rate from 20% to 100% on a representative
     multi-step transaction, compared with conventional DOM-analysis
     approaches.

     This document also documents an empirical finding (-01 update,
     2026-04-28) that manifest embedding alone is insufficient for
     autonomous execution by modern LLM agents due to prompt-injection
     defenses in their system policies.  A deterministic execution runtime
     (referred to herein as the "SDK") is required to consume the verified
     manifest outside the LLM reasoning loop and return only the
     structured outcome to the agent.  Without such a runtime, an embedded
     manifest may produce negative value (slower than baseline) due to
     user-approval-gate latency.

     A -01 update (2026-05-15) introduces two additions.  First, the
     manifest schema is extended to the AI Friction-Recovery Manifest
     (AFRM) three-part model: frameworkHints, knownTraps (primary
     content), and shortcuts.  This aligns with the independently observed
     structure of real-world practitioner documents and with the companion
     position paper (IUI 2027).  Second, a fifth discovery mechanism is
     specified -- Method E (AI-side curation) -- in which the user places
     a manifest at a vendor-conventional file-system path (e.g.,
     ~/.claude/afrm/{domain}.json); the AI runtime loads it on domain
     match without prompt-injection screening because the file originates
     from the user's authored context.  A new trap category, native-
     dialog-trap, is also registered.

full_text:
  Independent Submission                                            W. Han
  Internet-Draft                                                Individual
  Intended status: Informational                               15 May 2026
  Expires: 16 November 2026


         AI Manifest: Embedded Workflow Instructions for AI Agents
                          draft-han-ai-manifest-01

  Abstract

     This document specifies the AI Manifest protocol, a JSON-based format
     for websites to declare step-by-step user interface (UI) workflow
     instructions readable by autonomous AI agents.  By embedding the
     manifest, website operators allow AI agents using browser-automation
     tools to execute multi-step transactions directly via Cascading Style
     Sheets (CSS) selectors, without repeated analysis of the full
     Document Object Model (DOM).  The specification defines three
     interoperable embedding methods, a SHA-256 canonical hash
     verification procedure via a central trust registry, and security
     mitigations against prompt injection attacks.

     Empirical results from a reference implementation demonstrate an
     81.9% reduction in input tokens consumed by the AI agent and an
     increase in task success rate from 20% to 100% on a representative
     multi-step transaction, compared with conventional DOM-analysis
     approaches.

     This document also documents an empirical finding (-01 update,
     2026-04-28) that manifest embedding alone is insufficient for
     autonomous execution by modern LLM agents due to prompt-injection
     defenses in their system policies.  A deterministic execution runtime
     (referred to herein as the "SDK") is required to consume the verified
     manifest outside the LLM reasoning loop and return only the
     structured outcome to the agent.  Without such a runtime, an embedded
     manifest may produce negative value (slower than baseline) due to
     user-approval-gate latency.














  Han                     Expires 16 November 2026                [Page 1]


  Internet-Draft                 AI Manifest                      May 2026


     A -01 update (2026-05-15) introduces two additions.  First, the
     manifest schema is extended to the AI Friction-Recovery Manifest
     (AFRM) three-part model: frameworkHints, knownTraps (primary
     content), and shortcuts.  This aligns with the independently observed
     structure of real-world practitioner documents and with the companion
     position paper (IUI 2027).  Second, a fifth discovery mechanism is
     specified -- Method E (AI-side curation) -- in which the user places
     a manifest at a vendor-conventional file-system path (e.g.,
     ~/.claude/afrm/{domain}.json); the AI runtime loads it on domain
     match without prompt-injection screening because the file originates
     from the user's authored context.  A new trap category, native-
     dialog-trap, is also registered.

  Status of This Memo

     This Internet-Draft is submitted in full conformance with the
     provisions of BCP 78 and BCP 79.

     Internet-Drafts are working documents of the Internet Engineering
     Task Force (IETF).  Note that other groups may also distribute
     working documents as Internet-Drafts.  The list of current Internet-
     Drafts is at https://datatracker.ietf.org/drafts/current/.

     Internet-Drafts are draft documents valid for a maximum of six months
     and may be updated, replaced, or obsoleted by other documents at any
     time.  It is inappropriate to use Internet-Drafts as reference
     material or to cite them other than as "work in progress."

     This Internet-Draft will expire on 16 November 2026.

  Copyright Notice

     Copyright (c) 2026 IETF Trust and the persons identified as the
     document authors.  All rights reserved.

     This document is subject to BCP 78 and the IETF Trust's Legal
     Provisions Relating to IETF Documents (https://trustee.ietf.org/
     license-info) in effect on the date of publication of this document.
     Please review these documents carefully, as they describe your rights
     and restrictions with respect to this document.

  Table of Contents

     1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     2.  Conventions and Definitions . . . . . . . . . . . . . . . . .   4
     3.  Protocol Overview . . . . . . . . . . . . . . . . . . . . . .   4
       3.1.  Embedding Methods . . . . . . . . . . . . . . . . . . . .   4




  Han                     Expires 16 November 2026                [Page 2]


  Internet-Draft                 AI Manifest                      May 2026


         3.1.1.  Method A: Well-Known URI  . . . . . . . . . . . . . .   5
         3.1.2.  Method B: Hidden DOM Element  . . . . . . . . . . . .   5
         3.1.3.  Method C: HTTP Response Header  . . . . . . . . . . .   5
         3.1.4.  Method D: HTML Link Element . . . . . . . . . . . . .   5
         3.1.5.  Method E: AI-Side Curation  . . . . . . . . . . . . .   6
       3.2.  Manifest Schema (AFRM Three-Part Model) . . . . . . . . .   6
       3.3.  Agent Detection Algorithm . . . . . . . . . . . . . . . .   7
       3.4.  Canonical Hash and Trust Verification . . . . . . . . . .   7
       3.5.  Execution . . . . . . . . . . . . . . . . . . . . . . . .   8
     4.  Central Trust Registry  . . . . . . . . . . . . . . . . . . .   8
     5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
       5.1.  Well-Known URI Registration . . . . . . . . . . . . . . .   8
       5.2.  AI Manifest Actions Registry (initial)  . . . . . . . . .   9
       5.3.  AI Manifest Trap Categories Registry (initial)  . . . . .   9
       5.4.  Link Relation Type Registration . . . . . . . . . . . . .  10
     6.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
       6.1.  Prompt Injection Risk . . . . . . . . . . . . . . . . . .  10
       6.2.  Interaction with LLM Agent Prompt Injection Defenses  . .  10
       6.3.  Integrity of the Manifest . . . . . . . . . . . . . . . .  11
       6.4.  Transport Security  . . . . . . . . . . . . . . . . . . .  11
     7.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  12
     8.  Implementation Status . . . . . . . . . . . . . . . . . . . .  12
     9.  Intellectual Property Rights Disclosure . . . . . . . . . . .  13
     10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . .  13
     11. Normative References  . . . . . . . . . . . . . . . . . . . .  13
     Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  14

  1.  Introduction

     Large Language Model (LLM)-based AI agents increasingly interact with
     web services via browser-automation protocols such as the Model
     Context Protocol (MCP), Playwright, Puppeteer, and Selenium
     WebDriver.  Current agents typically parse entire DOM trees or
     screenshots on every page to infer UI structure, producing three
     well-known problems:

     1.  Substantial token consumption due to repeated analysis of large
         DOMs on every session.

     2.  High failure rates on complex multi-step transactional UIs such
         as enterprise resource planning (ERP) systems, academic
         manuscript submission portals, and government e-services.

     3.  Absence of a standardized mechanism for a website operator to
         declare an AI-agent-friendly ("AI-Ready") operational surface.






  Han                     Expires 16 November 2026                [Page 3]


  Internet-Draft                 AI Manifest                      May 2026


     Related prior work includes robots.txt, llms.txt, agents.txt, and ai-
     plugin.json.  These address crawling permissions, LLM-friendly
     documentation, agent capability declarations, and API-level
     integration respectively.  None provides step-by-step UI workflow
     instructions for multi-page transactional flows.

     AI Manifest fills this gap by specifying a JSON format that
     enumerates ordered UI operations keyed to CSS selectors.  An AI agent
     detects, parses, and verifies the manifest before executing the
     listed steps, and avoids further DOM-based inference for those steps.

  2.  Conventions and Definitions

     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
     "SHOULD", "SHOULD NOT", "RECOMMENDED", "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.

     AI Manifest  A structured data object, expressed in JSON, that a
        website operator embeds into a web page or serves at a well-known
        URI, containing at minimum a task identifier, an ordered steps
        array, and for each step an action field and a CSS selector.

     AI Agent  A software process, typically driven by an LLM, that
        accesses a web page via a browser-automation tool and executes
        actions on behalf of a human user.

     Central Trust Registry  A network service that stores SHA-256 hash
        values of manifests pre-registered by publishers, and responds to
        real-time trust lookups from AI agents with a status of white-
        listed, black-listed, or unknown.

     Canonical Form  The representation of an AI Manifest obtained by
        lexicographically sorting all JSON object keys at every nesting
        level and serializing the result using the JSON encoding defined
        in [RFC8259] with UTF-8.

  3.  Protocol Overview

  3.1.  Embedding Methods

     A website MAY provide an AI Manifest via one or more of the following
     methods:







  Han                     Expires 16 November 2026                [Page 4]


  Internet-Draft                 AI Manifest                      May 2026


  3.1.1.  Method A: Well-Known URI

     The server SHOULD make the manifest retrievable at the following
     well-known URI [RFC8615]:

       /.well-known/ai-manifest.json

     In addition, the HTML document SHOULD declare the entry point via an
     HTML meta element:

       <meta name="ai-manifest"
             content="/.well-known/ai-manifest.json">

  3.1.2.  Method B: Hidden DOM Element

     The server MAY embed the manifest into the HTML response as a hidden
     element with the display:none style and aria-hidden="true" attribute:

       <div id="ai-manifest" style="display:none" aria-hidden="true"
            data-manifest='{"version":"1.0", ... }'></div>

  3.1.3.  Method C: HTTP Response Header

     The server MAY declare the manifest location and hash in a response
     header:

       X-AI-Manifest: url=/.well-known/ai-manifest.json;
                      hash=sha256:<hex>

     Method C is RECOMMENDED in conjunction with Method A, so that an AI
     agent can discover the manifest URL and validate the hash in a single
     request-response round trip before fetching the body.

  3.1.4.  Method D: HTML Link Element

     The server MAY declare the manifest via an HTML link element in the
     document head:

     <link rel="ai-manifest" href="/.well-known/ai-manifest.json">

     Method D allows AI agents that parse the DOM but do not inspect HTTP
     headers to discover the manifest location.  The rel value ai-manifest
     is registered in Section 5.4.








  Han                     Expires 16 November 2026                [Page 5]


  Internet-Draft                 AI Manifest                      May 2026


  3.1.5.  Method E: AI-Side Curation

     A user MAY place a manifest at a vendor-conventional path in their
     own file system, for example ~/.claude/afrm/{domain}.json or
     ~/.codex/afrm/{domain}.json.  The AI runtime loads the file when it
     visits a matching domain.  Because the manifest originates from the
     user's authored context, it enters the agent's trust context without
     the prompt-injection screening applied to externally fetched data.

     When both an AI-side curated manifest and a site-side published
     manifest exist for the same origin, the curated manifest SHOULD take
     precedence as the more explicit trust signal.

     Method E is a transitional mechanism intended for domains that have
     not yet published a site-side AFRM.  Once the site publishes its own
     manifest, the AI-side copy SHOULD be retired or used only to override
     individual fields.

  3.2.  Manifest Schema (AFRM Three-Part Model)

     An AI Friction-Recovery Manifest (AFRM) is a JSON object [RFC8259]
     with the following top-level fields:

     version (string, REQUIRED)  Specification version.  This document
        defines version "1.0".

     publisher (string, REQUIRED)  Canonical domain name of the publishing
        website.

     manifestId (string, REQUIRED)  Stable identifier scoped to the
        publisher, used for registry lookup.

     registry_url (string, REQUIRED)  HTTPS URL of the trust registry that
        the publisher has pre-registered this manifest with.

     frameworkHints (object, OPTIONAL)  Metadata about the UI framework in
        use (e.g., framework name, version, rendering model).  Allows the
        AI agent to apply framework-specific heuristics before
        encountering friction.

     knownTraps (array, REQUIRED)  Primary content of the AFRM.  An
        ordered array of trap descriptors, each describing a UI pattern
        that predictably blocks autonomous AI agents.  Each element MUST
        include trapId (string), category (string from the IANA trap
        registry, see Section 5), selector (string), and escapeAction
        (string).  Optional fields include description and condition.

     shortcuts (array, OPTIONAL)  An array of direct navigation or action



  Han                     Expires 16 November 2026                [Page 6]


  Internet-Draft                 AI Manifest                      May 2026


        shortcuts that allow the AI agent to bypass multi-step UI flows
        when a direct API or deep-link equivalent exists.

  3.3.  Agent Detection Algorithm

     Upon loading a page, an AI agent implementing this specification
     SHOULD perform the following detection sequence before any full-DOM
     inference pass:

     1.  Check the agent's local file system for a user-curated manifest
         at the vendor-conventional path (e.g., ~/.claude/
         afrm/{domain}.json) matching the current origin (Method E).  If
         found, load it into the trust context and continue; the site-side
         steps below may still be consulted for supplementary data.

     2.  Inspect the HTTP response headers for X-AI-Manifest (Method C).

     3.  If absent, retrieve /.well-known/ai-manifest.json (Method A) or
         resolve the URI declared by the meta element.

     4.  If still absent, check the document head for a <link rel="ai-
         manifest"> element and fetch the referenced URL (Method D).

     5.  If still absent, search the DOM for an element with id="ai-
         manifest" and read its data-manifest attribute (Method B).

     6.  If none is found, fall back to conventional DOM-based inference.

  3.4.  Canonical Hash and Trust Verification

     Prior to execution, the AI agent MUST compute a SHA-256 hash over the
     canonical form (see Section 2) of the manifest and send a trust
     lookup request to the URI in the registry_url field.  The request
     MUST use HTTPS [RFC2818] and MUST carry the tuple {publisher,
     manifestId, hash} as a JSON body.

     The registry response is a JSON object containing a status field with
     one of the following values:

     *  "white" — the manifest is trusted; the agent MAY proceed to
        execution.

     *  "black" — the manifest is explicitly distrusted; the agent MUST
        abort and SHOULD alert the human user.

     *  "unknown" — the manifest is not registered; the agent SHOULD warn
        the user and MAY fall back to DOM-based inference.




  Han                     Expires 16 November 2026                [Page 7]


  Internet-Draft                 AI Manifest                      May 2026


     Implementations MAY cache a non-expired registry response keyed by
     the manifest hash, to avoid repeated network round trips for an
     identical manifest.

  3.5.  Execution

     When trust is confirmed, the agent executes the steps array in
     declared order, mapping each step's action and selector to a browser-
     automation primitive (e.g. "click", "fill", "select", "upload").  For
     the duration of a manifest-driven execution the agent SHOULD NOT
     perform additional LLM-based inference over the page DOM.

  4.  Central Trust Registry

     A Central Trust Registry accepts manifest registrations from
     publishers and answers real-time hash lookups from AI agents.  A
     conforming registry SHOULD:

     *  Store the SHA-256 hash of the canonical form of each registered
        manifest, together with the publisher and manifestId fields.

     *  Perform static analysis on the submitted steps array and reject or
        black-list manifests whose selectors or actions match a published
        pattern of prompt-injection risk (for example, selectors targeting
        iframe elements for cross-origin form submission, or actions
        outside the registered action set).

     *  Expose a community-driven mechanism for reporting and black-
        listing malicious manifests.

     This document does not mandate a specific registry operator.
     Multiple interoperable registries MAY exist, and each manifest
     declares which registry is authoritative for it via registry_url.

  5.  IANA Considerations

  5.1.  Well-Known URI Registration

     This document requests IANA to register the following entry in the
     "Well-Known URIs" registry established by [RFC8615]:

     URI Suffix:  ai-manifest.json

     Change Controller:  Independent Submission Stream editor

     Reference:  This document

     Status:  provisional



  Han                     Expires 16 November 2026                [Page 8]


  Internet-Draft                 AI Manifest                      May 2026


     Related Information:  None

  5.2.  AI Manifest Actions Registry (initial)

     This document requests IANA to create a new registry named "AI
     Manifest Actions", with the following initial registrations.
     Registration policy: Specification Required [RFC8126].

     click  Invoke a click event on the selected element.

     fill  Type a value into a text input element.

     select  Choose an option from a drop-down list element.

     upload  Attach a file to a file input element.

     wait  Pause for a condition or duration.

     navigate  Change the current URL.

     assert  Verify that a condition holds before proceeding.

  5.3.  AI Manifest Trap Categories Registry (initial)

     This document requests IANA to create a new registry named "AI
     Manifest Trap Categories", with the following initial registrations.
     Registration policy: Specification Required [RFC8126].

     shadow-dom-trap  A UI component rendered inside a Shadow DOM tree
        whose selectors are not accessible via standard
        document.querySelector calls.

     virtual-scroll-trap  A list or grid that renders only a visible
        viewport window, requiring programmatic scrolling before off-
        screen items can be targeted.

     iframe-context-trap  An action target located inside a cross-origin
        or same-origin <iframe> that requires a context-switch before
        interaction.

     native-dialog-trap  A browser-native modal dialog (invoked via
        window.alert(), window.confirm(), or window.prompt()) that freezes
        the renderer event loop until dismissed.  An AI agent must call
        the appropriate WebDriver dismiss or accept command rather than
        attempting a DOM interaction, which will block indefinitely.

     delayed-render-trap  A UI element that does not appear in the DOM




  Han                     Expires 16 November 2026                [Page 9]


  Internet-Draft                 AI Manifest                      May 2026


        until after an asynchronous operation completes; the agent must
        wait for the element's visibility predicate before acting.

  5.4.  Link Relation Type Registration

     This document requests IANA to register the following entry in the
     "Link Relations" registry established by [RFC8288]:

     Relation Name:  ai-manifest

     Description:  Refers to an AI Friction-Recovery Manifest (AFRM) that
        describes known UI traps, framework hints, and interaction
        shortcuts for the current origin, to assist autonomous AI agents.

     Reference:  This document

  6.  Security Considerations

  6.1.  Prompt Injection Risk

     A malicious website could embed an AI Manifest whose steps array
     leads an AI agent to perform actions harmful to the user (for
     example, submitting a form to a third party with user-supplied
     credentials).  The Central Trust Registry mechanism (Section 4) is
     the primary mitigation.  Agents MUST NOT execute a manifest whose
     registry lookup returns "black" and SHOULD warn the user before
     executing an "unknown" manifest.

  6.2.  Interaction with LLM Agent Prompt Injection Defenses

     Modern Large Language Model (LLM) agents (including but not limited
     to Claude, ChatGPT, and Gemini) implement prompt-injection defense as
     an immutable system-level policy.  Such policy treats web-page-
     embedded content that contains executable instructions, including AI
     Manifests, as untrusted external data and requires explicit user
     approval prior to execution.

     Empirical study by the author (2026-04-28) on a representative
     enterprise multi-step UI (one trial per condition) compared three
     configurations:

     *  Tier A — Native page without manifest: 97.7 seconds total wall-
        clock to task completion;








  Han                     Expires 16 November 2026               [Page 10]


  Internet-Draft                 AI Manifest                      May 2026


     *  Tier B — Embedded manifest with the LLM agent processing the
        manifest directly: 154.7 seconds, due to user-approval gate
        latency.  The agent in this trial classified the manifest content
        as a prompt-injection pattern and reverted to manual page
        navigation, defeating the manifest's intent;

     *  Tier C — Embedded manifest with a deterministic runtime (SDK)
        consuming the manifest outside the LLM reasoning loop: 5.0
        seconds, with no user-approval interruption.

     Implications:

     *  Manifest embedding alone (Method B without a runtime) SHOULD NOT
        be relied upon as a complete automation surface; in practice it
        may produce negative value due to repeated user-approval prompts.

     *  Implementations SHOULD pair the manifest with a deterministic
        runtime that performs discovery, registry verification, static
        analysis, and step execution outside the LLM context, returning
        only a structured success/failure summary to the LLM.

     *  Externally-referenced manifests (Method A, /.well-known/) avoid
        prompt-injection-defense triggering when the runtime fetches the
        manifest out-of-band, although they require additional HTTP round-
        trips.

     This finding does not alter the protocol on the wire but informs
     deployment patterns and the role of the runtime component vis-a-vis
     the LLM agent.

  6.3.  Integrity of the Manifest

     The SHA-256 hash is computed over the canonical form of the manifest
     so that semantically equivalent encodings produce identical digests.
     Implementations MUST NOT rely on a hash computed over non-canonical
     bytes.

  6.4.  Transport Security

     All communication with the registry MUST use HTTPS with server
     authentication per [RFC2818].  Registry operators SHOULD sign their
     responses with a public key published out of band so that an AI agent
     can verify the integrity of a cached response.








  Han                     Expires 16 November 2026               [Page 11]


  Internet-Draft                 AI Manifest                      May 2026


  7.  Privacy Considerations

     Registry lookups necessarily expose to the registry operator the fact
     that a particular AI agent has visited a particular publisher's
     manifest.  Registry operators SHOULD minimize the retention of client
     identifiers associated with lookup requests.  Agents MAY employ
     private, time-limited caching of registry responses to reduce the
     frequency of such lookups.

  8.  Implementation Status

     Note to RFC Editor: This section is intended to be removed prior to
     publication as an RFC.

     A reference implementation, including an example publisher server, a
     reference registry, two AI agent variants (DOM-analysis baseline and
     manifest-aware), and an automated benchmark harness, is available at
     https://github.com/11pyo/AINavManifest under the MIT License.

     In the reference benchmark — a two-step ERP order-entry transaction
     repeated 30 times with input tokens counted via the tiktoken
     cl100k_base encoding — the manifest-aware agent consumed an average
     of 341 input tokens per task with a 100% task success rate (30 of 30
     runs), while the DOM-analysis baseline consumed an average of 1887.6
     input tokens with a 20% success rate (6 of 30 runs).  Raw results
     accompany the reference implementation.

     A subsequent three-tier comparison study (2026-04-28, one trial per
     condition) used a representative enterprise approval UI ("IRIS-style
     vacation request") and the same LLM (Claude) across the three
     configurations described in Section 6.2.  Wall-clock results: Tier A
     (native, no manifest) 97.7 s; Tier B (manifest embedded, processed by
     the LLM directly) 154.7 s; Tier C (manifest embedded plus
     deterministic SDK runtime) 5.0 s.  Tier C achieved approximately a
     19-fold speedup over Tier A and a 31-fold speedup over Tier B.  The
     surprising Tier-B-slower-than-Tier-A result is attributed to the LLM
     agent rejecting the embedded manifest as a possible prompt-injection
     pattern and reverting to manual navigation, consistent with LLM
     safety policy.

     A controlled experiment (Phase 1, n=30 trials, 2026-04-28) examined
     whether an AI agent spontaneously detects and loads a site-side AFRM
     during routine task execution without explicit user instruction.  The
     primary hypothesis (H1: manifest_detected fires at least once during
     30 trials) was rejected: the event was never observed.  This result
     confirms that a deterministic SDK runtime, not unaided LLM inference,
     is required to achieve reliable manifest consumption.  All eight pre-
     registered secondary hypotheses (H2-H8, covering token reduction,



  Han                     Expires 16 November 2026               [Page 12]


  Internet-Draft                 AI Manifest                      May 2026


     task-completion rate, and step-accuracy metrics conditioned on
     successful detection) were accepted with large effect sizes (Cohen's
     d = 5.00 for token reduction in the SDK condition).  Raw data and
     analysis scripts accompany the reference implementation.

     A cross-AI interoperability study (Phase 2, 2026-05-11) tested
     whether three major LLM agents (Claude, ChatGPT, Gemini) can consume
     an AFRM presented directly in a conversation context.  Results:
     Claude correctly extracted and applied the AFRM content (trap
     descriptors, selectors, escape actions) when the manifest was
     provided in-context; ChatGPT demonstrated label-level recognition
     (identified the document as an AFRM) but did not apply individual
     trap entries procedurally; Gemini returned generic speculation
     without manifest-specific extraction.  These results suggest that
     AFRM consumption at the level of individual knownTraps entries is not
     yet uniform across LLM agents, further motivating the deterministic
     SDK runtime architecture specified in this document.

  9.  Intellectual Property Rights Disclosure

     The technology described in this document is the subject of Korean
     Patent Application No. 10-2026-0071716, filed on 2026-04-21 by the
     author.  The applicant commits to offer any essential claims under
     Fair, Reasonable, and Non-Discriminatory (FRAND) terms to
     implementers of this specification, as declared in the project
     repository.

  10.  Acknowledgments

     The author thanks the Anthropic Claude Code, Model Context Protocol,
     and OpenAI function-calling communities for the empirical
     observations that motivated this work.

  11.  Normative References

     [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/info/rfc2119>.

     [RFC2818]  Rescorla, E., "HTTP Over TLS", RFC 2818,
                DOI 10.17487/RFC2818, May 2000,
                <https://www.rfc-editor.org/info/rfc2818>.

     [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
                Writing an IANA Considerations Section in RFCs", BCP 26,
                RFC 8126, DOI 10.17487/RFC8126, June 2017,
                <https://www.rfc-editor.org/info/rfc8126>.



  Han                     Expires 16 November 2026               [Page 13]


  Internet-Draft                 AI Manifest                      May 2026


     [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/info/rfc8174>.

     [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
                Interchange Format", STD 90, RFC 8259,
                DOI 10.17487/RFC8259, December 2017,
                <https://www.rfc-editor.org/info/rfc8259>.

     [RFC8615]  Nottingham, M., "Well-Known Uniform Resource Identifiers
                (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
                <https://www.rfc-editor.org/info/rfc8615>.

     [RFC8288]  Nottingham, M., "Web Linking", RFC 8288,
                DOI 10.17487/RFC8288, October 2017,
                <https://www.rfc-editor.org/info/rfc8288>.

  Author's Address

     Won-pyo Han
     Individual
     Korea, Republic of
     Email: pk102h@naver.com




























  Han                     Expires 16 November 2026               [Page 14]


name: draft-vandemeent-iddrop
rev: 00
title: IDDrop: Identity Drop and Acceptance Protocol
time: 2026-05-18T04:36:20Z
group_uri: /api/v1/group/group/1027/
expires: 2026-11-19T04:36:20Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["Agent identity/auth", "Data formats/interop", "Human-agent interaction"]
tags: []
fetched_at: 2026-05-22T09:24:50.092750+00:00
source: ietf
abstract:
  This document specifies IDDrop, an identity-transfer protocol for
     moving identity claims, actor claims, and receiver-bound claim
     bundles across human-facing and machine-facing environments.

     IDDrop defines two complementary operating modes: offer-first,
     intended for proximity and human-in-the-loop workflows, and request-
     first, intended for autonomous systems, daemon-to-daemon exchange,
     and policy-driven machine identity transfer.

     IDDrop does not treat filenames or user-visible extensions as
     identity truth.  Instead, it binds identity transfer to sealed
     carrier truth, semantic classification, actor provenance, receiver
     targeting, and causal validation.  This document profiles the generic
     TIBET TAT handoff model for trustworthy identity transfer.

full_text:
  Internet Engineering Task Force                          J. van de Meent
  Internet-Draft                                                  Humotica
  Intended status: Standards Track                             17 May 2026
  Expires: 18 November 2026


               IDDrop: Identity Drop and Acceptance Protocol
                         draft-vandemeent-iddrop-00

  Abstract

     This document specifies IDDrop, an identity-transfer protocol for
     moving identity claims, actor claims, and receiver-bound claim
     bundles across human-facing and machine-facing environments.

     IDDrop defines two complementary operating modes: offer-first,
     intended for proximity and human-in-the-loop workflows, and request-
     first, intended for autonomous systems, daemon-to-daemon exchange,
     and policy-driven machine identity transfer.

     IDDrop does not treat filenames or user-visible extensions as
     identity truth.  Instead, it binds identity transfer to sealed
     carrier truth, semantic classification, actor provenance, receiver
     targeting, and causal validation.  This document profiles the generic
     TIBET TAT handoff model for trustworthy identity transfer.

  Status of This Memo

     This Internet-Draft is submitted in full conformance with the
     provisions of BCP 78 and BCP 79.

     Internet-Drafts are working documents of the Internet Engineering
     Task Force (IETF).  Note that other groups may also distribute
     working documents as Internet-Drafts.  The list of current Internet-
     Drafts is at https://datatracker.ietf.org/drafts/current/.

     Internet-Drafts are draft documents valid for a maximum of six months
     and may be updated, replaced, or obsoleted by other documents at any
     time.  It is inappropriate to use Internet-Drafts as reference
     material or to cite them other than as "work in progress."

     This Internet-Draft will expire on 18 November 2026.

  Copyright Notice

     Copyright (c) 2026 IETF Trust and the persons identified as the
     document authors.  All rights reserved.




  van de Meent            Expires 18 November 2026                [Page 1]


  Internet-Draft                   IDDrop                         May 2026


     This document is subject to BCP 78 and the IETF Trust's Legal
     Provisions Relating to IETF Documents (https://trustee.ietf.org/
     license-info) in effect on the date of publication of this document.
     Please review these documents carefully, as they describe your rights
     and restrictions with respect to this document.  Code Components
     extracted from this document must include Revised BSD License text as
     described in Section 4.e of the Trust Legal Provisions and are
     provided without warranty as described in the Revised BSD License.

  Table of Contents

     1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
     3.  Protocol Overview . . . . . . . . . . . . . . . . . . . . . .   4
     4.  Offer-First Mode  . . . . . . . . . . . . . . . . . . . . . .   4
     5.  Request-First Mode  . . . . . . . . . . . . . . . . . . . . .   4
     6.  Validation Rules  . . . . . . . . . . . . . . . . . . . . . .   5
     7.  Semantic Classification . . . . . . . . . . . . . . . . . . .   5
     8.  Security Considerations . . . . . . . . . . . . . . . . . . .   6
     9.  Transport and Carrier Bindings  . . . . . . . . . . . . . . .   6
       9.1.  Relationship to CEP and TAT . . . . . . . . . . . . . . .   6
     10. Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .   6
       10.1.  Human NFC Offer  . . . . . . . . . . . . . . . . . . . .   7
       10.2.  System Request . . . . . . . . . . . . . . . . . . . . .   7
     11. Normative References  . . . . . . . . . . . . . . . . . . . .   7
     12. Informative References  . . . . . . . . . . . . . . . . . . .   7
     Appendix A.  Minimal JSON Shapes  . . . . . . . . . . . . . . . .   7
     Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   8

  1.  Introduction

     Identity transfer in distributed systems is frequently
     underspecified.  Systems often know how to transport bytes, but not
     how to safely transfer the meaning of an identity claim.

     Existing encrypted transport systems provide confidentiality and
     integrity for byte carriage, but they do not by themselves answer
     whether the transferred object is an identity claim at all, whether
     the claim was expected or solicited, whether the visible name matches
     sealed semantics, whether the claim is bound to a known actor
     registry, or whether the response belongs to a known causal request
     chain.

     IDDrop fills this gap by defining a protocol for identity drop,
     acceptance, and validation across both human and system lanes.






  van de Meent            Expires 18 November 2026                [Page 2]


  Internet-Draft                   IDDrop                         May 2026


     This document is intended as an identity-transfer profile over the
     more general TIBET TAT transfer substrate and within the broader
     Continuity Envelope Protocol (CEP) model.

     The key design principle is simple: identity MUST NOT arrive as a
     surprise commitment.

  2.  Terminology

     The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
     "SHOULD", "SHOULD NOT", "RECOMMENDED", "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.

     IDDrop  The protocol specified in this document for identity offer,
        request, response, validation, and acceptance.

     Offer  A temporary, visible, non-binding identity availability
        signal.

     Request  An explicit solicitation by a receiver for a specific claim
        or identity response.

     Response  A sealed and receiver-bound identity-carrying answer to
        either an accepted offer or a request.

     Acceptance  An explicit receiver-side act indicating consent to
        proceed from discovery into sealed identity transfer.

     Materialization  The act of committing a validated identity claim
        into a receiver runtime, registry, or operator-visible state.

     Carrier Truth  The byte-level truth established by sealed carrier
        properties such as magic bytes, authenticated encryption,
        signatures, and receiver binding.

     Semantic Class  The declared object class of a transfer unit, such as
        identity, code, document, command, or receipt.

     Causal Binding  The linkage between a request, offer acceptance, and
        later response, such that the receiver can verify that the
        identity answer belongs to a known prior step.








  van de Meent            Expires 18 November 2026                [Page 3]


  Internet-Draft                   IDDrop                         May 2026


  3.  Protocol Overview

     IDDrop operates across three conceptual planes: Discovery Plane,
     Sealed Transfer Plane, and Commitment Plane.  Systems implementing
     IDDrop MUST NOT collapse these planes into a single implicit step.

     IDDrop defines two operating modes:

     *  offer-first, for human, proximity, NFC, QR, and local discovery
        workflows

     *  request-first, for daemon, automation, cap-bus, and machine-to-
        machine workflows

  4.  Offer-First Mode

     Offer-first mode is intended for NFC handoff, QR handoff, local
     discovery, AirDrop-like experiences, and home-agent or human-
     supervised device exchange.

     The offer-first flow is:

     1.  sender enables a temporary offer

     2.  receiver discovers offer metadata

     3.  receiver chooses accept, challenge, or reject

     4.  if accepted, sender performs sealed transfer to receiver

     5.  receiver validates the claim

     6.  receiver MAY materialize the claim

     An offer SHOULD contain at least `offer_id`, `expires_at`,
     `sender_pubkey`, `claimed_aint`, `claim_class`, `semantic_type`,
     `display_name`, `preview_hash`, and `ssm_class`.

     Offer metadata MUST NOT be treated as commitment truth.

  5.  Request-First Mode

     Request-first mode is intended for daemon-to-daemon exchange, cap-bus
     identity requests, relay and automation lanes, and policy-driven
     system exchange.

     The request-first flow is:




  van de Meent            Expires 18 November 2026                [Page 4]


  Internet-Draft                   IDDrop                         May 2026


     1.  receiver emits a request

     2.  request carries `request_id` and `challenge_nonce`

     3.  sender creates a receiver-bound response

     4.  receiver validates request/response linkage

     5.  receiver MAY materialize the claim

     A request SHOULD contain at least `request_id`, `challenge_nonce`,
     `requested_claim_type`, `receiver_pubkey`, `requested_aint`,
     `causal_parent`, and `expires_at`.

  6.  Validation Rules

     The following six validation rules are REQUIRED.

     1.  *Carrier Truth*: the receiver MUST verify carrier truth before
         trusting object bytes.

     2.  *Semantic Class*: the receiver MUST determine the semantic class
         of the object before commitment.  Byte validity alone is
         insufficient.

     3.  *Receiver Binding*: the receiver MUST verify that the response is
         bound to the intended receiver.  A response not addressed to the
         receiver MUST be rejected.

     4.  *Claim Provenance*: the receiver MUST validate the claim against
         a provenance source such as AINS, JIS, or an equivalent actor
         registry.

     5.  *Causal Binding*: in request-first mode, the receiver MUST
         validate that the response belongs to the prior request by
         checking `request_id`, `challenge_nonce`, and any causal parent
         references.  In offer-first mode, the receiver MUST validate that
         acceptance and later transfer belong to the same offer session.

     6.  *Commitment Discipline*: the receiver MUST NOT materialize or
         register an identity claim before Rules 1 through 5 have
         succeeded.

  7.  Semantic Classification

     Implementations SHOULD distinguish at least the following semantic
     classes: identity, code, document, command, and receipt.




  van de Meent            Expires 18 November 2026                [Page 5]


  Internet-Draft                   IDDrop                         May 2026


     Implementations MUST NOT use filename extension alone as semantic
     truth.

  8.  Security Considerations

     IDDrop forbids surprise identity commitment.  Offer-first mode is
     safe only if offers remain temporary and non-binding until explicit
     acceptance and later validation.  Request-first mode establishes
     intent and causal context, but the receiver MUST still validate the
     response and its provenance.

     Implementations MUST treat user-visible names and extensions as
     advisory surfaces only.  A man-in-the-middle or misleading sender MAY
     present a visually similar claim name.  Provenance validation and
     receiver binding are REQUIRED to defeat such confusion.

     Offers and requests SHOULD carry expiries.  Responses SHOULD be bound
     to active requests or active acceptances to limit replay.

  9.  Transport and Carrier Bindings

     IDDrop is transport-agnostic.  It MAY be carried over NFC, QR-
     assisted local handoff, local network discovery, message relay, and
     cap-bus or command-substrate lanes.

     When a sealed carrier is used, implementations SHOULD use a receiver-
     bound confidential carrier format rather than raw opaque payload
     carriage.

  9.1.  Relationship to CEP and TAT

     IDDrop is not intended to redefine generic handoff mechanics.

     CEP defines the umbrella continuity messaging model, TAT defines the
     generic consent-bound handoff and transfer flow, and IDDrop defines
     the identity-transfer profile over that flow.

     When a TAT implementation is available, IDDrop SHOULD use it as the
     preferred transfer and anchoring substrate.

  10.  Examples










  van de Meent            Expires 18 November 2026                [Page 6]


  Internet-Draft                   IDDrop                         May 2026


  10.1.  Human NFC Offer

     A user enables identity offer mode for 60 seconds on a device.
     Another device taps via NFC, sees the claim metadata and sender
     fingerprint, and explicitly accepts.  The sender then transfers a
     receiver-bound sealed response, which the receiver validates against
     AINS/JIS before materialization.

  10.2.  System Request

     A daemon requests an identity claim for a specific actor and embeds a
     nonce and request identifier.  The sender responds with a sealed,
     receiver-bound response referencing the original request.  The
     receiver validates the request linkage and provenance before
     continuing the workflow.

  11.  Normative References

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

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

  12.  Informative References

     [AINS]     van de Meent, J., "AINS Discovery", 2026.

     [JIS]      van de Meent, J., "JIS Identity", 2026.

     [SSM]      van de Meent, J., "TIBET Semantic Surface Manifest", 2026.

     [CEP]      van de Meent, J., "Continuity Envelope Protocol", 2026.

     [TAT]      van de Meent, J., "TIBET TAT: Touch-and-Transfer
                Protocol", 2026.

     [UPIP]     van de Meent, J., "UPIP: Universal Process Integrity
                Protocol", 2026.

  Appendix A.  Minimal JSON Shapes








  van de Meent            Expires 18 November 2026                [Page 7]


  Internet-Draft                   IDDrop                         May 2026


     {
       "offer": {
         "offer_id": "offer-123",
         "expires_at": "2026-05-17T10:00:00Z",
         "sender_pubkey": "hex...",
         "claimed_aint": "jasper.aint",
         "semantic_type": "identity"
       },
       "request": {
         "request_id": "req-456",
         "challenge_nonce": "nonce-789",
         "receiver_pubkey": "hex...",
         "requested_claim_type": "identity"
       },
       "response": {
         "request_id": "req-456",
         "sender_pubkey": "hex...",
         "receiver_pubkey": "hex...",
         "claimed_aint": "jasper.aint",
         "semantic_type": "identity",
         "provenance_ref": "ains:..."
       }
     }

  Author's Address

     Jasper van de Meent
     Humotica
     Netherlands
     Email: info@humotica.com
     URI:   https://humotica.com/




















  van de Meent            Expires 18 November 2026                [Page 8]


name: draft-kuehlewind-audit-architecture
rev: 00
title: An Architecture for Auditing AI Agent Delegation and Interactions
time: 2026-05-18T21:14:05Z
group_uri: /api/v1/group/group/1027/
expires: 2026-11-19T21:14:05Z
states: ["/api/v1/doc/state/1/", "/api/v1/doc/state/150/"]
categories: ["Policy/governance", "Agent identity/auth", "Autonomous netops"]
tags: []
fetched_at: 2026-05-22T09:24:50.092762+00:00
source: ietf
abstract:
  This document describes an architecture for auditing of agent-driven
     interactions on the Internet.  Autonomous and semi-autonomous
     software agents, including those based on artificial intelligence,
     increasingly act on behalf of users, organizations, and services.
     Existing auditing mechanisms often capture isolated system events but
     do not consistently represent delegation relationships, user intent,
     or evolving authorization.  In agent-driven systems, auditability
     requires linking intent, delegation, authorization, and execution.
     The proposed architecture enables this through distributed audit
     record generation, propagation of audit context, optional
     attestation, and additonal logging for transparency.

full_text:
  Network Working Group                                      M. Kuehlewind
  Internet-Draft                                                  Ericsson
  Intended status: Informational                               H. Birkholz
  Expires: 19 November 2026                                 Fraunhofer SIT
                                                               18 May 2026


     An Architecture for Auditing AI Agent Delegation and Interactions
                   draft-kuehlewind-audit-architecture-00

  Abstract

     This document describes an architecture for auditing of agent-driven
     interactions on the Internet.  Autonomous and semi-autonomous
     software agents, including those based on artificial intelligence,
     increasingly act on behalf of users, organizations, and services.
     Existing auditing mechanisms often capture isolated system events but
     do not consistently represent delegation relationships, user intent,
     or evolving authorization.  In agent-driven systems, auditability
     requires linking intent, delegation, authorization, and execution.
     The proposed architecture enables this through distributed audit
     record generation, propagation of audit context, optional
     attestation, and additonal logging for transparency.

  Discussion Venues

     This note is to be removed before publishing as an RFC.

     Source for this draft and an issue tracker can be found at
     https://github.com/mirjak/draft-audit-architecture.

  Status of This Memo

     This Internet-Draft is submitted in full conformance with the
     provisions of BCP 78 and BCP 79.

     Internet-Drafts are working documents of the Internet Engineering
     Task Force (IETF).  Note that other groups may also distribute
     working documents as Internet-Drafts.  The list of current Internet-
     Drafts is at https://datatracker.ietf.org/drafts/current/.

     Internet-Drafts are draft documents valid for a maximum of six months
     and may be updated, replaced, or obsoleted by other documents at any
     time.  It is inappropriate to use Internet-Drafts as reference
     material or to cite them other than as "work in progress."

     This Internet-Draft will expire on 19 November 2026.




  Kuehlewind & Birkholz   Expires 19 November 2026                [Page 1]


  Internet-Draft         Agent Auditing Architecture              May 2026


  Copyright Notice

     Copyright (c) 2026 IETF Trust and the persons identified as the
     document authors.  All rights reserved.

     This document is subject to BCP 78 and the IETF Trust's Legal
     Provisions Relating to IETF Documents (https://trustee.ietf.org/
     license-info) in effect on the date of publication of this document.
     Please review these documents carefully, as they describe your rights
     and restrictions with respect to this document.  Code Components
     extracted from this document must include Revised BSD License text as
     described in Section 4.e of the Trust Legal Provisions and are
     provided without warranty as described in the Revised BSD License.

  Table of Contents

     1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
       1.1.  Relationship to Other IETF Work . . . . . . . . . . . . .   4
     2.  Motivating Use Cases  . . . . . . . . . . . . . . . . . . . .   5
       2.1.  Financial Transactions by Agents  . . . . . . . . . . . .   5
       2.2.  Long-Running Autonomous Agents  . . . . . . . . . . . . .   5
       2.3.  Everyday Agent Interaction  . . . . . . . . . . . . . . .   6
       2.4.  Data Sharing and User Trust . . . . . . . . . . . . . . .   6
     3.  Architectural Overview  . . . . . . . . . . . . . . . . . . .   6
       3.1.  Audit Records and Context . . . . . . . . . . . . . . . .   7
       3.2.  Attestation Model . . . . . . . . . . . . . . . . . . . .   8
       3.3.  Identity Substrate  . . . . . . . . . . . . . . . . . . .   8
     4.  Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . .   9
       4.1.  Principle Agent Interaction Actors  . . . . . . . . . . .   9
       4.2.  Auditing Services . . . . . . . . . . . . . . . . . . . .  10
       4.3.  Auditor . . . . . . . . . . . . . . . . . . . . . . . . .  11
       4.4.  Role Aggregation  . . . . . . . . . . . . . . . . . . . .  11
     5.  Record Types  . . . . . . . . . . . . . . . . . . . . . . . .  11
     6.  Potential Work Items  . . . . . . . . . . . . . . . . . . . .  12
     7.  Illustrative Audit Record Examples  . . . . . . . . . . . . .  14
       7.1.  Audit Context in an Access Token  . . . . . . . . . . . .  15
       7.2.  Action Record . . . . . . . . . . . . . . . . . . . . . .  15
       7.3.  Delegation Record . . . . . . . . . . . . . . . . . . . .  16
       7.4.  Authorization Transition Record . . . . . . . . . . . . .  17
     8.  Security Considerations . . . . . . . . . . . . . . . . . . .  17
     9.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  18
     10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  19
     11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  19
       11.1.  Normative References . . . . . . . . . . . . . . . . . .  19
       11.2.  Informative References . . . . . . . . . . . . . . . . .  21
     Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  22





  Kuehlewind & Birkholz   Expires 19 November 2026                [Page 2]


  Internet-Draft         Agent Auditing Architecture              May 2026


  1.  Introduction

     Autonomous and semi-autonomous software agents based on large
     language models (LLMs) and similar non-deterministic systems are
     deployed to take consequential actions on behalf of users and
     organizations.  These agents interact across administrative and trust
     domains, delegate tasks and authority to other agents or tools, and
     initiate consequential actions without per-step human oversight.  The
     question of whether the recorded actions of an agent faithfully
     represent what the agent actually did has acquired new urgency.

     Autonomous agents may run long-lived workflows without tight user
     interaction or may be very short-lived, e.g. for a delegated sub-
     tasks.  Agents may be authenticated to several services, request
     step-up approval from a human, spawn further sub-agents, and produc
     records that long outlive its own process.  Existing auditing
     mechanisms often capture isolated system events but do not
     consistently represent delegation relationships, user intent, or
     evolving authorization.  In agent-driven systems, auditability
     requires linking intent, delegation, authorization, and execution.

     This document describes an architecture that enables this form of
     auditing through three layers: - distributed audit record generation
     by each participant, - propagation of audit context across protocol
     interactions, and - optional attestation and independent third-party
     logging for transparency that provides verifiable assurances about
     the content and origin of records.

     The architecture in this document identifies roles and their duties,
     describes the classes of interaction that must be audited, and
     discusses an example data model to make audits interoperable across
     vendors, domains, and time.

     Two principles frame the rest of this document:

     1.  Agents participate in _two distinct classes of interaction_ that
         must each be auditable: user-facing interactions (prompts,
         approvals, human-in-the-loop confirmations) and system-facing
         interactions (API calls, tool invocations, delegation to other
         agents or services).  Effective auditing requires linking user
         intent to resulting system actions across protocol and
         administrative boundaries.

     2.  Unlike traditional delegated workflows in which authorization
         transitions are explicit and predefined, AI agent systems
         introduce dynamic, fine-grained authorization changes that arise
         during execution and are driven by agent decisions, sub-agent
         delegation, and human interaction.  Auditing must therefore



  Kuehlewind & Birkholz   Expires 19 November 2026                [Page 3]


  Internet-Draft         Agent Auditing Architecture              May 2026


         capture authorization as a _time-evolving state_ and must
         correlate transitions across interactions and domains by
         maintaining common context.

  1.1.  Relationship to Other IETF Work

     The architecture is designed to compose existing IETF building blocks
     to make verifiable what these layers already do rather than
     redefining them.

     Remote attestation follows RATS [RFC9334] supplies the environmental
     evidence of the record's origin: RATS Evidence, Attestation Results,
     and Endorsements are reused verbatim as the vocabulary for
     environmental claims about audit-record producers.

     Transparency follows SCITT [I-D.ietf-scitt-architecture]that makes a
     record's existence later un-deniable: SCITT Signed Statements,
     Receipts, and Transparent Statements are the canonical artifacts, and
     SCITT-compatible Transparency Services are the canonical substrate
     for non-repudiable custody.

     The Verifiable Agent Conversations data model
     [I-D.birkholz-verifiable-agent-conversations] could be utilizd as an
     Interaction Record.

     HTTP may be used as the transport mechanism for conveying audit
     context alongside requests.  JSON-based formats, including JWT and
     COSE, can proide representations for audit records and attestations,
     along with mechanisms for cryptographic protection.

     Authority and delegation are based on by OAuth 2.0 [RFC6749], Token
     Exchange [RFC8693], Transaction Tokens
     [I-D.ietf-oauth-transaction-tokens], Identity Chaining
     [I-D.ietf-oauth-identity-chaining], Identity Assertion Authorization
     Grants [I-D.ietf-oauth-identity-assertion-authz-grant], RAR
     [RFC9396], attestation-based client authentication
     [I-D.ietf-oauth-attestation-based-client-auth], DPoP [RFC9449],
     Status Lists [I-D.ietf-oauth-status-list], and SPIFFE client
     authentication [I-D.ietf-oauth-spiffe-client-auth].

     Workload identity follows WIMSE [I-D.ietf-wimse-arch], which this
     document specializes for AI Agents.

     The three principal acting roles as described in the next section and
     shown in Figure 1 have parallel counterparts in OAuth and WIMSE; a
     deployment may use both.  The following table shows a simple mapping:





  Kuehlewind & Birkholz   Expires 19 November 2026                [Page 4]


  Internet-Draft         Agent Auditing Architecture              May 2026


     | Actor View (this document) | OAuth view [RFC6749] | WIMSE view
     [I-D.ietf-wimse-arch] | |---|---|---| | User | Resource Owner |
     Principal of a run; may also be a Workload in machine-only runs | |
     AI Agent | OAuth Client | Workload (with sub_profile=ai_agent)
     presenting a Workload Identity Credential | | External Service /
     Tool | Resource Server | Service-side Workload or external endpoint
     of another Trust Domain |

     The auditing layer adds the cross-layer artifacts (audit records and
     context, agent interaction records, attestation references, and
     transparency receipts) that turn isolated layer events into a
     verifiable audit trail.

  2.  Motivating Use Cases

     The need for interoperable auditing of agent-driven systems arises
     from both regulatory requirements and user trust expectations.  The
     following examples highlight scenarios where traditional logging is
     insufficient and where an explicit auditing architecture for agents
     provides value.

     The proposed auditing architecture provides traceability of data
     access and enables reconstruction of the full chain from user intent
     to execution, including the full delegation chain that might change
     dynamically and authorization decisions, providing the desired
     verifiable audit trail suitable for compliance and review.

  2.1.  Financial Transactions by Agents

     Agents may execute financial operations such as payments or
     procurement actions on behalf of users, often involving multiple
     systems.  Regulatory frameworks (e.g., SOX, PSD2) require that
     transactions be attributable, authorized, and auditable.

     Traditional logs typically capture only execution events (e.g.,
     “payment executed”), without clearly linking them to user intent,
     approvals, or delegation steps.  This makes it difficult to verify
     whether actions were properly authorized.

  2.2.  Long-Running Autonomous Agents

     Some agents operate continuously over extended periods, making
     decisions and performing actions based on changing conditions.  For
     example, a procurement agent may manage ordering and inventory over
     days or weeks.  In such scenarios, authorization evolves over time
     due to policy changes, approvals, or context-dependent decisions.
     Delegation paths may also change dynamically.




  Kuehlewind & Birkholz   Expires 19 November 2026                [Page 5]


  Internet-Draft         Agent Auditing Architecture              May 2026


  2.3.  Everyday Agent Interaction

     Even simple consumer use cases benefit from improved auditing.  For
     example, an assistant may book a restaurant on behalf of a user by
     selecting a venue and interacting with a booking service.  If the
     result is unexpected, traditional logs provide limited insight into
     how the decision was made or which services were involved.

  2.4.  Data Sharing and User Trust

     Agents often access and share (sensitive) user data with external
     services.  For example, an assistant may send a user’s address to a
     delivery provider.  Without detailed auditing, it is difficult to
     verify what data was accessed, what was shared, and with whom.
     Unintended disclosure can undermine user trust.

  3.  Architectural Overview

     Figure 1 shows a high level end-to-end view of the proposed
     architecture: three principal acting roles produce records about
     their own behaviour.  These records flow into supporting services
     that store, attest, and expose them to consumers that can verify
     their authenticity and provenance.

     +---------------+        +---------------+        +---------------+
     |     User      |        |   AI Agent    |        |   External    |
     |               +------->+               +------->+   Services /  |
     +---------------+        +---------------+        |   Tools       |
              |                        |               +---------------+
              |                        |                       |
              v                        v                       v
        Interaction Records     Agent Records           Service Records
              |                        |                       |
              +------------------------+-----------------------+
                                       |
                                       v
            +--------------------------+---------------------------+
            |                   Auditing Service                   |
            |  +--------------+  +--------------+  +------------+  |
            |  |  Attestation |  |   Audit      |  |Transparency|  |
            |  |              |  |   Store      |  |Log         |  |
            |  +--------------+  +--------------+  +------------+  |
            +------------------------------------------------------+
                                       |
                                       v
                     +-----------------+-------------------+
                     |    Audit Consumers / Verifiers      |
                     +-------------------------------------+



  Kuehlewind & Birkholz   Expires 19 November 2026                [Page 6]


  Internet-Draft         Agent Auditing Architecture              May 2026


        Figure 1: Roles view: principal acting roles, auditing services,
                     and the records that flow among them.

     The proposed architecture enables interoperable auditing of agent-
     driven interactions by combining distributed audit record generation,
     audit context propagation, and optional attestation and transparency
     logging.  Audit information is produced by multiple actors operating
     across administrative domains and is later reconstructed and
     validated by audit consumers through a shared audit context and may
     be accompanied by attestations.

     Audit records are generated distributively.  Each principal acting
     role (user, agent, service/tool) records its own behaviour rather
     than relying on a central observer.  These records are linked via a
     propagated audit context with a coherent trail: Interaction Records
     flow are generated by the User; Action and Delegation Records flowby
     the Agent; Service Records flow by external Services/Tools.  Each
     actor may produce mutiple records to, e.g., audit actions,
     delegation, or authorization changes.  Distributed record generation
     limits the trust placed in any single point.  Two trust mechanisms
     are composed (attestation and transparency logging).  An auditing
     system may select either, both, or neither according to the strength
     of evidence its Auditors require.

     The auditing services (Attestation, Audit Store, and Transparency
     Log) are distinct from the interaction and authorization layers that
     drives the three acting roles.  They can be or need to be operated by
     different parties dependeing on trust requirements of auditor.
     Attestations may be directly provided by the producer or supplied on
     request by an Attestation Service.  An Audit Store canonicalises
     observable agent signals into the records and exposes them to Audit
     Consumers and Verifiers.  The Store is logically distinct from the
     Agent it records, because an agent that records itself can produce
     useful telemetry but cannot, by itself, deliver non-repudiation to a
     third party.  Transparency receipts provided by the Transparency Log
     are embedded in or referenced from the records.

  3.1.  Audit Records and Context

     Audit records are generated independently by participating actors and
     reflect different perspectives of an interaction.  User-facing
     systems produce records capturing intent, such as prompts or
     approvals.  Agents produce records describing decisions, actions, and
     delegation steps.  Services produce records reflecting execution
     outcomes.






  Kuehlewind & Birkholz   Expires 19 November 2026                [Page 7]


  Internet-Draft         Agent Auditing Architecture              May 2026


     These records are linked through a shared audit context that is
     propagated across protocol interactions.  This context carries
     identifiers such as a trace identifier and references to prior
     events, enabling reconstruction of a causal chain.  It also carries
     identity information, including the acting entity and, where
     applicable, the entity on whose behalf the action is performed.

     Transport mechanisms such as HTTP are used for propagating this
     context, for example via headers or message metadata.  Existing
     approaches such as W3C's trace context propagation can serve as a
     basis but require extension to include identity, delegation, and
     authorization state.  As such, correlation is not performed by a
     centralized component.  Instead, it emerges from consistent use of
     shared identifiers and structures across all participants.

  3.2.  Attestation Model

     Audit records may include attestation evidence that provides
     verifiable assurances about their content.  An attestation binds a
     statement to a cryptographic identity and allows relying parties to
     validate claims about events, delegation, or execution.

     Attestations are generated at or on behalf of the entity asserting a
     claim and are associated with audit records at creation time.
     Attestation can have different levels of assurance, depending on the
     type of origin (ranging from self-assertions to RATS evidence).  An
     agent or service may self-attest its actions using mechanisms such as
     JSON Web Signatures or COSE-based signatures.  In other cases, the
     producer interacts (taking on the role of a RATS Attester) with an
     external remote attestation service (i.e., a RATS Verifier) to obtain
     an additional statement (an Attestation Result).

     Further, the transparency service may attest that a record has been
     recorded in an append-only log.  And the audit store may provide
     additional attestations, such as timestamping or proof of inclusion.
     But this does not replace attestations generated by record producers.

  3.3.  Identity Substrate

     An AI Agent is treated as a specialisation of a Workload
     [I-D.ietf-wimse-arch], with a Workload Identifier
     [I-D.ietf-wimse-identifier] scoped within a Trust Domain and a
     Workload Identity Credential (e.g., a WIT
     [I-D.ietf-wimse-workload-creds]) bound to a key the workload
     generates and retains.  The credential is never a bearer token and is
     normally short-lived.  For auditing it is benefical if an Agent also
     carries a role profile (per [I-D.mcguinness-oauth-actor-profile]'s
     sub_profile convention) so that downstream parties can distinguish an



  Kuehlewind & Birkholz   Expires 19 November 2026                [Page 8]


  Internet-Draft         Agent Auditing Architecture              May 2026


     AI-driven Workload from a human-operated client or a traditional
     service.  The role-profile vocabulary is the subject of a separate
     specification (WI-2 in Section 6).

  4.  Roles

     A role is a function, not a deployment unit.  The same entity may
     take on several roles.

  4.1.  Principle Agent Interaction Actors

     The User is the human or organisation on whose behalf an Agent acts.
     Where the User is a natural person they are also the OAuth Principal
     of the run: the sub of any token issued for the run and the original
     authorizing party in any delegation chain.  On the audit layer the
     User's duty is to issue intent in a verifiable form--prompt,
     approval, or signed grant--and to respond to step-up escalations.

     An AI Agent is a Workload [I-D.ietf-wimse-arch] whose behaviour is
     driven, in whole or in part, by a non-deterministic decision process
     (typically an LLM).  Agents operate within the authorization they
     were issued, propagate the upstream Principal's identity and the
     delegation context unmodified except where an exchange explicitly
     authorises a change, and emit observable signals, such as prompts,
     actions, tool calls, sub-agent invocations, terminations, that an
     Audit Store can canonicalise.  Where an Agent signs records itself,
     it signs with a key bound to its Workload Identity Credential, never
     with a long-lived shared key.  A Sub-Agent is an Agent invoked by
     another Agent rather than directly by a User.  This distinction is
     positional and not categorical.  A Sub-Agent receives a downscoped
     authorization, represented in the delegation chain, and re-binds the
     chain on outbound calls so downstream Services can attribute the call
     correctly and trace back to the parent.

     A Tool is co-located with or directly invocable from an Agent runtime
     (filesystem, shell, sandbox, function call).  A Service is a remote
     workflow reached via a network protocol.  A Resource Server provides
     an access service to an authorization-protected resource.  All three
     enforce the Agent's presented authorization at the point of effect
     and emit per-request records bound to the Agent's Workload Identity
     Credential.  Those records reflect the canonical request as observed
     at the boundary, not as reported by the Agent.









  Kuehlewind & Birkholz   Expires 19 November 2026                [Page 9]


  Internet-Draft         Agent Auditing Architecture              May 2026


  4.2.  Auditing Services

     The Auditing Service canonicalises observable records (Interaction,
     Action, Delegation, Authorization Transition), signs them with a key
     bound to its own identity, and submits them for registration with a
     Transparency Log before they leave the operational environment.  The
     Auditing Service is logically distinct from the User, Agent, or Tool
     it records: the architecture's accountability properties require
     either an independent Auditing Service.

     The Audit Store is a generic role of storing audit records after they
     have been produced.  Substrates range from append-only databases and
     SIEM-fed log stores to fully transparent registries.  Deployment
     requires only availability of records may use any type of Audit Store
     implementation.

     Attestation binds a record to the operational state of the
     environment in which it was produced.  A record may carry inline
     Evidence about that environment, an Attestation Result derived from
     that Evidence by a Verifier, or a stable reference to either, and the
     resulting record carries a verifiable claim about _what was running_
     and _in what configuration_ when the recorded action took place.
     Remote Attestation is the architecture's principal candidate for
     producing records that are authentic in this sense.  RATS [RFC9334]
     is the canonical instance.

     The Transparency Log binds a record to an append-only, non-
     equivocating statement sequence.  Once a Transparency Log has issued
     a receipt for a signed statement, the record's existence and content
     at registration time can no longer be denied, and no Auditor with
     read access can be presented with an inconsistent view of the
     history.  Transparency is the architecture's principal mechanism for
     producing records that are non-repudiable in this sense.  SCITT
     [I-D.ietf-scitt-architecture] is the canonical instance.

     Attestation and transparency answer different questions: attestation
     answers "is this record authentic?", transparency answers "did this
     record exist as claimed?".  They compose freely as a record may carry
     attestation evidence and be transparently registered, and the
     resulting receipt then binds that combination immutably.











  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 10]


  Internet-Draft         Agent Auditing Architecture              May 2026


  4.3.  Auditor

     The Auditor consumes Interaction, Action, Delegation, and
     Authorization Transition Records together with the receipts that bind
     them, and determines whether recorded behaviour matched the User's
     intent and the authorization in force at the time and, where
     appropriate, whether the recorded evidence supports or contradicts a
     claim of compliance.  The Auditor is not required to trust the Agent:
     the entire point of the architecture is to make the Agent itself the
     auditable object.

  4.4.  Role Aggregation

     An entity can assume one or more roles.  An Agent's host process may
     also implement the Audit Recorder role for that Agent.  Doing so
     simplifies deployment but introduces recorder-collusion threats that
     the architecture mitigates by either an independent Recorder or non-
     repudiable registration with a Transparency Service.  An Auditor can
     be operated by an organisation distinct from the one operating the
     Recorder, the Transparency Service, the Auditing Service, or the
     Agent.  The architecture's requirements apply across role boundaries
     even when those roles are co-located.

  5.  Record Types

     This document proposes an initial set of four record types for agent
     auditing:

     Interaction Records:  capture user-facing events (prompts, model
        responses, instructions, approvals, refusals) and agent-to-agent
        dialogue treated as conversation.

     The Verifiable Agent Conversations data model
     [I-D.birkholz-verifiable-agent-conversations] is the principal
     candidate format for the user-Agent dialogue subtype.

     Human-in-the-loop escalations, like step-up approvals, refusals, or
     the rarer case of an action that should have been escalated but was
     not, appear as identifiable records bindable to the run's Interaction
     Record.

     Action Records:  capture system-facing events at the boundary where
        the action took effect.

     An Action Record may carry inline Evidence, an Attestation Result, or
     a stable reference to either; where Evidence is unavailable, that
     absence is itself an audit-relevant fact and can be recorded.




  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 11]


  Internet-Draft         Agent Auditing Architecture              May 2026


     Delegation Records:  capture the assignment of authority from one
        entity to another,e.g., delegator, delegatee, scope, and
        constraints on use.

     Authorization delegation records are used to audit which authority is
     transmitted along the chain from User through Agent through Sub-Agent
     to Tool or Service.  Across that chain, the record remains append-
     only, meaning no actor removes or reorders prior actors.  Any cross-
     domain transition is recorded with enough fidelity that an Auditing
     Service on either side can make sense of it without access to the
     other side's pipeline.

     Authorization Transition Records:  capture changes in permission
        state over time: initial grants, step-up approvals, scope
        narrowing on exchange, revocation, and expiry.

     Authorization is considered as a time-evolving state.  The ordered
     sequence of Authorization Transition Records of a run reconstructs
     the authorization in force at any point within it.

     Concrete illustrative shapes for each are given in Section 7.  The
     four classes of records share a common correlation identifier in the
     Audit Context (see Section 7.1 and WI-11), so that a User's stated
     intent and an Agent's executed action remain linkable across protocol
     and administrative boundaries.

     Consequential records are attested by an in-device or third-party
     service, stored in the Audit Store for retrival by an authorized
     auditor, and registered with a Transparency Service before they leave
     the operational environment, or as soon as network conditions permit.

  6.  Potential Work Items

     The following work items are proposed for potential specifications
     that support this architecture:

     *  *WI-1: Audit Data Models and Semantics.* The canonical structure
        of Interaction, Action, Delegation, and Authorization Transition
        Records (Section 5), encoded in at least one IETF-recognised
        serialisation (CBOR/COSE or JSON/JWS) with support for detached
        payloads, and carrying actor identity unambiguously across User,
        Agent, Sub-Agent, Tool, and Service.

     *  *WI-2: Delegation-Chain Wire Profile.* Specify both a
        Cryptographic Delegation Chain carried in token bodies (nested act
        per [RFC8693]; acti/actc candidates from
        [I-D.mw-oauth-actor-chain]) as well as a Tracing Delegation Chain
        (a flat, lightweight Actor sequence suitable for audit context,



  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 12]


  Internet-Draft         Agent Auditing Architecture              May 2026


        HTTP headers, and standalone records) with a defined
        reconciliation path between them.  This item includes a
        representation for cross-domain transitions, and a sub_profile
        [I-D.mcguinness-oauth-actor-profile] vocabulary that distinguishes
        AI Agent, Sub-Agent, Tool, Service, and Human.

     *  *WI-3: Interaction Record Profile.* A canonical Interaction Record
        format for prompts, responses, instructions, approvals, refusals,
        tool-invocation traces, reasoning traces (where exposed by the
        model), and system events, potentially with an identifiable HITL
        subtype and a registration profile compatible with SCITT.
        [I-D.birkholz-verifiable-agent-conversations] is the principal
        candidate for the User-Agent dialogue subtype.  This work item
        does not preclude additional profiles for non-conversational
        interactions, such as network device interaction.

     *  *WI-4: Action Record Profile.* A canonical Action Record produced
        at the boundary where each tool or service call took effect, bound
        to its parent Interaction Record via SC-2/SC-11 tracing
        identifiers, to its authorizing Token, and (when available) to the
        Attestation Result for the executing environment.  Distinguishes
        the Recorder's signing identity from the recorded Agent's identity
        where the two are operationally separated.

     *  *WI-5: HITL Escalation Signalling.* Communication of step-up
        requests from Agent to User and the User's response, e.g.,
        approval, refusal, or timeout, in a form auditable end-to-end and
        bindable to the resulting authorization state.

     *  *WI-6: Profile of RATS Evidence.* How Evidence is referenced from
        Interaction and Action Records using [RFC9334]'s encoding-agnostic
        Conceptual Messages, and how Attestation Results derived from such
        Evidence are consumed by Identity Issuance Authorities, Services,
        and Auditors.

     *  *WI-7: Profile of SCITT Transparency.* A Registraton Policy
        profile of [I-D.ietf-scitt-architecture] for auditing records--
        admissible Issuers (Agents, Sub-Agents, Recorders) and required
        payload media types--and a Receipt presentation profile permitting
        Auditors to verify non-repudiation independently of any single
        Transparency Service.

     *  *WI-8: Authorization Transition Encoding.* A canonical
        Authorization Transition Record format carrying previous state,
        new state, triggering event, and responsible actor (see
        Section 7.4), reusing [I-D.ietf-oauth-status-list] where the state
        is a token-status state, and replayable to reconstruct
        authorization in force at any timestamp within a run.



  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 13]


  Internet-Draft         Agent Auditing Architecture              May 2026


     *  *WI-9: Auditor-Facing Query Interface.* An optional specialised
        query profile over the Audit Store and Transparency Log, surfacing
        records by session, workflow, principal, agent, tool, or time
        range, with authorization and privacy controls.

     *  *WI-10: Deployment and Operations Best Practices.* Recorder
        placement, Identity Issuance Authority configuration for ephemeral
        Workloads, Trust Domain partitioning, operational separation
        between Agent runtime and audit pipeline, and the privacy guidance
        on redaction, retention, and disclosure that Section 9 relies on.

     *  *WI-11: Audit Context Propagation Protocol Extensions.* This could
        be realized by an HTTP headers carrying the Audit Context, e.g. a
        workflow-wide Audit-Trace-ID, an immediate-redecessor Audit-
        Parent-ID, the current Audit-Actor, the upstream Audit-On-Behalf-
        Of, the SC-2 tracing chain as Audit-Delegation-Chain, and a
        reference to the current Audit-Auth-State.  Alternatively, a
        single composite Audit-Context header could be defined that
        provides the audit context embedded in OAuth token claims
        (Section 7.1).  The relationship to existing distributed-tracing
        conventions (W3C Trace Context, OpenTelemetry) need to be
        considered.

  7.  Illustrative Audit Record Examples

     This section is informative.  It illustrates the four classes of
     audit record introduced in Section 5 and the audit context introduced
     in SC-2 and SC-11 with concrete examples.  The exact field names,
     claim names, and encodings shown here are placeholders pending the
     specifications defined in SC-1 through SC-11.  They are intended to
     convey the relationships among the artifacts.

     To enable interoperability, audit records require a common structure
     that captures identity, delegation, and causal relationships.  Each
     record includes identifiers for correlation, such as a trace
     identifier and a reference to a preceding event.  It identifies the
     acting entity and may include an “on-behalf-of” identity to represent
     delegation.  The record also captures relevant authorization state,
     such as scope and validity, which may be derived from OAuth tokens or
     authorization responses.











  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 14]


  Internet-Draft         Agent Auditing Architecture              May 2026


  7.1.  Audit Context in an Access Token

     An access token or similar credential MAY include an audit claim
     carrying correlation and tracing-chain information alongside the
     conventional OAuth claims.  The cryptographic delegation chain
     remains in the OAuth act claim [RFC8693]; the audit claim carries the
     tracing-layer chain (SC-2) and the correlation identifiers used to
     link records:

     {
       "iss": "authz.example",
       "sub": "agent-42",
       "aud": "calendar.service",
       "exp": 1715674800,

       "audit": {
         "trace_id": "trace-abc",
         "parent_id": "int-001",
         "delegation_chain": ["user-123", "agent-42"]
       },

       "authorization": {
         "scope": ["calendar.write"],
         "expires_at": "2026-05-14T11:00:00Z"
       }
     }

     The same information MAY be propagated using HTTP headers (SC-11) or
     included in standalone audit records.

  7.2.  Action Record

     An Action Record produced at the boundary where a tool or service
     call took effect:

















  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 15]


  Internet-Draft         Agent Auditing Architecture              May 2026


     {
       "event_id": "act-456",
       "trace_id": "trace-abc",
       "parent_id": "int-001",
       "timestamp": "2026-05-14T10:00:00Z",
       "type": "action",

       "actor": { "type": "agent", "id": "agent-42" },
       "on_behalf_of": { "type": "user", "id": "user-123" },

       "action": {
         "type": "api_call",
         "target": "calendar.service",
         "operation": "create_event"
       },

       "delegation_chain": ["user-123", "agent-42"],

       "authorization": {
         "scope": ["calendar.write"],
         "expires_at": "2026-05-14T11:00:00Z"
       }
     }

     The parent_id references the Interaction Record that motivated the
     action.  The delegation_chain is the SC-2 tracing chain.  The
     cryptographic chain lives in the authorizing token and is not
     duplicated here.

  7.3.  Delegation Record

     A Delegation Record produced when an Agent narrows or assigns
     authority to a Sub-Agent:


















  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 16]


  Internet-Draft         Agent Auditing Architecture              May 2026


     {
       "event_id": "del-789",
       "trace_id": "trace-abc",
       "parent_id": "act-456",
       "timestamp": "2026-05-14T10:01:00Z",
       "type": "delegation",

       "delegator": { "type": "agent", "id": "agent-42" },
       "delegatee": { "type": "agent", "id": "agent-sub-1" },

       "scope": ["email.send"],

       "constraints": {
         "expires_at": "2026-05-14T10:30:00Z"
       }
     }

  7.4.  Authorization Transition Record

     An Authorization Transition Record produced when a Principal's
     authorization state changes.  This example illustrates a user
     approval:

     {
       "event_id": "auth-001",
       "trace_id": "trace-abc",
       "parent_id": "int-002",
       "timestamp": "2026-05-14T10:02:00Z",
       "type": "authorization_transition",

       "previous_state": { "scope": ["calendar.read"] },
       "new_state":      { "scope": ["calendar.read", "calendar.write"] },

       "trigger": { "type": "user_approval" },
       "actor":   { "type": "user", "id": "user-123" }
     }

     An ordered sequence of such records reconstructs the authorization
     state in force at any point in a recorded run.

  8.  Security Considerations

     The architecture's security properties are properties of the
     combination of mitigations supplied by the underlying layers (RATS,
     SCITT, WIMSE, OAuth) plus the bindings added by this architecture and
     any new potenial specification (Section 6).  No single layer suffices
     on its own.




  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 17]


  Internet-Draft         Agent Auditing Architecture              May 2026


     While the final architecture and set of specification require a
     detailed security and threat model analysis, some initial
     consideration are stated here:

     First, the Agent is _not_ trusted; the architecture is designed
     precisely for the case where the Agent's internal behaviour is the
     subject of scrutiny.

     Second, the Audit Store is only partially trusted: its records are
     corroborated by independent Service-side records and, for
     consequential actions, by registration with a Transparency Service.

     Third, neither a single Verifier nor a single Transparency Service is
     assumed sufficient: a deployment that requires defence against
     compromise of either re-appraises Evidence against independent
     Reference Values and Endorsements, registers records to multiple
     Transparency Services, and verifies mutual consistency in each case.

     The architecture does _not_ solve the case of an adversarial Service
     that refuses to record what happened at its boundary, nor the case of
     operator collusion across all roles, nor the alignment of the model
     behind the Agent.

  9.  Privacy Considerations

     Audit records of AI agent activity are intrinsically rich in
     information about the User, the User's intent, the Agent's reasoning
     trace where exposed, and the data the Agent processed in tool calls.
     As such privacy considerations are of special importance for
     auditing.

     Prompt and response content frequently contain personally
     identifiable information, confidential business information, or
     content under contractual confidentiality.  Records of this content
     registered to a Transparency Service may be visible to a broader set
     of parties than the original interlocutors.  Subsequent
     specifications (WI-3) must permit detached payloads so that the
     registered Signed Statement may carry only a hash of the
     conversation, with the content held elsewhere under deployment
     controls; WI-10 best practice need to address redaction and retention
     policies.










  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 18]


  Internet-Draft         Agent Auditing Architecture              May 2026


     The chain identifier required for cross-service correlation
     (Section 5) also enables correlation of an Agent's--and by extension
     a User's--activity across the Services it touches.  Chain identifiers
     can be encrypted to specific Auditors when the Service does not need
     to correlate itself, and pairwise per-Service identifiers
     ([I-D.johansson-direct-presentation-arch]'s pairwise pattern) could
     substitute for a single global chain identifier where correlation is
     not required.

     Tool-call outputs should be referenceable by hash rather than
     included inline in WI-4 Action Records.  Where inline inclusion is
     required, encryption to a specific Auditor should be supported.
     Receipts [I-D.ietf-scitt-architecture] bind a registration to a
     position in the Transparency Service's data structure. the fact of
     registration leaks the existence of an interaction at a time even
     when the Statement payload is hash-only.

     Where an Agent operates across organisational boundaries, the audit
     context propagated outward reveals the existence and rough size of
     the workflow (via Trace ID continuity), the identity or pseudonym of
     every Actor that participated earlier in the workflow (via the
     Tracing Delegation Chain), and the structural shape of the workflow
     (via the Parent ID graph).  These are not theoretical concerns; the
     same primitives are the basis of operational distributed-tracing
     systems where the trace stream is routinely used for capacity
     planning, account profiling, and adversarial reconnaissance.  To
     address this, the Tracing Delegation Chain could be replaced at an
     organisational boundary by an opaque identifier whose mapping is
     retained only at the originating side's Audit Store (the egress
     identity generalisation pattern of Section 3.3.8 of
     [I-D.ietf-wimse-arch]).

  10.  IANA Considerations

     This document has no IANA actions.

  11.  References

  11.1.  Normative References

     [I-D.ietf-oauth-attestation-based-client-auth]
                Looker, T., Bastian, P., and C. Bormann, "OAuth 2.0
                Attestation-Based Client Authentication", Work in
                Progress, Internet-Draft, draft-ietf-oauth-attestation-
                based-client-auth-08, 2 March 2026,
                <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
                attestation-based-client-auth-08>.




  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 19]


  Internet-Draft         Agent Auditing Architecture              May 2026


     [I-D.ietf-oauth-identity-assertion-authz-grant]
                Parecki, A., McGuinness, K., and B. Campbell, "Identity
                Assertion JWT Authorization Grant", Work in Progress,
                Internet-Draft, draft-ietf-oauth-identity-assertion-authz-
                grant-03, 22 April 2026,
                <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
                identity-assertion-authz-grant-03>.

     [I-D.ietf-oauth-identity-chaining]
                Schwenkschuster, A., Kasselman, P., Burgin, K., Jenkins,
                M. J., Campbell, B., and A. Parecki, "OAuth Identity and
                Authorization Chaining Across Domains", Work in Progress,
                Internet-Draft, draft-ietf-oauth-identity-chaining-12, 11
                May 2026, <https://datatracker.ietf.org/doc/html/draft-
                ietf-oauth-identity-chaining-12>.

     [I-D.ietf-oauth-spiffe-client-auth]
                Schwenkschuster, A., Kasselman, P., Rose, S., and S.
                Thorgersen, "OAuth SPIFFE Client Authentication", Work in
                Progress, Internet-Draft, draft-ietf-oauth-spiffe-client-
                auth-01, 2 March 2026,
                <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
                spiffe-client-auth-01>.

     [I-D.ietf-oauth-status-list]
                Looker, T., Bastian, P., and C. Bormann, "Token Status
                List (TSL)", Work in Progress, Internet-Draft, draft-ietf-
                oauth-status-list-20, 20 April 2026,
                <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
                status-list-20>.

     [I-D.ietf-oauth-transaction-tokens]
                Tulshibagwale, A., Fletcher, G., and P. Kasselman,
                "Transaction Tokens", Work in Progress, Internet-Draft,
                draft-ietf-oauth-transaction-tokens-08, 2 March 2026,
                <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
                transaction-tokens-08>.

     [I-D.ietf-scitt-architecture]
                Birkholz, H., Delignat-Lavaud, A., Fournet, C., Deshpande,
                Y., and S. Lasker, "An Architecture for Trustworthy and
                Transparent Digital Supply Chains", Work in Progress,
                Internet-Draft, draft-ietf-scitt-architecture-22, 10
                October 2025, <https://datatracker.ietf.org/doc/html/
                draft-ietf-scitt-architecture-22>.






  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 20]


  Internet-Draft         Agent Auditing Architecture              May 2026


     [I-D.ietf-wimse-arch]
                Salowey, J. A., Rosomakho, Y., and H. Tschofenig,
                "Workload Identity in a Multi System Environment (WIMSE)
                Architecture", Work in Progress, Internet-Draft, draft-
                ietf-wimse-arch-07, 2 March 2026,
                <https://datatracker.ietf.org/doc/html/draft-ietf-wimse-
                arch-07>.

     [I-D.ietf-wimse-identifier]
                Rosomakho, Y. and J. A. Salowey, "Workload Identifier",
                Work in Progress, Internet-Draft, draft-ietf-wimse-
                identifier-02, 2 March 2026,
                <https://datatracker.ietf.org/doc/html/draft-ietf-wimse-
                identifier-02>.

     [I-D.ietf-wimse-workload-creds]
                Campbell, B., Salowey, J. A., Schwenkschuster, A.,
                Sheffer, Y., and Y. Rosomakho, "WIMSE Workload
                Credentials", Work in Progress, Internet-Draft, draft-
                ietf-wimse-workload-creds-01, 5 May 2026,
                <https://datatracker.ietf.org/doc/html/draft-ietf-wimse-
                workload-creds-01>.

     [RFC6749]  Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
                RFC 6749, DOI 10.17487/RFC6749, October 2012,
                <https://www.rfc-editor.org/rfc/rfc6749>.

     [RFC8693]  Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J.,
                and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693,
                DOI 10.17487/RFC8693, January 2020,
                <https://www.rfc-editor.org/rfc/rfc8693>.

     [RFC9334]  Birkholz, H., Thaler, D., Richardson, M., Smith, N., and
                W. Pan, "Remote ATtestation procedureS (RATS)
                Architecture", RFC 9334, DOI 10.17487/RFC9334, January
                2023, <https://www.rfc-editor.org/rfc/rfc9334>.

     [RFC9396]  Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0
                Rich Authorization Requests", RFC 9396,
                DOI 10.17487/RFC9396, May 2023,
                <https://www.rfc-editor.org/rfc/rfc9396>.

     [RFC9449]  Fett, D., Campbell, B., Bradley, J., Lodderstedt, T.,
                Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of
                Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449,
                September 2023, <https://www.rfc-editor.org/rfc/rfc9449>.

  11.2.  Informative References



  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 21]


  Internet-Draft         Agent Auditing Architecture              May 2026


     [I-D.birkholz-verifiable-agent-conversations]
                Birkholz, H., Heldt, T., and O. Steele, "Verifiable Agent
                Conversation Records", Work in Progress, Internet-Draft,
                draft-birkholz-verifiable-agent-conversations-00, 25
                February 2026, <https://datatracker.ietf.org/doc/html/
                draft-birkholz-verifiable-agent-conversations-00>.

     [I-D.johansson-direct-presentation-arch]
                Johansson, L., Zundel, B., and T. Cappalli, "A reference
                architecture for direct presentation credential flows",
                Work in Progress, Internet-Draft, draft-johansson-direct-
                presentation-arch-01, 4 November 2025,
                <https://datatracker.ietf.org/doc/html/draft-johansson-
                direct-presentation-arch-01>.

     [I-D.mcguinness-oauth-actor-profile]
                McGuinness, K., "OAuth Actor Profile for Delegation", Work
                in Progress, Internet-Draft, draft-mcguinness-oauth-actor-
                profile-00, 30 April 2026,
                <https://datatracker.ietf.org/doc/html/draft-mcguinness-
                oauth-actor-profile-00>.

     [I-D.mw-oauth-actor-chain]
                Prasad, A., Krishnan, R., Lopez, D., and S. Addepalli,
                "Cryptographically Verifiable Actor Chains for OAuth 2.0
                Token Exchange", Work in Progress, Internet-Draft, draft-
                mw-oauth-actor-chain-00, 1 May 2026,
                <https://datatracker.ietf.org/doc/html/draft-mw-oauth-
                actor-chain-00>.

  Authors' Addresses

     Mirja Kuehlewind
     Ericsson
     Email: mirja.kuehlewind@ericsson.com


     Henk Birkholz
     Fraunhofer SIT
     Email: henk.birkholz@ietf.contact











  Kuehlewind & Birkholz   Expires 19 November 2026               [Page 22]


