# Glossary And Terminology

**Status:** Live terminology guide for Supply-Y Protocol 1.0. This guide explains current customer-facing language; it does not add fields to the immutable wire contract.

## Use definitions as contract boundaries

Supply-Y terms are operational. A `204` acknowledgement, a Policy Receipt and a Package Receipt prove three different things. A Package, its delivery envelope and the encrypted bytes are related, but they are not interchangeable objects. Implementations should preserve those distinctions in APIs, logs, dashboards and customer support.

## Version labels belong to different contracts

Protocol, schema, Skill, SDK, installer, Compatibility Report and Connection Profile versions advance independently. `Protocol 1.0` names the stable cross-company contract. A supporting component may still be a preview without changing the Protocol version or allowing a receiver to accept `supply-y/0.1`.

Never rewrite an old object to look current, infer compatibility from a similar version number or use a floating `latest` artifact. Pin the exact Release Manifest and evaluate each supporting component against its own compatibility and trust rules.

## Three distinctions that prevent common mistakes

1. **Policy Envelope versus Policy Receipt:** the Envelope states the intended disclosure and usage rule; the Receipt is the sender Agent's signed claim that required local checks ran for one exact Package.
2. **Event acknowledgement versus Package Receipt:** HTTP `204` proves durable notification storage; a signed Package Receipt proves a business lifecycle state such as received, opened, rejected or failed.
3. **Conformance versus certification:** conformance proves named test behavior; certification binds evidence to a specific implementation, version, operating scope and expiry.

## Terms link back to evidence

The HTML page provides an interactive index that links every definition to its canonical guide, contract or evidence page. The Markdown version expands the same structured index for Agents and offline review.

## Current version vocabulary

Only the Protocol row names the Protocol version. Supporting contracts keep independent identities and maturity.

| Surface | Current version | Status |
| --- | --- | --- |
| Protocol | `Protocol 1.0` | stable |
| Skill catalog | `0.1.0` | Preview artifacts |
| TypeScript SDK | `0.1.0-preview.5` | Restricted source preview |
| Agent installer | `0.9.0` | Preview contract |

## Complete term index (38)

Definitions below are generated from the same structured index used by the interactive HTML page.

## Contract and objects

### Agent

A company-controlled runtime that transforms local data, applies approved Skills, uses customer keys and exchanges Supply-Y objects.

- **Also called:** `company Agent`, `customer Agent`
- **Do not confuse it with:** It is not a mandatory Supply-Y gateway. A company may use its own Agent or a customer-isolated Jenae deployment.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/architecture#3-participant-model)

### Controlled Reasoning

A structured business output containing the useful facts, assumptions, uncertainty, confidence, requested action and disclosure limits needed for a decision.

- **Also called:** `bounded reasoning`, `reasoning with a disclosure boundary`
- **Do not confuse it with:** It is not private chain of thought, a raw database export or an instruction for the recipient Agent to execute.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/concepts#what-controlled-reasoning-means)

### Loop Thread

The durable business context that orders Packages, Responses, state transitions and the current Network Story for one collaboration problem.

- **Also called:** `Thread`, `collaboration thread`
- **Do not confuse it with:** It is more than a chat or correlation ID: its lifecycle and allowed transitions are part of the protocol.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/concepts#the-collaboration-loop)

### Network Story

A versioned, evidence-linked summary of what the participating network currently agrees on, what remains open and what should happen next.

- **Also called:** `shared judgment`, `thread summary`
- **Do not confuse it with:** It is not a replacement for the underlying Packages and Responses, which remain its auditable basis.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/concepts#core-objects)

### Package

A bounded protocol object prepared for a named business purpose and recipient, with identity, intent, disclosure boundaries and response obligations.

- **Also called:** `Supply-Y Package`, `business object`
- **Do not confuse it with:** It is not an ERP export, a database replica or the transport envelope used to deliver it.
- **Canonical detail:** [Read the source](https://supply-y.net/docs#package-example-title)

### Policy Envelope

The protocol object that states allowed recipients and actions, granularity, retention, forwarding, model-use and human-approval boundaries.

- **Also called:** `usage boundary`, `disclosure policy`
- **Do not confuse it with:** It states the intended rule. A Policy Receipt is the sender Agent's signed claim that required local checks ran for one exact Package.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/concepts#core-objects)

### Reasoning Package

A Package type that carries the sender's facts, evidence references, reasoning, confidence, known unknowns and requested response.

- **Also called:** `reasoning_package`, `bounded business judgment`
- **Do not confuse it with:** Schema validity proves structure and declared boundaries, not that the hidden business claim is true.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/reference#examples-valid-reasoning-package-material-constraint-native-valid-json)

### Response Object

The recipient's structured reply, bound to the Package it answers and carrying commitments, constraints, questions or a rejection.

- **Also called:** `response`, `structured reply`
- **Do not confuse it with:** It is a new signed protocol object, not an edit to the sender's original Package.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/concepts#core-objects)

### Supply-Y Protocol

The stable cross-company contract for object meaning, compatibility, integrity, delivery metadata, receipts, Thread state and audit semantics.

- **Also called:** `Protocol 1.0`, `wire contract`, `supply-y/1.0`
- **Do not confuse it with:** Protocol 1.0 does not mean every hosted service, Skill, SDK or certification surface is generally available.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/release)

### Supply-Y Skill

A signed JSON artifact that tells an Agent how to produce or validate one class of bounded business output under explicit capabilities and safety rules.

- **Also called:** `Skill`, `capability package`, `behavior rules`
- **Do not confuse it with:** A Skill is data, not remotely executable code, and its version is independent from the Protocol version.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/skills)

### TypeScript SDK

An optional reference implementation for validation, Skill lifecycle, Native cryptography, Thread context and the Agent API.

- **Also called:** `reference SDK`, `@supplywhy/supply-y-sdk`
- **Do not confuse it with:** The SDK is not the Protocol and is not required; any language can implement the public Protocol 1.0 contracts.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/sdk)

## Security and policy

### Ciphertext

Package bytes encrypted for authorized participants so the Supply-Y platform cannot read the business content from stored data alone.

- **Also called:** `encrypted Package`, `JWE ciphertext`
- **Do not confuse it with:** Ciphertext still requires authenticated metadata, a sender signature and recipient key checks before it is trustworthy.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/security#end-to-end-confidentiality)

### Content Digest

A SHA-256 digest that binds an exact byte sequence to Package metadata, policy evidence, transfer records and receipts.

- **Also called:** `RFC 9530 digest`, `SHA-256 hash`, `payload hash`
- **Do not confuse it with:** A matching digest proves byte integrity, not business truth or sender authorization by itself.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/crypto#canonical-plaintext-and-digest)

### Digital Signature

Cryptographic proof that a registered signing key approved the exact protected object or delivery claim.

- **Also called:** `ES256 signature`, `JWS`, `sender signature`
- **Do not confuse it with:** A valid signature proves key use and integrity; it does not prove that the signed business statement is factually correct.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/crypto#sign-the-exchange-envelope)

### Forwarding

Giving another organization access to a received Package or its content after the original exchange.

- **Also called:** `continued sharing`, `downstream disclosure`
- **Do not confuse it with:** Supply-Y permits no blind forwarding. A new recipient normally requires a new Package, disclosure decision and Policy Receipt.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/concepts#no-blind-forwarding)

### Joint Audit

A time-limited exception in which both parties approve an exact Package scope for isolated plaintext review with logged access and an ephemeral key.

- **Also called:** `bilateral audit`, `approved plaintext review`
- **Do not confuse it with:** It is not normal platform operation and does not turn Supply-Y into a central plaintext archive.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/security#joint-audit)

### KMS / HSM

Customer-controlled infrastructure that performs signing and decryption operations without exporting private key material into Supply-Y or application code.

- **Also called:** `key management system`, `hardware security module`, `customer key custody`
- **Do not confuse it with:** A key identifier or adapter reference is safe to configure; the private key value is not.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/crypto#kms-and-hsm-operation-boundary)

### Plaintext

Readable business content before encryption or after authorized decryption inside a participant-controlled environment.

- **Also called:** `decrypted Package`, `business content`
- **Do not confuse it with:** Supply-Y does not receive Package plaintext on the normal Native or Catena-X path.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/security#data-ownership)

### Policy Receipt

A sender-signed, plaintext-free claim binding one Package digest, recipient, Skill, Policy Envelope and required local check results.

- **Also called:** `signed policy claim`, `package authorization evidence`
- **Do not confuse it with:** It proves what the sender Agent claimed to check. It does not reveal the Package or prove that a malicious implementation checked honestly.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/security#policy-without-platform-plaintext-access)

### Routing Metadata

Readable identifiers, versions, timestamps, transport selection, digests and lifecycle references needed to route and audit an encrypted exchange.

- **Also called:** `authenticated metadata`, `delivery metadata`
- **Do not confuse it with:** It excludes business payload fields and private keys, but customers should still treat it as sensitive operational metadata.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/security#data-ownership)

## Delivery and audit

### Audit Event

A tamper-evident record of a Package or Thread action, including actor, time, state, object identity and digest without business plaintext.

- **Also called:** `lifecycle event`, `append-only event`
- **Do not confuse it with:** It proves what the platform observed, not that the encrypted business claim was true.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/security#audit-integrity)

### Catena-X Mode

The transport mode in which both participants' approved EDC connectors move one encrypted Package peer to peer while Supply-Y coordinates identity, Thread state, receipts and audit.

- **Also called:** `EDC transport`, `catena_x`
- **Do not confuse it with:** Supply-Y stores transfer references, not a duplicate Native Package, and the transport cannot change silently inside an active Thread.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/catena-x)

### Control Plane

Identity, public keys, signed Skills, Package and Thread state, transfer references, notifications, receipts and audit coordination.

- **Also called:** `coordination plane`, `Supply-Y services`
- **Do not confuse it with:** The control plane can coordinate an exchange without becoming the data plane that carries readable business content.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/architecture#11-supply-y-cloud-architecture)

### Data Plane

The single path that carries encrypted Package bytes: Supply-Y encrypted object storage in Native Mode or participant EDC infrastructure in Catena-X Mode.

- **Also called:** `payload transport`, `Package bytes path`
- **Do not confuse it with:** One Package uses one data plane. Sending it through both modes creates a prohibited duplicate path.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/catena-x#one-package-one-transport)

### Dead-letter Queue

A retained operational state for a notification that exhausted bounded retries and now requires operator action or replay.

- **Also called:** `DLQ`, `exhausted delivery`
- **Do not confuse it with:** Moving an event to dead letter does not delete the Package, close the Thread or imply business rejection.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/events#retry-decisions)

### Delivery Envelope

The transport-independent wrapper that binds sender, recipients, Skill, expiry, digest, policy receipt and transport metadata to a protocol object.

- **Also called:** `exchange envelope`, `wire wrapper`
- **Do not confuse it with:** It is separate from the business object so routing fields do not leak into every scenario schema.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/concepts#stable-envelope-and-scenario-payload)

### Event Acknowledgement

Confirmation that a recipient Agent durably stored a lifecycle notification in its local inbox.

- **Also called:** `204 response`, `webhook acknowledgement`, `durable inbox ack`
- **Do not confuse it with:** HTTP 204 does not mean the business Package was opened, accepted or acted on; those states require a Package Receipt.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/events#acknowledgement)

### Idempotency Key

A caller-generated key that makes one mutation safe to retry by returning the original result for the same request content.

- **Also called:** `retry key`, `Idempotency-Key`
- **Do not confuse it with:** Reusing the key with different content is an error, and using a new key does not permit a duplicate Package ID.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/api#api-conventions)

### Native Mode

The transport mode in which Supply-Y stores one end-to-end encrypted Package and makes it available to the authorized recipient.

- **Also called:** `Supply-Y transport`, `native`
- **Do not confuse it with:** Supply-Y can route and audit the ciphertext but holds no customer decryption key.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/architecture#101-native-mode)

### Package Receipt

A recipient-signed statement that an exact Package was received, opened, rejected or failed at a particular time.

- **Also called:** `recipient receipt`, `business lifecycle receipt`, `signed receipt`
- **Do not confuse it with:** It is not the sender's Policy Receipt and not the HTTP 204 acknowledgement for storing a notification.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/events#three-identifiers-three-jobs)

## Adoption and assurance

### Agent Bundle

A digest-pinned, one-fetch archive of public contracts, schemas, fixtures, conformance cases and test vectors that an Agent can use without repository access.

- **Also called:** `Protocol Bundle`, `public implementation bundle`
- **Do not confuse it with:** It contains public fictional test material and no customer data or executable Skill permissions.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/release#protocol-10-artifacts)

### Agent Compatibility Report

The structured result an installing Agent returns after running the required checks against its own implementation and customer configuration.

- **Also called:** `Compatibility Report`, `install result`
- **Do not confuse it with:** A schema-valid report cannot claim production enablement when evidence, keys, trust or configuration remains incomplete.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/conformance#agent-compatibility-report-conformance)

### Certification

A time-limited assurance claim for a named Agent implementation, Skill set, transport mode, version range and evidence date.

- **Also called:** `Supply-Y Certified`, `implementation certification`
- **Do not confuse it with:** Passing repository conformance is evidence, not a permanent certification of an organization or every future release.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/conformance#certification-levels)

### Conformance

Executable evidence that an implementation follows specified object, cryptographic, behavior, safety and transport rules, including required rejection cases.

- **Also called:** `compatibility checks`, `test profile`
- **Do not confuse it with:** Conformance tests contract behavior; certification adds implementation identity, operating evidence, scope and time limits.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/conformance)

### Customer Connection Profile

A strict customer-local configuration containing references to API credentials, Agent identity, keys, approved Skills, transport, policy, approval and notification settings.

- **Also called:** `connection profile`, `customer-local configuration`
- **Do not confuse it with:** It stores typed references, not secret values or private keys, and the complete profile is never uploaded to Supply-Y.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/agent-install#customer-local-connection-profile)

### Discovery Manifest

The stable machine-readable starting point that tells an Agent where to find the current release, installer, conformance profile, API, Skills, trust and security resources.

- **Also called:** `/.well-known/supply-y`, `Agent discovery`
- **Do not confuse it with:** Discovery locates and pins contracts; it does not silently install or activate a Skill.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/agent-install#machine-readable-entry-points)

### Production Readiness

Evidence that the specific hosted services, trust roots, customer implementation, keys, interoperability, operations and support needed for live exchange are complete.

- **Also called:** `GA`, `generally available`, `production enablement`
- **Do not confuse it with:** A stable Protocol 1.0 contract is necessary but does not make every product surface generally available.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/readiness)

### Protocol Release Manifest

The immutable Protocol 1.0 inventory that pins each release artifact by canonical URL, byte count and RFC 9530 SHA-256 digest.

- **Also called:** `Release Manifest`, `immutable release inventory`
- **Do not confuse it with:** It identifies exact contract bytes; a floating latest URL or similar-looking file is not an equivalent release.
- **Canonical detail:** [Read the source](https://supply-y.net/docs/release)

---

Canonical HTML: [Glossary and Terminology](https://supply-y.net/docs/glossary)
Agent documentation index: [llms.txt](https://supply-y.net/llms.txt)