# Supply-Y Agent Exchange Infrastructure

## 1. Purpose

This document defines the infrastructure architecture for Supply-Y's cross-company Agent exchange.

The product promise is simple:

> A company's Agent can exchange useful supply-chain packages with another company's Agent. The companies keep their raw data and private keys. Supply-Y provides the Skills, APIs, identity, delivery, audit and trust infrastructure around the exchange.

Supply-Y is not a central supply-chain data lake. It is the network and trust layer that lets company-controlled Agents collaborate safely.

## 2. What Each Party Owns

### Customer owns

- ERP, MES, QMS, PLM, warehouse and data-lake data
- its own Agent, or a Jenae Agent deployed for that customer
- the transformation from local data into a Supply-Y Package
- its signing and encryption private keys
- the decision to send, receive, open and respond
- any plaintext created or decrypted inside its environment

### Supply-Y owns

- Supply-Y Core Skill and scenario Skills
- signed Skill Registry and version compatibility rules
- Agent and organization registration
- public-key directory
- authenticated exchange APIs
- Native encrypted Package transport and storage
- Catena-X integration and transfer tracking
- threads, delivery receipts and notifications
- append-only audit trail
- optional joint-audit workflow
- compatibility testing and certification
- network usage metering and billing

In plain language:

**Customers own the data and the decisions. Supply-Y owns the trusted exchange infrastructure.**

## 3. Participant Model

Every participating company needs an Agent that can run Supply-Y Skills.

- A customer with an existing Agent installs the Supply-Y Skills.
- A customer without an Agent can use Jenae, which runs the same Skills.
- Supply-Y does not require a separate Gateway inside the customer network.
- The Agent makes outbound HTTPS calls to Supply-Y. Supply-Y does not open an inbound connection into the customer's private network.

The Agent connects to local systems through customer-controlled connectors. Those connectors may call APIs, consume events, query a data product or read an approved data view. Supply-Y does not prescribe how the customer's internal integration must work.

### 3.1 One-message Agent installation

Supply-Y onboarding must be Agent-friendly. A customer copies one self-contained paragraph from [`/docs/agent-install`](/docs/agent-install) and pastes it into its existing Agent. The same canonical text is available at [`/agent-install.txt`](/agent-install.txt), while [`/.well-known/supply-y`](/.well-known/supply-y) lets the Agent discover current contracts without guessing URLs.

The Agent then performs the work: it verifies the discovery-pinned Protocol Release Manifest, downloads the digest-pinned public Protocol Bundle, decodes and verifies all 55 embedded contracts and evidence files, creates an isolated workspace, and uses the language-neutral contract profile by default. No repository account is required. The TypeScript SDK profile is selected only when the operator confirms authorized source access. The Agent then verifies publisher keys and signed Skills, runs conformance in its own stack, asks the operator only for missing customer configuration, creates a strict customer-local connection profile and returns a schema-valid compatibility report. The local profile pins the exact Protocol release and stores references to OAuth credentials, keys, policies and approvers; Supply-Y receives only its digest and readiness result. Copying the paragraph never supplies credentials, exports keys or grants activation approval. Human documentation explains the process; the one-message prompt and machine manifest are the executable onboarding interface.

## 4. Supply-Y Skills

Supply-Y is Agent-facing. The installable product is a set of signed Skills.

### 4.1 Core Skill

`Supply-Y Core Skill` provides the common network behavior:

- Agent registration and authentication
- Skill and protocol version negotiation
- recipient public-key lookup
- Package creation and validation
- envelope encryption and signatures
- Native or Catena-X transport selection
- delivery receipts and retries
- thread and response handling
- audit event generation
- secure handling of incoming Packages

### 4.2 Scenario Skills

The initial scenario Skills are:

- `Supply-Y Material Risk Skill`
- `Supply-Y Capacity Alignment Skill`
- `Supply-Y Quality Containment Skill`
- `Supply-Y Compliance Evidence Skill`
- `Supply-Y Engineering Change Skill`

Each scenario Skill defines:

- the business goal
- the minimum output contract
- important field meanings
- fields that must not be disclosed
- validation rules
- example Packages and responses
- required approvals
- required audit events
- the expected next action

The customer's Agent can understand and transform local data however it wants. Supply-Y only standardizes the small Package that crosses the company boundary.

**Internal transformation is flexible. Network output is controlled.**

### 4.3 Skill Updates

Supply-Y operates a signed Skill Registry.

An Agent checks:

- installed Skill version
- every newer candidate returned by the paged Skill catalog
- minimum supported version
- protocol compatibility
- exact predecessor and change classification
- publisher trust, signature, artifact digest and dependencies
- requested capability changes

The Agent validates the publisher record and evaluates its `active`, `retiring`, `revoked` or test-only lifecycle before verifying the release signature. It ignores equal or older candidates; rejects deprecated, untrusted, invalid or incompatible candidates; sends capability expansion to manual review; and requires a migration for a breaking or non-direct update. A compatible additive or security update may be downloaded automatically when its signed policy permits it. Download never means activation: every current release requires explicit operator approval. After a publisher-key cutoff, an older release is accepted only when customer-controlled audit evidence binds its exact signed digest to an acceptance time before cutoff. If an installed release is revoked, the Agent disables it and alerts the operator. Every exchanged Package records `skill_id`, `skill_version` and `protocol_version`, so old and new versions can coexist during a migration window.

## 5. Lightweight Package Contract

A Package is the controlled unit of exchange. It is not the customer's full dataset.

Supply-Y avoids a large shared ontology. It separates the protocol object's identity from the network metadata used to deliver it.

### 5.1 Common protocol object envelope

Every protocol object includes:

- `id` and `object_type`
- `protocol_version` and `schema_version`
- `created_at` and `created_by`
- correlation and idempotency values under `trace`

Reasoning Package, Response Object, Loop Thread, Network Story and Audit Event also require `thread_id`. Policy Envelope is the exception because one published policy can be reused across multiple threads.

These fields are defined once in `schemas/common.schema.json` and referenced by all six object contracts.

### 5.2 Exchange delivery metadata

When a Package is transported, its readable authenticated metadata includes:

- `package_id`
- `thread_id`
- `responds_to_package_id`
- `sender_org_id` and `sender_agent_id`
- `recipient_org_id` and `recipient_agent_id`
- `skill_id` and `skill_version`
- `protocol_version` and `schema_version`
- `created_at` and expiry
- `content_type` and `content_digest`
- `transport_mode`
- mandatory `policy_receipt_id`

The exchange request and audit trail repeat `transport_mode` so routing and evidence remain explicit. In Native Mode this metadata is authenticated as JWE AAD and by the outer JWS. In Catena-X Mode the same logical metadata is bound to the EDC transfer record.

The business object itself does not contain a self-hash, embedded signature or transport routing. Integrity has one authoritative chain: canonical object bytes, readable `content_digest`, encrypted-asset digest where applicable, sender signature over the exchange envelope, signed receipt and audit event. Native versus Catena-X selection changes the envelope, never the business object.

### 5.3 Scenario payload

A Material Risk payload could contain:

```json
{
  "material_family": "PA66 flame-retardant resin",
  "affected_part_family": "sealed connector housings",
  "risk_band": "high",
  "affected_window": {
    "start": "2026-08-01",
    "end": "2026-09-15"
  },
  "confidence": 0.82,
  "evidence_refs": ["supplier_notice:SN-2048", "inventory_model:run-719"],
  "requested_action": "Confirm protected demand class within 30 hours",
  "not_disclosed": ["exact_inventory", "customer_names", "contract_price"]
}
```

The Skill defines what this payload must contain, not how the sender's Agent derived it from internal systems.

## 6. Policy In Practice

In Supply-Y, policy means the scenario-specific rules attached to a Skill and Package.

For example, the Material Risk Skill may allow:

- material family
- affected part family
- risk band
- time window
- confidence
- evidence reference
- requested action

It may prohibit:

- exact inventory
- exact plant capacity
- customer names
- pricing and margin
- allocation formulas

Because Supply-Y cannot normally decrypt the Package, Supply-Y does not inspect plaintext fields in the normal path. The sending Agent applies the Skill's rules locally and signs a Policy Receipt that records:

- the exact Package ID and encrypted-content digest
- sender and recipient Agent identities
- protocol, Skill and policy versions
- object-schema, Skill-profile, prohibited-disclosure, recipient-authorization, retention and forwarding check results
- approval result, when required
- evaluation timestamp and sender signature

The Agent first calls `POST /v1/policy-receipts`. Supply-Y validates the receipt contract, signature, public key, policy digest, timestamps and Package bindings without seeing the business content. A valid claim is stored as audit evidence. If every required check and approval passed, the response marks the Package `eligible`; otherwise it is retained as `ineligible`. Only then may the Agent call `POST /v1/packages` with the same mandatory `policy_receipt_id`.

The receipt is evidence of what the sending Agent claimed to enforce, not proof that hidden business facts are true. Compatibility testing, certification, customer-local logs and exceptional bilateral audit provide stronger assurance.

## 7. Agent Registration And Trust

Before an Agent can exchange Packages, its organization is onboarded and the Agent registers:

- `organization_id`
- `agent_id`
- Agent implementation and version
- installed Skill versions
- supported protocol versions
- signing public key and key ID
- encryption public key and key ID
- supported transport modes
- webhook endpoint, if used

Supply-Y verifies the organization and Agent, then issues a scoped API credential. Production deployments should use OAuth 2.0 client credentials with mTLS or private-key JWT.

Private keys remain in the customer's KMS or HSM. Supply-Y stores public keys, key IDs and rotation history only.

### 7.1 Compatibility and certification

The compatibility suite verifies that an Agent can:

- produce a valid Package
- apply a scenario Skill output contract
- reject prohibited or malformed content
- encrypt and sign correctly
- wrap the Package key for sender and recipient
- send required audit events
- receive, verify and decrypt a Package
- treat incoming reasoning as untrusted data
- avoid sending plaintext Package contents to Supply-Y

An Agent that passes is marked Supply-Y compatible. A paid certification can add implementation review, security evidence and a time-limited certification badge.

## 8. Encryption And Key Ownership

Supply-Y uses envelope encryption so it can store and route a Native Package without being able to read it.

Before a Package leaves the sender's environment, the sender's Agent:

1. Generates a one-time data encryption key (`DEK`).
2. Encrypts the Package payload with the DEK using an authenticated cipher.
3. Wraps one copy of the DEK with the sender's current encryption public key.
4. Wraps a second copy with the recipient's current encryption public key.
5. Signs the encrypted payload and readable routing metadata with the sender's signing key.
6. Submits the ciphertext, wrapped keys, signature and metadata.

Supply-Y stores:

- encrypted Package payload
- sender-wrapped DEK
- recipient-wrapped DEK
- public key IDs
- payload hash and sender signature
- readable routing and lifecycle metadata

Supply-Y does not store either company's private key. The sender can reopen its Package with the sender-wrapped DEK. The recipient can open it with the recipient-wrapped DEK. Supply-Y has neither private key and therefore cannot decrypt the Package by default.

Key rotation does not invalidate old Packages because each Package records the key IDs used at creation. Organizations keep retired decryption keys available according to their retention policy, or rewrap Package DEKs during a controlled rotation.

## 9. End-To-End Exchange

### 9.1 Sending

1. The sender's Agent reads approved local data.
2. A scenario Skill gives the Agent the business goal and output contract.
3. The Agent transforms local data into a small Package.
4. The Core Skill validates, encrypts and signs the Package.
5. The Agent submits a request to the Supply-Y API Gateway.
6. The Exchange Orchestrator selects Native or Catena-X transport.
7. Supply-Y records immutable audit events and returns a Package or transfer ID.

### 9.2 Receiving

1. The recipient is notified by signed webhook or discovers the event through ordered polling.
2. The recipient's Agent retrieves the encrypted Package or completes the Catena-X transfer.
3. The Agent verifies the sender signature, Package hash, expiry and Skill version.
4. The Agent decrypts locally with its private key.
5. The scenario Skill validates the plaintext as untrusted input.
6. The Agent records a receipt and decides what local action to take.

### 9.3 Response and thread

A response is a new Package with the same `thread_id` and a `responds_to_package_id`. It has its own payload, encryption, signature, policy receipt and audit trail.

The Thread API gives both parties a shared view of Package order and state without exposing plaintext to Supply-Y.

### 9.4 No blind forwarding

If Company B receives Company A's Package and needs to communicate with Company C, B creates a new Package under the appropriate Skill. A's original Package is not automatically forwarded.

This preserves data ownership and creates a clear audit boundary for every disclosure.

## 10. Two Transport Modes

The business Package and audit model stay the same. Only the transport changes.

### 10.1 Native Mode

Native Mode is used when the participants do not already have Catena-X EDC connectivity.

Flow:

1. The sender submits ciphertext and metadata through the Package API.
2. Package Service stores ciphertext in the Encrypted Object Store.
3. Metadata DB stores IDs, state, wrapped-key references and receipts.
4. Notification Service tells the recipient that a Package is available.
5. The recipient downloads ciphertext through an authorized, short-lived URL or API response.
6. The recipient decrypts locally and sends a receipt.

Supply-Y stores the encrypted Package in Native Mode but cannot read it.

### 10.2 Catena-X Mode

Catena-X Mode is used when the participants already operate compatible EDC connectors.

The Package should not be transferred twice.

Flow:

1. The sender's Agent creates the same encrypted and signed Supply-Y wire Package used by the Native contract.
2. The sender publishes those exact bytes as one EDC asset and computes an RFC 9530 `asset_digest` over them.
3. The Agent signs a canonical control manifest that binds Package metadata, connector ID, asset ID, asset digest, Contract Agreement ID and Transfer Process ID.
4. The Supply-Y Catena-X Adapter uses the participant's EDC Management API to initiate or observe contract negotiation and transfer.
5. The Package moves peer-to-peer through the existing EDC data plane.
6. The recipient verifies the asset digest, sender signature and Package before decrypting locally.
7. Supply-Y records the signed control manifest, receipts and thread state.
8. Supply-Y does not upload a duplicate Package into Native storage.

Supply-Y remains responsible for Skills, identity, thread coordination and audit. Catena-X provides the transport and contract-control path.

### 10.3 Transport selection

Exchange Orchestrator selects the mode from both organizations' capabilities and the thread configuration:

- if both sides have approved Catena-X connector registrations, use Catena-X Mode;
- otherwise use Native Mode;
- do not change transport silently after a thread starts;
- record the selected mode in every audit event.

### 10.4 Executable reference evidence

`npm run validate:interop` runs a Node.js sender, a separate Python recipient and a Node.js receipt verifier in isolated operating-system processes. The Python Agent independently verifies the outer signature, decrypts the JWE, validates authenticated metadata and object rules, then signs a receipt that Node.js verifies. The Native run stores one encrypted object. The Catena-X run stores one simulated EDC asset and zero Native objects. Both runs preserve the same Package identity, business-content digest and object semantics and verify append-only audit hash chains.

This proves repository-local cross-language Agent interoperability. The public hosted Sandbox now exercises the Native API with fictional data, but neither result replaces testing with an independently maintained external Agent, customer KMS or HSM evidence, or a real partner EDC interoperability run.

## 11. Supply-Y Cloud Architecture

### 11.1 Public edge

Only the API Gateway is public.

It provides:

- HTTPS termination
- WAF and DDoS protection
- Agent authentication
- tenant-aware authorization
- rate limits and quotas
- request size and content-type limits
- idempotency enforcement
- request routing
- access logs without Package plaintext

### 11.2 Identity and Agent Registry

Stores organizations, Agents, credentials, capabilities, certification status and supported Skill/protocol versions.

### 11.3 Skill Registry

Stores signed Skill manifests, release channels, compatibility rules, checksums and deprecation windows.

### 11.4 Public Key Directory

Publishes verified signing and encryption public keys, key IDs, status and rotation history.

### 11.5 Exchange Orchestrator

Creates Package and thread identities, selects transport mode, coordinates state changes and exposes one consistent API across Native and Catena-X modes.

### 11.6 Package and Thread Service

Package Service manages Native ciphertext references, metadata, receipts and idempotent state transitions. Thread Service returns the ordered Package graph for a collaboration.

For the MVP, Thread Service can be a logical module inside Package Service rather than a separate deployment.

### 11.7 Catena-X Adapter

Integrates with approved EDC Management APIs. It stores connector references and Supply-Y transfer metadata, but not the customer's EDC credentials in application tables and not a duplicate Package payload.

Connector secrets are stored in Supply-Y Secret Manager or, preferably, exchanged through a customer-controlled short-lived credential flow.

### 11.8 Notification Service

Delivers metadata-only Package events through signed webhooks and an ordered polling API. Webhook delivery has a fixed seven-attempt backoff profile and a dead-letter queue. Each receiving Agent writes events to a durable local inbox, deduplicates by stable `event_id`, and uses the ordered stream to recover webhook gaps. The normative contract is documented in [Events And Webhooks](/docs/events).

### 11.9 Audit and Joint Audit

Audit Service writes append-only, tamper-evident lifecycle events. Joint Audit coordinates two-party approval for a limited review session.

### 11.10 Metering and Billing

Metering reads objective network events, Package counts and an optional signed transaction-value declaration. It does not read Package plaintext.

The commercial model can combine:

- a base subscription or included exchange allowance
- low-cost or free non-monetary reasoning exchange
- a percentage Network Fee when a Package carries an objectively declared transaction value

Pricing policy can evolve without changing the exchange protocol.

### 11.11 Internal Event Bus

Services publish durable events such as:

- `package.accepted`
- `package.available`
- `package.received`
- `package.opened`
- `package.responded`
- `transfer.failed`
- `joint_audit.approved`

Audit, Notification and Metering consume independently. Every event has a unique `event_id`. Consumers acknowledge separately, retry safely and send repeated failures to a dead-letter queue.

If Audit succeeds but Notification fails, the Package is not lost and the audit event is not rolled back. Notification retries from the Event Bus. This avoids one secondary failure breaking the whole exchange.

## 12. Data Storage

| Data | System of record | Can Supply-Y read plaintext by default? | Notes |
| --- | --- | --- | --- |
| Raw ERP, MES, QMS, PLM and lake data | Customer systems | No | Never uploaded for normal exchange |
| Decrypted Package | Customer Agent | No | Exists inside sender or recipient environment |
| Customer private keys | Customer KMS or HSM | No | Never sent to Supply-Y |
| Native Package ciphertext | Supply-Y Encrypted Object Store | No | Versioned, encrypted and retention controlled |
| Catena-X Package payload | Participant EDC data plane | No | Not duplicated in Supply-Y storage |
| Wrapped DEKs | Supply-Y Native metadata/object storage | No | Wrapped separately for sender and recipient |
| Organization, Agent, thread and state metadata | Supply-Y Metadata DB | Yes | Tenant-scoped, no Package contents |
| Public keys and Skill manifests | Supply-Y registries | Yes | Signed and versioned |
| Hashes, signatures and receipts | Supply-Y Audit Store | Yes | Used to prove integrity and delivery |
| Audit events | Supply-Y Append-Only Audit Store | Yes | Contains metadata, not Package plaintext |
| Joint-audit plaintext | Isolated temporary review session | Only after both parties approve | Not retained after the session by default |

Supply-Y's cloud KMS protects platform service keys, database credentials, object-store keys and Supply-Y signing keys. It never contains customer decryption or signing private keys.

## 13. External API Surface

The API is intentionally separated into a **current machine contract** and **target extensions**. This prevents an architecture diagram from being mistaken for an implementation promise.

### 13.1 Current 1.0 Agent API

These 21 operations are the complete current customer-facing surface. They are defined in the [API Contract](/docs/api), represented in the OpenAPI 3.1.1 document, covered by committed request and response examples, and checked for one-to-one parity in the release gate.

| Area | Method | Endpoint | Purpose |
| --- | --- | --- | --- |
| Agent | `POST` | `/v1/agents/register` | Register an Agent, capabilities and public keys |
| Agent | `GET` | `/v1/agents/{agent_id}` | Read verified Agent capabilities and status |
| Agent | `POST` | `/v1/agents/{agent_id}/keys` | Register a distinct replacement public key |
| Agent | `POST` | `/v1/agents/{agent_id}/keys/{key_id}/revoke` | Record revocation and its effective trust cutoff |
| Skill | `GET` | `/v1/skills` | List compatible signed Skill releases |
| Skill | `GET` | `/v1/skills/{skill_id}/releases/{version}` | Resolve one signed Skill release |
| Directory | `GET` | `/v1/directory/agents/{agent_id}/keys` | Get a timestamped, versioned public-key snapshot |
| Directory | `GET` | `/v1/directory/notification-keys` | Pin Supply-Y webhook-signing public keys |
| Policy | `POST` | `/v1/policy-receipts` | Validate and retain a signed local-policy claim before Package submission |
| Policy | `GET` | `/v1/policy-receipts/{policy_receipt_id}` | Read the authorized claim, signature result and Package eligibility |
| Package | `POST` | `/v1/packages` | Create a Native or Catena-X Package transfer |
| Package | `GET` | `/v1/packages/{package_id}` | Read authorized metadata and ciphertext location |
| Package | `POST` | `/v1/packages/{package_id}/receipts` | Record received, opened, rejected or failed state |
| Package | `POST` | `/v1/packages/{package_id}/responses` | Create a response Package in the same thread |
| Package | `POST` | `/v1/packages/{package_id}/revoke` | Request revocation before access where possible |
| Thread | `GET` | `/v1/threads/{thread_id}` | Read ordered Package metadata and current state |
| Notification | `POST` | `/v1/webhook-endpoints` | Register a signed webhook endpoint |
| Notification | `GET` | `/v1/notifications` | Recover retained notifications in sequence order |
| Notification | `POST` | `/v1/notifications/{notification_id}/ack` | Acknowledge durable local inbox storage |
| Audit | `GET` | `/v1/audit/threads/{thread_id}` | Read authorized immutable thread evidence |
| Audit | `GET` | `/v1/audit/packages/{package_id}` | Read Package integrity and delivery evidence |

Every mutation requires an `Idempotency-Key`. Retrying the same request returns the original result instead of creating a duplicate Package. OAuth token issuance is referenced by the OpenAPI security scheme as a supporting identity-provider endpoint; it is not counted as one of the 21 Agent resource operations.

### 13.2 Target extensions

The following operations describe intended modules, not the current 1.0 OpenAPI contract. They require their own schemas, examples, security review and release evidence before they may be advertised as available.

| Module | Candidate endpoint | Why it is not current yet |
| --- | --- | --- |
| Identity | `POST /v1/agents/auth/token` | Supplied by the production identity provider and deployment profile |
| Certification | `POST /v1/agents/{agent_id}/compatibility-runs` | The public exchange Sandbox is available, but hosted certification runs and certificate lifecycle are not |
| Skills | `GET /v1/skills/{skill_id}/releases/latest` | Optional convenience route; current Agents deterministically select from signed `GET /v1/skills` results |
| Skills | `GET /v1/skills/compatibility` | Compatibility response and failure schemas are not finalized |
| Discovery | `GET /v1/directory/organizations/{org_id}/agents` | Organization visibility and consent rules need production policy |
| Catena-X management | `/v1/integrations/catenax/*`, `/v1/catenax/transfers/*` | Current 1.0 carries EDC references through `POST /v1/packages`; connector administration is deployment-specific |
| Joint audit | `/v1/joint-audits/*` | Bilateral approval, temporary grants and review-session isolation need a separate security profile |
| Metering | `GET /v1/usage` | Commercial retention, dispute and invoice semantics are not finalized |
| Value declaration | `POST /v1/packages/{package_id}/value-declarations` | Bilateral signature and commercial governance require a separate profile |

## 14. Package State And Partial Failure

Package state is a durable state machine, not one long synchronous request.

Typical states are:

`accepted -> encrypted_available / transfer_started -> delivered -> received -> opened -> responded`

Failure states include:

- `delivery_retrying`
- `delivery_failed`
- `rejected`
- `expired`
- `revoked`

Rules:

- every state transition is idempotent;
- sender success is not erased because recipient processing fails;
- recipient processing can retry without resending the original Package;
- each side records its own signed receipt;
- audit records both success and failure;
- an operator can replay failed notifications without replaying the business Package;
- timeouts and retries are visible through the Package and Thread APIs.

## 15. Handling Malicious Or Unsafe Reasoning

Encrypted transport does not make content trustworthy. An incoming Package is untrusted input.

The recipient's Core Skill must:

- verify organization, Agent, signature, hash, expiry and key status before decryption;
- enforce Package size, content type and schema limits;
- validate the scenario Skill and protocol version;
- treat payload text as data, never as executable Agent instructions;
- isolate payload content from system prompts, tool permissions and credentials;
- block scripts, binaries and undeclared attachments;
- require allowlisted evidence references;
- apply confidence and provenance checks;
- require human approval for high-impact actions;
- log rejection reasons without sending plaintext to Supply-Y.

Supply-Y can enforce metadata, identity, rate and ciphertext limits at the API Gateway. Plaintext safety checks run inside the participating customer Agents because Supply-Y cannot decrypt the Package.

Certification tests these controls with malicious fixtures and prompt-injection examples.

## 16. Security And Tenant Isolation

- Every request is authenticated as an Agent and organization.
- Every database query and object access is scoped by `organization_id` and authorization policy.
- Object download uses short-lived, recipient-scoped authorization.
- Service-to-service traffic uses private networking and workload identity.
- Internal services and stores are not internet-accessible.
- Secrets live in a managed Secret Manager, not source code or application tables.
- Logs, traces and error reports must never contain Package plaintext or private keys.
- Key rotation, credential revocation and Agent suspension are supported without deleting audit history.
- WAF, rate limits, replay protection and idempotency protect the public API.

## 17. Reliability, Recovery And Observability

### Reliability

- API and backend services are stateless and horizontally scalable.
- Metadata DB uses multi-zone deployment and point-in-time recovery.
- Native Object Store uses versioning, retention policy and cross-region backup when required.
- Event Bus is durable and supports independent consumer acknowledgements.
- Audit Store has immutable backups and integrity verification.
- Webhook and EDC callbacks are retried with exponential backoff.

### Recovery objectives

The production SLOs should define separate recovery targets for:

- API availability
- Package metadata
- Native ciphertext
- audit evidence
- notifications

Loss of a notification must not mean loss of a Package. Loss of an analytics or billing event must not block delivery.

### Observability

Supply-Y records:

- request latency and error rate
- Package and transfer state duration
- retry and dead-letter counts
- Skill and protocol compatibility failures
- signature and key lookup failures
- webhook and EDC delivery health
- audit-write integrity checks

Metrics, logs and traces use IDs and states only. They do not contain Package plaintext.

## 18. Joint Audit

Joint Audit is the controlled exception to Supply-Y's no-plaintext default.

1. One participant requests a review and names the Packages, purpose and expiry.
2. Both organizations approve the exact scope.
3. One participant re-encrypts the selected Package for an ephemeral audit-session public key.
4. The second participant confirms the grant.
5. An isolated review viewer receives a temporary decryption capability.
6. Every view and export is logged.
7. The session key and temporary plaintext are destroyed when the session expires.

Supply-Y should not retain joint-audit plaintext after the approved session unless both parties explicitly approve a separate retention policy.

## 19. Recommended MVP Deployment

The architecture does not require dozens of microservices on day one.

The MVP can deploy:

1. one public API application containing Identity, Package, Thread, Skill and Key Directory modules;
2. one background worker for notifications, audit projection and metering;
3. one Catena-X Adapter worker;
4. managed relational Metadata DB;
5. managed encrypted Object Store;
6. durable queue or Event Bus with a dead-letter queue;
7. append-only audit tables plus immutable audit backup;
8. managed KMS, Secret Manager and observability stack.

The module boundaries and events should match the target architecture, but services should only be split when scale, security isolation or team ownership makes the split useful.

## 20. Final Architecture Summary

1. A customer uses its existing Agent or Jenae.
2. The Agent installs signed Supply-Y Core and scenario Skills.
3. Raw data and private keys stay in the customer's environment.
4. The Agent transforms local data into a small controlled Package.
5. The Agent signs a Policy Receipt, Supply-Y verifies its bindings, and only an eligible receipt can authorize sending.
6. The Package is encrypted for sender and recipient and signed before it leaves.
7. Native Mode stores ciphertext in Supply-Y; Catena-X Mode transfers once through existing EDC connectors.
8. Supply-Y APIs provide identity, keys, Skills, Policy Receipts, Packages, threads, notifications and audit.
9. Supply-Y stores readable metadata and tamper-evident evidence, not Package plaintext.
10. Partial failures retry independently through a durable Event Bus.
11. Joint plaintext review requires both parties and expires automatically.

The result is a lightweight Agent network: easier than reproducing the full Catena-X stack, compatible with Catena-X when customers already use it, and auditable without turning Supply-Y into a central plaintext data lake.

## 21. Catena-X References

The Catena-X transport design in this document follows the current Tractus-X model in which EDC separates control-plane metadata from data-plane transfer, and contract negotiation and transfer processing are asynchronous:

- [Tractus-X Connector Kit](https://eclipse-tractusx.github.io/docs-kits/25.09/kits/connector-kit/adoption-view/)
- [Tractus-X Data Governance Kit](https://eclipse-tractusx.github.io/docs-kits/kits/data-governance-kit/development-view/)
- [Tractus-X Demand and Capacity Management Development View](https://eclipse-tractusx.github.io/docs-kits/kits/demand-and-capacity-management-kit/software-development-view/overview/)

---

Canonical HTML: [Agent Exchange Architecture](https://supply-y.net/docs/architecture)
Agent documentation index: [llms.txt](https://supply-y.net/llms.txt)