{
  "schemaVersion": "1.0",
  "title": "Dependency graph",
  "description": "Use this page to decide where a change belongs in the reviewed Rust workspace and which lower-level contracts it may depend on. The graph groups crates by architectural responsibility so native AIP semantics do not drift into a transport, c",
  "canonical": "https://getaip.org/docs/architecture/dependency-graph",
  "route": "/docs/architecture/dependency-graph",
  "source": "docs/architecture/dependency-graph.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Architecture and Security",
  "documentType": "Architecture",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/architecture/dependency-graph.md",
    "txt": "/docs/download/architecture/dependency-graph.txt",
    "json": "/docs/download/architecture/dependency-graph.json",
    "pdf": "/docs/download/architecture/dependency-graph.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Dependency graph\ndescription: Place changes in the AIP workspace without reversing architectural ownership\nkind: explanation\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# Dependency graph\n\nUse this page to decide where a change belongs in the reviewed Rust workspace\nand which lower-level contracts it may depend on. The graph groups crates by\narchitectural responsibility so native AIP semantics do not drift into a\ntransport, compatibility profile, product connector, storage adapter, or\ndeployment binary.\n\nThe page describes version `2.0.0` of the workspace at source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`. Cargo manifests are the source\nof truth for exact direct edges. The grouped graph is a design map, not a\nreplacement for the manifests.\n\n## Read every arrow as “depends on”\n\nAn arrow points from a consumer to the lower-level crate or contract it imports.\nFor example, `aip-runtime --> aip-core` means the runtime consumes native AIP\ntypes. It does not mean that the semantic core knows how to execute an action.\n\nThe pinned direct workspace graph is acyclic. That property matters because a\nlower layer can define a stable contract without importing the process that\neventually composes it.\n\nCompile-time dependency is not the same as runtime traffic:\n\n- a binary can depend on a transport crate without enabling every listener;\n- a storage adapter depends on the traits it implements even though the runtime\n  receives the adapter through composition;\n- the public facade depends on crates selected by features, but those crates do\n  not depend back on the facade; and\n- a product host depends on one connector adapter without making that adapter a\n  dependency of the central daemon.\n\n## Follow the primary ownership layers\n\n~~~mermaid\nflowchart TB\n    P[\"Central process: getaip-server\"]\n    H[\"Six connector-host binaries\"]\n    L[\"Client and control CLI: getaip\"]\n    X[\"Shared connector-host bootstrap\"]\n    C[\"Composition: gateway, MCP edges, remote dispatch\"]\n    F[\"Fleet control: registry, admission, orchestration, lifecycle control\"]\n    S[\"Storage adapters: runtime PostgreSQL and registry PostgreSQL\"]\n    R[\"Runtime governance: lifecycle, policy, queues, connector contract\"]\n    B[\"Bindings: native transports and compatibility profiles\"]\n    D[\"Domain services: authentication, cryptography, discovery, schema\"]\n    K[\"Semantic foundation: aip-core\"]\n    A[\"Feature-gated aip facade\"]\n\n    P --> C\n    P --> F\n    P --> S\n    H --> X\n    X --> C\n    X --> F\n    X --> S\n    L --> F\n    L --> B\n    L --> D\n    C --> R\n    C --> B\n    C --> F\n    F --> R\n    F --> D\n    S --> R\n    S --> F\n    R --> D\n    R --> K\n    B --> K\n    D --> K\n    A --> C\n    A --> R\n    A --> B\n    A --> D\n    A --> K\n~~~\n\nThe text equivalent is:\n\n1. `aip-core` owns native protocol data and validation-independent semantics.\n2. Schema, cryptography, authentication, and discovery build on that semantic\n   foundation.\n3. Runtime governance and the connector contract consume those domain services\n   to validate and execute native work.\n4. Transports and compatibility profiles translate or carry protocol data\n   without becoming owners of the native lifecycle.\n5. Gateways, remote dispatch, MCP edges, and connector-host bootstrap compose\n   the runtime with selected bindings.\n6. Fleet registry, admission, orchestration, lifecycle control, and their\n   concrete storage adapters remain separate control and persistence paths.\n7. The central daemon, six product-host binaries, and the client or control CLI\n   consume different outer combinations instead of sharing one executable\n   dependency tree.\n8. The `aip` facade is a feature-gated consumer convenience layer, not a new\n   owner below those components.\n\nSome direct Cargo edges cross the visual layers. For example, a gateway imports\nauthentication and cryptography directly, while the PostgreSQL runtime adapter\nimports profile session contracts as well as runtime storage traits. Those\nedges implement a bounded responsibility; they do not transfer ownership of\nthe whole lower layer.\n\n## Keep native semantics at the foundation\n\n`aip-core` has no workspace dependency. It defines the native message model,\nidentifiers, capability and lifecycle values, errors, and validation methods\nused throughout the workspace. Its optional schema feature adds derive support;\nit does not import the schema registry, runtime, transport, or a connector.\n\n`aip-schema` consumes core types to generate and validate JSON Schema.\n`aip-crypto` and `aip-auth` consume core identities and messages for\ncryptographic and authorization decisions. `aip-discovery` consumes core and\nschema contracts to admit manifests and expose capabilities.\n\nThis direction creates a practical rule: a protocol field required across\ntransports and profiles belongs in the semantic or schema layer. It must not be\ndefined first in an HTTP route, an MCP mapping, or a product adapter and then\nleak upward through conversions.\n\n## Let runtime depend on policy contracts, not products\n\n`aip-runtime` depends on authentication, cryptography, discovery, schema, the\nproduct-neutral connector registry contract, and core. It owns action\ngovernance, lifecycle state, queues, approvals, transactions, delegations,\ncallbacks, and recovery.\n\nThe runtime has no dependency on any of the six maintained product adapters,\nconnector-host binaries, compatibility servers, or deployment processes.\nProduct behavior reaches the runtime only through an admitted action handler or\nthe tenant-scoped remote catalog and remote handler.\n\n`aip-connector` depends on core, discovery, and runtime because it defines the\nconnector-facing implementation contract, credential boundary, and lifecycle\nintegration. Product adapters depend on that contract. Reversing this edge\nwould make generic execution depend on a particular provider.\n\n## Keep bindings parallel to lifecycle\n\n`aip-transport` defines native transport abstractions over core messages.\nProtocol-specific transport crates implement HTTP, NATS, SSE, or WebSocket\nbindings by depending on that abstraction and the core model.\n\nCompatibility profiles map foreign semantics into native AIP. MCP client and\nserver packages depend on the MCP profile and session contracts; the MCP server\nalso composes the gateway. The gateway itself does not depend on the MCP\nprofile. This keeps the native action lifecycle usable without importing an MCP\nserver.\n\nThe A2A profile is a gateway dependency for its bounded native integration.\nThat compile-time edge does not mean every gateway deployment exposes an A2A\nendpoint.\n\nProfiles and transports may depend on native semantics. Native lifecycle code\nmust not depend on a wire listener or a foreign protocol mapping to decide what\nan action, approval, transaction, or result means.\n\n## Compose at the gateway boundary\n\n`aip-gateway` combines trusted ingress, replay protection, identity\nresolution, query authorization, runtime dispatch, remote delegation, and\ncallbacks. It consumes the runtime, generic connector contract, selected native\ntransport abstractions, and the profile support it directly owns.\n\nThe gateway is still a library. Listener construction and deployment\nconfiguration belong to an executable or embedding application. A new listener\ntherefore depends on the gateway; the gateway should not import the process\nthat starts it.\n\nThe remote connector package implements the runtime's catalog and handler\nextension points using the connector registry and gateway peer clients. The\ncentral daemon depends on this product-neutral path and does not import the six\nproduct implementations.\n\n## Separate fleet control from provider execution\n\nFleet packages divide authority rather than forming one large connector crate:\n\n| Package responsibility | Depends on | Must remain independent of |\n|---|---|---|\n| Registry contract | Core, cryptography, and discovery definitions | Product API clients and host processes |\n| Admission | Registry contract, cryptography, discovery, and core | Process startup and provider execution |\n| Orchestration contract | Admission and registry contracts | Deployment-platform implementation details |\n| Registry PostgreSQL adapter | Registry and admission-owned storage contracts | Runtime product execution |\n| Connector host | Gateway, runtime, connector contract, registry views, and bounded transport support | Selection of another tenant or connector instance |\n| Host bootstrap | Host composition, trusted peer setup, and complete runtime storage | Product-specific capability implementation |\n| Lifecycle control process | Host lifecycle and registry control contracts | Catalog admission authority and provider credentials |\n| Product host binary | Shared bootstrap plus exactly one maintained adapter | Central daemon composition |\n\nThe concrete storage and process crates sit outside the contracts they\nimplement. Their Cargo arrows point inward because dependency inversion lets a\nruntime or control service accept an implementation without importing a\nspecific database or executable.\n\n## Put storage outside the state owner\n\n`aip-storage-postgres` depends on runtime storage traits and constructs a\ncomplete shared-durability store bundle. The runtime does not depend on\nPostgreSQL. It can instead receive the in-memory, local file, or another\ncontract-compatible bundle.\n\nThe registry PostgreSQL adapter follows the same pattern for fleet catalog,\nroute, admission-journal, lease, and control state. A database schema can\noptimize and coordinate those records, but it does not become the owner of\ntheir protocol meaning.\n\nThis direction allows storage replacement without moving authorization,\nlifecycle, or routing rules into SQL-specific callers.\n\n## Treat binaries and the facade as outer consumers\n\n`getaip-server` is the central product-neutral server composition. It depends on the\ngateway, runtime, shared storage, remote connector path, profiles, and\ntransports needed for its configured surfaces. It does not depend on the six\nproduct adapters.\n\nEach maintained connector-host executable combines shared host bootstrap with\none product adapter. That is the intended point where provider-specific code\nenters an executable dependency tree.\n\n`getaip` is a client, conformance, release-admission, and fleet-operation\nsurface. It imports the contracts and transports needed for those tasks, but\ndoes not embed the gateway or become part of server action execution.\n\nThe `aip` crate is a feature-gated facade. Enabling one of its features makes\nthe selected lower-level crate available to that consumer. It does not create a\nreverse edge, prove that a binary enables the feature, or make every optional\ncomponent part of the core protocol.\n\n## Place a change by its owner\n\n| Change | Start in | Add outward dependencies only when |\n|---|---|---|\n| Native message field or invariant | `aip-core` and schema coverage | Bindings need serialization or mapping |\n| Signature or principal rule | Cryptography or authentication | Gateway composition must invoke the decision |\n| Manifest or capability admission | Discovery | Runtime or fleet admission must enforce it |\n| Action lifecycle or recovery rule | Runtime | Gateway, storage, or operators must expose it |\n| Transport encoding or listener behavior | Transport implementation or process | It calls the stable gateway boundary |\n| Foreign protocol mapping | Corresponding profile | Client or server adapters need that mapping |\n| Generic connector execution contract | `aip-connector` | Maintained adapters implement it |\n| Product operation | One maintained adapter and its host | Public connector docs expose the mapping |\n| Fleet route or release rule | Registry, admission, or orchestration contract | Adapter and process implement the contract |\n| Database coordination | Concrete storage adapter | The owning service accepts it through a trait |\n| Command or daemon wiring | `getaip`, `getaip-server`, or host binary | No lower layer imports the executable |\n\nWhen a proposed lower-level crate needs a type from a higher-level process,\nfirst ask whether the type is actually a missing semantic contract. Moving that\nsmall contract inward is usually safer than introducing a reverse dependency.\n\n## Interpret the graph narrowly\n\nCargo metadata proves compile-time edges at the reviewed revision. It does not\nprove runtime enablement, network reachability, production qualification,\nfeature selection, storage durability, or provider availability.\n\nThe graph deliberately omits third-party dependencies, development-only tools,\nqualification packages, and exact edges that do not change architectural\nownership. Add or remove a direct workspace dependency in Cargo first, then\nupdate this map when the ownership path changes.\n\n## Related pages\n\n- [Architecture overview](overview.md)\n- [Runtime](runtime.md)\n- [Gateway](gateway.md)\n- [Connector fleet architecture](connector-fleet.md)\n- [Transport bindings](../reference/transport-bindings.md)\n",
    "text": "Dependency graph\n\nUse this page to decide where a change belongs in the reviewed Rust workspace\nand which lower-level contracts it may depend on. The graph groups crates by\narchitectural responsibility so native AIP semantics do not drift into a\ntransport, compatibility profile, product connector, storage adapter, or\ndeployment binary.\n\nThe page describes version 2.0.0 of the workspace at source revision\nd7cce13d1d555644d04a4d73c66c95b113737635. Cargo manifests are the source\nof truth for exact direct edges. The grouped graph is a design map, not a\nreplacement for the manifests.\n\nRead every arrow as “depends on”\n\nAn arrow points from a consumer to the lower-level crate or contract it imports.\nFor example, aip-runtime --> aip-core means the runtime consumes native AIP\ntypes. It does not mean that the semantic core knows how to execute an action.\n\nThe pinned direct workspace graph is acyclic. That property matters because a\nlower layer can define a stable contract without importing the process that\neventually composes it.\n\nCompile-time dependency is not the same as runtime traffic:\n• a binary can depend on a transport crate without enabling every listener;\n• a storage adapter depends on the traits it implements even though the runtime\n  receives the adapter through composition;\n• the public facade depends on crates selected by features, but those crates do\n  not depend back on the facade; and\n• a product host depends on one connector adapter without making that adapter a\n  dependency of the central daemon.\n\nFollow the primary ownership layers\n\nmermaid\nflowchart TB\n    P[\"Central process: getaip-server\"]\n    H[\"Six connector-host binaries\"]\n    L[\"Client and control CLI: getaip\"]\n    X[\"Shared connector-host bootstrap\"]\n    C[\"Composition: gateway, MCP edges, remote dispatch\"]\n    F[\"Fleet control: registry, admission, orchestration, lifecycle control\"]\n    S[\"Storage adapters: runtime PostgreSQL and registry PostgreSQL\"]\n    R[\"Runtime governance: lifecycle, policy, queues, connector contract\"]\n    B[\"Bindings: native transports and compatibility profiles\"]\n    D[\"Domain services: authentication, cryptography, discovery, schema\"]\n    K[\"Semantic foundation: aip-core\"]\n    A[\"Feature-gated aip facade\"]\n\n    P --> C\n    P --> F\n    P --> S\n    H --> X\n    X --> C\n    X --> F\n    X --> S\n    L --> F\n    L --> B\n    L --> D\n    C --> R\n    C --> B\n    C --> F\n    F --> R\n    F --> D\n    S --> R\n    S --> F\n    R --> D\n    R --> K\n    B --> K\n    D --> K\n    A --> C\n    A --> R\n    A --> B\n    A --> D\n    A --> K\n\nThe text equivalent is:\n1. aip-core owns native protocol data and validation-independent semantics.\n2. Schema, cryptography, authentication, and discovery build on that semantic\n   foundation.\n3. Runtime governance and the connector contract consume those domain services\n   to validate and execute native work.\n4. Transports and compatibility profiles translate or carry protocol data\n   without becoming owners of the native lifecycle.\n5. Gateways, remote dispatch, MCP edges, and connector-host bootstrap compose\n   the runtime with selected bindings.\n6. Fleet registry, admission, orchestration, lifecycle control, and their\n   concrete storage adapters remain separate control and persistence paths.\n7. The central daemon, six product-host binaries, and the client or control CLI\n   consume different outer combinations instead of sharing one executable\n   dependency tree.\n8. The aip facade is a feature-gated consumer convenience layer, not a new\n   owner below those components.\n\nSome direct Cargo edges cross the visual layers. For example, a gateway imports\nauthentication and cryptography directly, while the PostgreSQL runtime adapter\nimports profile session contracts as well as runtime storage traits. Those\nedges implement a bounded responsibility; they do not transfer ownership of\nthe whole lower layer.\n\nKeep native semantics at the foundation\n\naip-core has no workspace dependency. It defines the native message model,\nidentifiers, capability and lifecycle values, errors, and validation methods\nused throughout the workspace. Its optional schema feature adds derive support;\nit does not import the schema registry, runtime, transport, or a connector.\n\naip-schema consumes core types to generate and validate JSON Schema.\naip-crypto and aip-auth consume core identities and messages for\ncryptographic and authorization decisions. aip-discovery consumes core and\nschema contracts to admit manifests and expose capabilities.\n\nThis direction creates a practical rule: a protocol field required across\ntransports and profiles belongs in the semantic or schema layer. It must not be\ndefined first in an HTTP route, an MCP mapping, or a product adapter and then\nleak upward through conversions.\n\nLet runtime depend on policy contracts, not products\n\naip-runtime depends on authentication, cryptography, discovery, schema, the\nproduct-neutral connector registry contract, and core. It owns action\ngovernance, lifecycle state, queues, approvals, transactions, delegations,\ncallbacks, and recovery.\n\nThe runtime has no dependency on any of the six maintained product adapters,\nconnector-host binaries, compatibility servers, or deployment processes.\nProduct behavior reaches the runtime only through an admitted action handler or\nthe tenant-scoped remote catalog and remote handler.\n\naip-connector depends on core, discovery, and runtime because it defines the\nconnector-facing implementation contract, credential boundary, and lifecycle\nintegration. Product adapters depend on that contract. Reversing this edge\nwould make generic execution depend on a particular provider.\n\nKeep bindings parallel to lifecycle\n\naip-transport defines native transport abstractions over core messages.\nProtocol-specific transport crates implement HTTP, NATS, SSE, or WebSocket\nbindings by depending on that abstraction and the core model.\n\nCompatibility profiles map foreign semantics into native AIP. MCP client and\nserver packages depend on the MCP profile and session contracts; the MCP server\nalso composes the gateway. The gateway itself does not depend on the MCP\nprofile. This keeps the native action lifecycle usable without importing an MCP\nserver.\n\nThe A2A profile is a gateway dependency for its bounded native integration.\nThat compile-time edge does not mean every gateway deployment exposes an A2A\nendpoint.\n\nProfiles and transports may depend on native semantics. Native lifecycle code\nmust not depend on a wire listener or a foreign protocol mapping to decide what\nan action, approval, transaction, or result means.\n\nCompose at the gateway boundary\n\naip-gateway combines trusted ingress, replay protection, identity\nresolution, query authorization, runtime dispatch, remote delegation, and\ncallbacks. It consumes the runtime, generic connector contract, selected native\ntransport abstractions, and the profile support it directly owns.\n\nThe gateway is still a library. Listener construction and deployment\nconfiguration belong to an executable or embedding application. A new listener\ntherefore depends on the gateway; the gateway should not import the process\nthat starts it.\n\nThe remote connector package implements the runtime's catalog and handler\nextension points using the connector registry and gateway peer clients. The\ncentral daemon depends on this product-neutral path and does not import the six\nproduct implementations.\n\nSeparate fleet control from provider execution\n\nFleet packages divide authority rather than forming one large connector crate:\n\n| Package responsibility | Depends on | Must remain independent of |\n\n| Registry contract | Core, cryptography, and discovery definitions | Product API clients and host processes |\n| Admission | Registry contract, cryptography, discovery, and core | Process startup and provider execution |\n| Orchestration contract | Admission and registry contracts | Deployment-platform implementation details |\n| Registry PostgreSQL adapter | Registry and admission-owned storage contracts | Runtime product execution |\n| Connector host | Gateway, runtime, connector contract, registry views, and bounded transport support | Selection of another tenant or connector instance |\n| Host bootstrap | Host composition, trusted peer setup, and complete runtime storage | Product-specific capability implementation |\n| Lifecycle control process | Host lifecycle and registry control contracts | Catalog admission authority and provider credentials |\n| Product host binary | Shared bootstrap plus exactly one maintained adapter | Central daemon composition |\n\nThe concrete storage and process crates sit outside the contracts they\nimplement. Their Cargo arrows point inward because dependency inversion lets a\nruntime or control service accept an implementation without importing a\nspecific database or executable.\n\nPut storage outside the state owner\n\naip-storage-postgres depends on runtime storage traits and constructs a\ncomplete shared-durability store bundle. The runtime does not depend on\nPostgreSQL. It can instead receive the in-memory, local file, or another\ncontract-compatible bundle.\n\nThe registry PostgreSQL adapter follows the same pattern for fleet catalog,\nroute, admission-journal, lease, and control state. A database schema can\noptimize and coordinate those records, but it does not become the owner of\ntheir protocol meaning.\n\nThis direction allows storage replacement without moving authorization,\nlifecycle, or routing rules into SQL-specific callers.\n\nTreat binaries and the facade as outer consumers\n\ngetaip-server is the central product-neutral server composition. It depends on the\ngateway, runtime, shared storage, remote connector path, profiles, and\ntransports needed for its configured surfaces. It does not depend on the six\nproduct adapters.\n\nEach maintained connector-host executable combines shared host bootstrap with\none product adapter. That is the intended point where provider-specific code\nenters an executable dependency tree.\n\ngetaip is a client, conformance, release-admission, and fleet-operation\nsurface. It imports the contracts and transports needed for those tasks, but\ndoes not embed the gateway or become part of server action execution.\n\nThe aip crate is a feature-gated facade. Enabling one of its features makes\nthe selected lower-level crate available to that consumer. It does not create a\nreverse edge, prove that a binary enables the feature, or make every optional\ncomponent part of the core protocol.\n\nPlace a change by its owner\n\n| Change | Start in | Add outward dependencies only when |\n\n| Native message field or invariant | aip-core and schema coverage | Bindings need serialization or mapping |\n| Signature or principal rule | Cryptography or authentication | Gateway composition must invoke the decision |\n| Manifest or capability admission | Discovery | Runtime or fleet admission must enforce it |\n| Action lifecycle or recovery rule | Runtime | Gateway, storage, or operators must expose it |\n| Transport encoding or listener behavior | Transport implementation or process | It calls the stable gateway boundary |\n| Foreign protocol mapping | Corresponding profile | Client or server adapters need that mapping |\n| Generic connector execution contract | aip-connector | Maintained adapters implement it |\n| Product operation | One maintained adapter and its host | Public connector docs expose the mapping |\n| Fleet route or release rule | Registry, admission, or orchestration contract | Adapter and process implement the contract |\n| Database coordination | Concrete storage adapter | The owning service accepts it through a trait |\n| Command or daemon wiring | getaip, getaip-server, or host binary | No lower layer imports the executable |\n\nWhen a proposed lower-level crate needs a type from a higher-level process,\nfirst ask whether the type is actually a missing semantic contract. Moving that\nsmall contract inward is usually safer than introducing a reverse dependency.\n\nInterpret the graph narrowly\n\nCargo metadata proves compile-time edges at the reviewed revision. It does not\nprove runtime enablement, network reachability, production qualification,\nfeature selection, storage durability, or provider availability.\n\nThe graph deliberately omits third-party dependencies, development-only tools,\nqualification packages, and exact edges that do not change architectural\nownership. Add or remove a direct workspace dependency in Cargo first, then\nupdate this map when the ownership path changes.\n\nRelated pages\n• Architecture overview (overview.md)\n• Runtime (runtime.md)\n• Gateway (gateway.md)\n• Connector fleet architecture (connector-fleet.md)\n• Transport bindings (../reference/transport-bindings.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "4094f584c69fd76921bf95adcff964fb5a7d856afa3bb264b4442914916165e1"
  }
}