Supply-Y Protocol

Developer Documentation

Protocol 1.0
Documentation

Search Supply-Y

All documentation
MarkdownDemo
Understand

Glossary And Terminology

Precise, shared definitions for business reviewers, implementers and Agents.

Protocol 1.0 terminology
Version identity

One stable Protocol, independently versioned components

Only the first row is the Protocol version. Skill, SDK and installer versions describe different contracts and release at their own pace.

Protocol
Protocol 1.0stable
Skill catalog
0.1.0Preview artifacts
TypeScript SDK
0.1.0-preview.5Restricted source preview
Agent installer
0.9.0Preview contract
Shared language

Find the exact meaning before implementation

Each entry gives the operational definition and the nearest concept it must not be confused with.

38 of 38 terms
Contract and objectsAgentcompany Agent · customer Agent

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

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.

Read the canonical detail
Contract and objectsControlled Reasoningbounded reasoning · reasoning with a disclosure boundary

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

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.

Read the canonical detail
Contract and objectsLoop ThreadThread · collaboration thread

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

Do not confuse it with: It is more than a chat or correlation ID: its lifecycle and allowed transitions are part of the protocol.

Read the canonical detail
Contract and objectsNetwork Storyshared judgment · thread summary

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

Do not confuse it with: It is not a replacement for the underlying Packages and Responses, which remain its auditable basis.

Read the canonical detail
Contract and objectsPackageSupply-Y Package · business object

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

Do not confuse it with: It is not an ERP export, a database replica or the transport envelope used to deliver it.

Read the canonical detail
Contract and objectsPolicy Envelopeusage boundary · disclosure policy

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

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.

Read the canonical detail
Contract and objectsReasoning Packagereasoning_package · bounded business judgment

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

Do not confuse it with: Schema validity proves structure and declared boundaries, not that the hidden business claim is true.

Read the canonical detail
Contract and objectsResponse Objectresponse · structured reply

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

Do not confuse it with: It is a new signed protocol object, not an edit to the sender's original Package.

Read the canonical detail
Contract and objectsSupply-Y ProtocolProtocol 1.0 · wire contract · supply-y/1.0

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

Do not confuse it with: Protocol 1.0 does not mean every hosted service, Skill, SDK or certification surface is generally available.

Read the canonical detail
Contract and objectsSupply-Y SkillSkill · capability package · behavior rules

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.

Do not confuse it with: A Skill is data, not remotely executable code, and its version is independent from the Protocol version.

Read the canonical detail
Contract and objectsTypeScript SDKreference SDK · @supplywhy/supply-y-sdk

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

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.

Read the canonical detail
Security and policyCiphertextencrypted Package · JWE ciphertext

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

Do not confuse it with: Ciphertext still requires authenticated metadata, a sender signature and recipient key checks before it is trustworthy.

Read the canonical detail
Security and policyContent DigestRFC 9530 digest · SHA-256 hash · payload hash

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

Do not confuse it with: A matching digest proves byte integrity, not business truth or sender authorization by itself.

Read the canonical detail
Security and policyDigital SignatureES256 signature · JWS · sender signature

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

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.

Read the canonical detail
Security and policyForwardingcontinued sharing · downstream disclosure

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

Do not confuse it with: Supply-Y permits no blind forwarding. A new recipient normally requires a new Package, disclosure decision and Policy Receipt.

Read the canonical detail
Security and policyJoint Auditbilateral audit · approved plaintext review

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

Do not confuse it with: It is not normal platform operation and does not turn Supply-Y into a central plaintext archive.

Read the canonical detail
Security and policyKMS / HSMkey management system · hardware security module · customer key custody

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

Do not confuse it with: A key identifier or adapter reference is safe to configure; the private key value is not.

Read the canonical detail
Security and policyPlaintextdecrypted Package · business content

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

Do not confuse it with: Supply-Y does not receive Package plaintext on the normal Native or Catena-X path.

Read the canonical detail
Security and policyPolicy Receiptsigned policy claim · package authorization evidence

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

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.

Read the canonical detail
Security and policyRouting Metadataauthenticated metadata · delivery metadata

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

Do not confuse it with: It excludes business payload fields and private keys, but customers should still treat it as sensitive operational metadata.

Read the canonical detail
Delivery and auditAudit Eventlifecycle event · append-only event

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

Do not confuse it with: It proves what the platform observed, not that the encrypted business claim was true.

Read the canonical detail
Delivery and auditCatena-X ModeEDC transport · catena_x

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.

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.

Read the canonical detail
Delivery and auditControl Planecoordination plane · Supply-Y services

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

Do not confuse it with: The control plane can coordinate an exchange without becoming the data plane that carries readable business content.

Read the canonical detail
Delivery and auditData Planepayload transport · Package bytes path

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

Do not confuse it with: One Package uses one data plane. Sending it through both modes creates a prohibited duplicate path.

Read the canonical detail
Delivery and auditDead-letter QueueDLQ · exhausted delivery

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

Do not confuse it with: Moving an event to dead letter does not delete the Package, close the Thread or imply business rejection.

Read the canonical detail
Delivery and auditDelivery Envelopeexchange envelope · wire wrapper

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

Do not confuse it with: It is separate from the business object so routing fields do not leak into every scenario schema.

Read the canonical detail
Delivery and auditEvent Acknowledgement204 response · webhook acknowledgement · durable inbox ack

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

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.

Read the canonical detail
Delivery and auditIdempotency Keyretry key · Idempotency-Key

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

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.

Read the canonical detail
Delivery and auditNative ModeSupply-Y transport · native

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

Do not confuse it with: Supply-Y can route and audit the ciphertext but holds no customer decryption key.

Read the canonical detail
Delivery and auditPackage Receiptrecipient receipt · business lifecycle receipt · signed receipt

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

Do not confuse it with: It is not the sender's Policy Receipt and not the HTTP 204 acknowledgement for storing a notification.

Read the canonical detail
Adoption and assuranceAgent BundleProtocol Bundle · public implementation 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.

Do not confuse it with: It contains public fictional test material and no customer data or executable Skill permissions.

Read the canonical detail
Adoption and assuranceAgent Compatibility ReportCompatibility Report · install result

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

Do not confuse it with: A schema-valid report cannot claim production enablement when evidence, keys, trust or configuration remains incomplete.

Read the canonical detail
Adoption and assuranceCertificationSupply-Y Certified · implementation certification

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

Do not confuse it with: Passing repository conformance is evidence, not a permanent certification of an organization or every future release.

Read the canonical detail
Adoption and assuranceConformancecompatibility checks · test profile

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

Do not confuse it with: Conformance tests contract behavior; certification adds implementation identity, operating evidence, scope and time limits.

Read the canonical detail
Adoption and assuranceCustomer Connection Profileconnection profile · customer-local configuration

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

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.

Read the canonical detail
Adoption and assuranceDiscovery Manifest/.well-known/supply-y · Agent discovery

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.

Do not confuse it with: Discovery locates and pins contracts; it does not silently install or activate a Skill.

Read the canonical detail
Adoption and assuranceProduction ReadinessGA · generally available · production enablement

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

Do not confuse it with: A stable Protocol 1.0 contract is necessary but does not make every product surface generally available.

Read the canonical detail
Adoption and assuranceProtocol Release ManifestRelease Manifest · immutable release inventory

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

Do not confuse it with: It identifies exact contract bytes; a floating latest URL or similar-looking file is not an equivalent release.

Read the canonical detail

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.

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.

On this page