CommandLayer Protocol — Commercial

The canonical commercial contract for monetized agent execution. Payment-aware request and receipt schemas — or settlement semantics drift.

Release notice — Protocol-Commercial v1.1.0

v1.1.0 is the current canonical commercial line in this repository.

A GitHub Release is not represented as already published in this repo state. releases/v1.1.0.md is the checked-in release-note draft for a future publication step, not evidence that a GitHub Release already exists.

Protocol-Commercial v1.1.0 is the current CommandLayer commercial schema line in this repository.

This README is a release-orientation document for the current line. The normative specification lives in SPEC.md. Release policy, checksum-boundary policy, and version-lifecycle rules live in POLICY.md.

It defines the canonical commercial overlays that sit on top of Protocol-Commons v1.1.0. Commons defines base semantic actions. Commercial defines the monetized, settlement-aware request and receipt contracts that agents and runtimes use when value moves.

Protocol-Commercial is intentionally limited to protocol truth:

• no runtime code
• no provider-specific business policy
• no pricing engine
• no routing logic
• no transport implementation beyond the normative x402-first execution assumption

Document scope

This README is a repo-wide orientation document for the active release line and its canonical shipped boundary.

Release truth

• Current canonical line: v1.1.0
• Current canonical schema root: https://commandlayer.org/schemas/v1.1.0/
• Current package entrypoint: index.js → schemas/v1.1.0/index.json
• Canonical shipped boundary: schemas/v1.1.0/, examples/v1.1.0/, manifest.json, checksums.txt, LICENSE, README.md, index.js
• Historical repository-only line: v1.0.0, retained under schemas/v1.0.0/ and examples/v1.0.0/
• Changelog: CHANGELOG.md
• Release note draft for a future GitHub Release publication: releases/v1.1.0.md

For the authoritative version policy and checksum-boundary rules, see POLICY.md. For normative identity and path rules, see SPEC.md.

Canonical namespace and source of truth

The commandlayer.org $id namespace is canonical for published Protocol-Commercial schemas.

This repository is the source of truth for those schema files and release metadata. Public mirrors or hosted copies under commandlayer.org may be unavailable temporarily; that does not change the canonical $id values or the repository-local release contents.

Schema identity and trust

• https://commandlayer.org/... is the canonical schema namespace and the normative $id base for this release line.
• This Git repository and its canonical shipped package contents are the source of truth for those artifacts.
• External resolution of $id URLs is a convenience, not a trust requirement; consumers should vendor, mirror, or package-pin the repository artifacts they validate against.

Relationship to the stack

Layer	Current line	Responsibility
Protocol-Commons	v1.1.0	Base semantic action contracts
Protocol-Commercial	v1.1.0	Commercial overlays for payment, settlement, fulfillment, and verification
Agent Cards	v1.1.0	Identity and discovery bindings to canonical schema URIs
Runtime	implementation-defined	x402 transport, execution, metering, policy, and provider integration

The stack story is singular:

• Commons defines the base action semantics.
• Commercial defines the monetized request and receipt contracts.
• Agent Cards point directly at the current commercial schema URIs.
• Runtimes execute those contracts but do not redefine them.

Integrator quickstart

For consumers who need the shortest safe path:

1. If and when @commandlayer/commercial is published, install that package and use the package-root export or explicit current-line schema export. Until then, treat the repository checkout as the authoritative source of the current line.

   npm install @commandlayer/commercial

   import commercialIndex from "@commandlayer/commercial";

   import commercialSchemaIndex from "@commandlayer/commercial/schemas/v1.1.0/index.json";

2. Treat schemas/v1.1.0/index.json as the authoritative map of current schemas and verb inventory. The package-root index.js export resolves to that same file.
3. Prefer schemas/v1.1.0/commercial/<verb>/<verb>.request.schema.json and ...receipt.schema.json directly for validator configuration.
4. Verify the shipped current-line payload before mirroring or vendoring using the canonical command surface in Validation commands.
5. Ignore v1.0.0 unless you are consulting repository-local historical material for migration work. It is not part of the canonical shipped package surface.
6. Treat schemas/v1.1.0/, examples/v1.1.0/, manifest.json, checksums.txt, README.md, LICENSE, and index.js as the canonical shipped boundary for the current line. Treat the checksum-covered subset as that same boundary minus checksums.txt itself.

The install command above is a future-publication consumer path, not a claim that npm publication has already happened. In the current repository state, the checked-in artifacts are the authoritative release candidate surface.

Commercial execution model

Protocol-Commercial is x402-first.

That means commercial execution is expected to be gated and evidenced through x402-compatible payment requirements, sessions, authorizations, and proofs. This repository does not define transport code, but it does define the canonical request and receipt shapes an x402-aware runtime needs in order to execute and later audit a paid interaction deterministically.

Commercial grammar decisions

Actor grammar

Protocol-Commercial uses a compact actor model:

• payer: the party funding or bearing the commercial obligation
• payee: the settlement recipient when it differs from the merchant identity
• merchant: the seller or commercial principal governing the offer, order, or fulfillment
• provider: an optional facilitating runtime or service performing settlement or fulfillment work on the merchant
• carrier: the shipment operator once physical fulfillment exists
• verifier: the authority performing or attesting the verification result

requester is a verify-specific initiator field, not a seventh governed actor role. It reuses the general actor identity shape so a payer, merchant, provider, verifier, or other documented commercial party can ask for verification without expanding the normative role vocabulary.

Field names are normative. A merchant field MUST carry a merchant actor, a payer field MUST carry a payer actor, and so on. payee is used only for settlement destination semantics; if omitted, the merchant is implicitly the payee.

x402 / payment grammar

Protocol-Commercial standardizes three payment layers across the verb family:

• payment_requirement: pre-payment terms or authorization preconditions
• payment_session: live x402 negotiation/session state
• payment_proof: final payment evidence for authorization or captured settlement

The verbs use those layers intentionally:

• authorize centers on payment_requirement and may emit authorization-flavored payment_proof
• checkout centers on payment_session and requires payment_proof when capture succeeds
• purchase accepts direct payment_input and requires payment_proof when capture succeeds
• ship links to upstream commercial settlement through commercial_ref and optional payment_ref, rather than restating the full payment flow
• verify verifies payment_proof, settlement, fulfillment, and receipt evidence

Verb set

Verb	Purpose	Teaching note
authorize	Reserve payment authority before capture or settlement	Teaches pre-capture approval, denial, and authorization evidence
checkout	Finalize an order and request commercial capture	Teaches negotiated session state, amount binding, and settlement outcomes
purchase	Complete a one-step paid commercial action	Teaches direct payment input without a separate checkout negotiation round
ship	Advance commercial fulfillment state for a settled checkout or purchase	Teaches how fulfillment references upstream commercial settlement without replaying payment semantics
verify	Verify a commercial receipt, settlement, payment, or shipment target	Teaches evidence-based attestation and inconclusive vs failed outcomes

Repository layout

protocol-commercial/
├── schemas/
│   ├── v1.0.0/                     # repository-only historical nested layout
│   └── v1.1.0/
│       ├── index.json
│       └── commercial/
│           ├── authorize/
│           │   ├── authorize.request.schema.json
│           │   └── authorize.receipt.schema.json
│           ├── checkout/
│           │   ├── checkout.request.schema.json
│           │   └── checkout.receipt.schema.json
│           ├── purchase/
│           │   ├── purchase.request.schema.json
│           │   └── purchase.receipt.schema.json
│           ├── ship/
│           │   ├── ship.request.schema.json
│           │   └── ship.receipt.schema.json
│           └── verify/
│               ├── verify.request.schema.json
│               └── verify.receipt.schema.json
├── examples/
│   ├── v1.0.0/                     # repository-only historical examples
│   └── v1.1.0/commercial/<verb>/{valid,invalid}/
├── manifest.json
├── checksums.txt
├── index.js
├── LICENSE
├── README.md
└── scripts/

When npm produces a tarball, it also emits package.json as required package metadata. That generated tarball addition does not widen the canonical shipped boundary described above.

Protocol-Commercial v1.1.0 does not use a current-line _shared/ tree. Every v1.1.0 request and receipt schema is self-contained, flat, and mirror-safe.

Browsing large self-contained schemas

To navigate the flat schema line efficiently without reintroducing cross-file dependencies:

• Start at schemas/v1.1.0/index.json to locate the request and receipt pair for the verb you need.
• Read a verb directory as a pair: request first for caller obligations, receipt second for canonical outcome and audit references.
• Use the local $defs section in each schema as the file-scoped glossary for repeated structures such as actors, money, and payment evidence.
• Compare same-named $defs across verbs only when checking consistency; the validator enforces those shared shapes without making readers chase external files.

Current-line example governance is equally explicit:

• valid/ contains illustrative conforming request and receipt fixtures.
• invalid/ contains isolated negative fixtures intended to fail validation cleanly.
• No examples/v1.1.0/**/ts/ tree is currently part of the public release surface.

Scope boundaries

This repository defines:

• canonical request and receipt schema identities
• explicit payment, authorization, settlement, fulfillment, and verification semantics
• x402-facing references required for commercial execution
• deterministic release metadata and machine-artifact checksums

This repository does not define:

• merchant onboarding policy
• fraud decisions
• custody or treasury operations
• legal finality
• provider SLAs
• runtime traces or debugging exhaust as normative truth

Example current-line schema pair

• Request: https://commandlayer.org/schemas/v1.1.0/commercial/checkout/checkout.request.schema.json
• Receipt: https://commandlayer.org/schemas/v1.1.0/commercial/checkout/checkout.receipt.schema.json

Example request artifact

{
  "protocol": "commercial",
  "version": "1.1.0",
  "verb": "checkout",
  "request_id": "checkoutreq-001",
  "requested_at": "2026-03-19T10:05:00Z",
  "payer": { "role": "payer", "id": "buyer-001", "kind": "account" },
  "merchant": { "role": "merchant", "id": "merchant.example", "kind": "organization" },
  "order_ref": { "type": "order", "id": "ord-1001" },
  "items": [
    {
      "sku": "sku-pro-plan",
      "description": "Protocol Pro Plan",
      "quantity": 1,
      "unit_price": { "amount": "49.99", "currency": "USDC", "decimals": 2 }
    }
  ],
  "amount_breakdown": {
    "subtotal": { "amount": "49.99", "currency": "USDC", "decimals": 2 },
    "total": { "amount": "49.99", "currency": "USDC", "decimals": 2 }
  },
  "capture": "immediate",
  "payee": { "role": "payee", "id": "merchant-settlement", "kind": "wallet" },
  "payment_session": {
    "scheme": "x402",
    "session_id": "x402-session-001",
    "resource": "https://merchant.example/x402/sessions/x402-session-001"
  },
  "fulfillment_intent": { "mode": "digital", "destination_ref": "acct-buyer-001" }
}

Validation commands

This README is the canonical command surface for repository validation. Other docs should reference this section instead of duplicating the full command block.

npm install
npm test
npm run validate:schemas
npm run validate:examples
npm run validate:integrity
npm run generate:checksums
sha256sum -c checksums.txt

• npm test runs the full current-line validation aggregate (npm run validate).
• npm run validate:schemas checks current-line metadata, package boundary, schema identity, layout, and manifest/index alignment expectations.
• npm run validate:examples validates every shipped v1.1.0 JSON valid and invalid example fixture against the canonical schemas.
• npm run validate:integrity verifies the canonical shipped payload scope and hash coverage for the current release line.
• checksums.txt intentionally covers the shipped boundary excluding the ledger itself: manifest.json, schemas/v1.1.0/, examples/v1.1.0/, LICENSE, README.md, and index.js.
• npm run validate:pack checks that npm pack --dry-run contains only the canonical shipped boundary plus npm-emitted package.json.

Agent Cards and Commons alignment

Agent Cards v1.1.0 should bind directly to the current flat commercial schema URIs published by this repository. They should not point at the historical v1.0.0 requests/ or receipts/ paths when declaring current-line commercial capability.

The manifest.json alignment metadata is intentionally declarative only. It records the intended version pairing with Protocol-Commons and Agent Cards, but it must not be read as machine-verified cross-repository enforcement on its own.

Protocol-Commons and Protocol-Commercial therefore tell one coherent story:

• Commons defines base actions.
• Commercial defines monetized overlays.
• Agent Cards point at the current flat commercial schema paths.
• Legacy nested v1.0.0 paths remain in the repository only as historical source material.

Checksum boundary and provenance summary

The checksum boundary is defined normatively in SPEC.md and governed by POLICY.md.

checksums.txt is the generated hash ledger for the shipped payload; it describes that surface but is not itself part of the hashed payload, so checksum verification confirms covered files only relative to the checked-in checksums.txt ledger and does not independently authenticate that ledger. Repository docs outside the shipped package surface remain authoritative guidance inside the repo, but they are not shipped or checksum-covered unless package metadata is expanded deliberately in a later release.

For external verification, the minimal path is:

1. Inspect manifest.json to confirm the current line is v1.1.0.
2. Run npm run validate:integrity.
3. Run sha256sum -c checksums.txt.
4. Load schemas/v1.1.0/index.json and bind validators from the listed request and receipt schema paths.
5. Ignore v1.0.0 unless you are consulting repository-only historical material during migration work.