From 0c1112f39b641dafad1a084b9fdd65836b7c23b7 Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Wed, 18 Mar 2026 11:56:48 -0400 Subject: [PATCH] docs: align v1.1.0 commons documentation --- README.md | 531 +++++++++++++++++++++++------------------------------ SCHEMAS.md | 305 +++++++++++++++++------------- SPEC.md | 364 +++++++++++++++++++----------------- 3 files changed, 594 insertions(+), 606 deletions(-) diff --git a/README.md b/README.md index aa75d20..bb4f07f 100644 --- a/README.md +++ b/README.md @@ -8,56 +8,55 @@ [![CI Status](https://img.shields.io/github/actions/workflow/status/commandlayer/protocol-commons/validate.yml?branch=main&label=CI)](https://github.com/commandlayer/protocol-commons/actions/workflows/validate.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/commandlayer/protocol-commons/blob/main/LICENSE) - ----- +--- ## Why Now Autonomous agents are finally leaving the lab — but without shared meaning, they fragment into isolated API silos. -CommandLayer establishes the first **semantic contract for agents**: +CommandLayer separates the stack into clear responsibilities: -- **ENS** provides universal identity -- **x402** enables verifiable machine-to-machine execution -- **Protocol-Commons** defines **the shared language** those machines speak +- **Protocol-Commons** defines the shared semantic layer +- **Identity and discovery layers** can resolve who an agent is and where it can be reached +- **Execution and payment layers** can transport, meter, or settle work around those semantics -This is the foundation of the machine economy — -**without semantics, nothing interoperates.** +Protocol-Commons is the foundation for portable machine intent: a stable set of verbs plus strict JSON Schemas for requests and receipts. ----- +--- > **Integrity Notice — Protocol-Commons v1.1.0** > > Canonical schemas are pinned and immutable: -> `schemas/v1.1.0/commons` — CID: `PENDING` +> `schemas/v1.1.0/commons` — CID: `TBD (pre-release)` > > Historical v1.0.0 artifacts remain in-repo for compatibility and verification. > > Verify integrity locally: > ```bash -> sha256sum -c checksums.txt +> npm run checksums:verify > ``` > -> Any mismatch indicates **untrusted or modified artifacts**. -> New versions MUST use a new version directory + new CID. +> Any mismatch indicates modified artifacts. +> New versions MUST use a new version directory and, once published, a new CID. --- Without a shared verb layer, ecosystems degrade into: -- Ad-hoc verbs and incompatible dialects -- No trustable receipts -- No cross-runtime interoperability -- Closed vendor silos with fragile glue logic +- Ad-hoc verbs and incompatible dialects +- Ambiguous receipts with inconsistent evidence +- No cross-runtime interoperability +- Closed vendor silos with fragile glue logic -**Protocol-Commons** fixes this with a global, canonical **action language**: +**Protocol-Commons** fixes this with a canonical action language: -- Verbs + JSON Schemas + strict validation = -- **Machine intent you can trust.** +- Verbs + JSON Schemas + strict validation +- Stable request envelopes +- Signed receipts with hash-based verification evidence -If agents can’t agree on what actions mean → **nothing works.** +If agents cannot agree on what actions mean, interoperability breaks. ----- +--- ## Real verbs. Real receipts. @@ -66,7 +65,7 @@ If agents can’t agree on what actions mean → **nothing works.** { "verb": "summarize", "version": "1.1.0", - "input": "CommandLayer defines the semantics of agent behavior.", + "input": "CommandLayer Commons v1.1.0 simplifies every request into a flat verb/version/input shape and narrows receipts to signed execution evidence.", "mode": "brief" } @@ -75,81 +74,134 @@ If agents can’t agree on what actions mean → **nothing works.** "verb": "summarize", "version": "1.1.0", "status": "ok", - "timestamp": "2026-03-18T00:00:00Z", - "agent": "commandlayer.eth", - "request_hash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", - "summary": "Semantic verb layer for autonomous multi-agent workflows.", - "signature": "Q29tbWFuZExheWVyU2lnbmF0dXJlRXhhbXBsZV8xMjM0NTY" + "timestamp": "2026-03-18T12:00:00Z", + "agent": "summarizeagent.eth", + "request_hash": "sha256:1111111111111111111111111111111111111111111111111111111111111111", + "result_hash": "sha256:2222222222222222222222222222222222222222222222222222222222222222", + "result_cid": "bafybeisummarizereceiptokexample0001", + "summary": "Commons v1.1.0 makes requests smaller and receipts easier to verify while preserving stable verb semantics.", + "signature": "sigAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } ``` -**Same shape — everywhere: -SDKs → Runtimes → x402 → ENS → Receipts** +Every v1.1.0 Commons receipt uses the same evidence-oriented spine: + +- `status` +- `timestamp` +- `agent` +- `request_hash` +- `result_hash` *(optional)* +- `result_cid` *(optional)* +- `summary` *(required on success)* +- `signature` +- `error` *(required on error)* --- + ## Quickstart -Install Commons + AJV: +Install Commons and AJV: +```bash +npm install @commandlayer/commons ajv ajv-formats ajv-errors ``` -npm install @commandlayer/commons ajv -``` -**Validate a request against a canonical verb schema** +**Validate all schemas and examples with the repo's working commands** + +```bash +npm install +npm run validate ``` -npx cl-validate examples/v1.1.0/commons/summarize/json/valid/001-summarize.request.valid.json -# ✓ VALID — trace: bafybeieoynknza... + +**Validate a specific example against the published schema using AJV** + +```bash +node --input-type=module <<'EOF_NODE' +import Ajv2020 from 'ajv/dist/2020.js'; +import addFormats from 'ajv-formats'; +import fs from 'node:fs'; +import summarizeRequestSchema from './schemas/v1.1.0/commons/summarize/summarize.request.schema.json' with { type: 'json' }; + +const ajv = new Ajv2020({ strict: true, allErrors: true, strictRequired: false, allowUnionTypes: false }); +addFormats(ajv); + +const validate = ajv.compile(summarizeRequestSchema); +const data = JSON.parse(fs.readFileSync('./examples/v1.1.0/commons/summarize/json/valid/001-summarize.request.valid.json', 'utf8')); + +console.log(validate(data)); +console.log(validate.errors ?? []); +EOF_NODE ``` + **Programmatic usage (Node.js/ESM)** -``` -import Ajv from "ajv"; -import { analyzeRequestV110 } from "@commandlayer/commons"; +```js +import Ajv2020 from 'ajv/dist/2020.js'; +import addFormats from 'ajv-formats'; +import summarizeRequestSchema from '@commandlayer/commons/schemas/v1.1.0/commons/summarize/summarize.request.schema.json' with { type: 'json' }; -const ajv = new Ajv({ strict: true, allErrors: true }); -const validate = ajv.compile(analyzeRequestV110); +const ajv = new Ajv2020({ strict: true, allErrors: true, strictRequired: false, allowUnionTypes: false }); +addFormats(ajv); + +const validate = ajv.compile(summarizeRequestSchema); const input = { - verb: "analyze", - version: "1.1.0", - input: "CommandLayer defines semantics.", - mode: "extract" + verb: 'summarize', + version: '1.1.0', + input: 'CommandLayer Commons v1.1.0 simplifies every request into a flat shape.', + mode: 'brief' }; -console.log(validate(input)); // true or false -console.log(validate.errors); // diagnostics if invalid -``` -**Generate TypeScript types directly from schemas** for zero-drift validation: +console.log(validate(input)); +console.log(validate.errors ?? []); ``` -npx ajv compile -s schemas/v1.1.0/commons -o dist/types.d.ts -``` ---- +--- ## Commons v1.1.0 -Commons v1.1.0 introduces a simplified schema surface for general-purpose agent actions. The new `schemas/v1.1.0/commons` family is fully self-contained: each request and receipt schema stands alone, uses no shared `$ref` dependencies, and keeps the Commons layer flat and minimal. +Commons v1.1.0 introduces a simplified, flat schema surface for general-purpose agent actions. -Commons is the general-purpose primitive layer for interoperable agent actions. Commercial and x402-specific packaging remain separate concerns and are not part of the Commons v1.1.0 request/receipt schema family. Earlier versions remain in the repo for compatibility and historical reference. +- Each request schema is standalone +- Each receipt schema is standalone +- No shared `$ref` dependency tree is required for v1.1.0 Commons +- Commercial, transport, and payment envelopes are out of scope for Commons itself -Example standalone schema paths: +Example schema paths: - `schemas/v1.1.0/commons/analyze/analyze.request.schema.json` - `schemas/v1.1.0/commons/analyze/analyze.receipt.schema.json` -Every v1.1.0 Commons receipt shares the same trust spine: +The request contract is intentionally small: -- `status` -- `timestamp` -- `agent` -- `request_hash` -- `result_hash` -- `result_cid` -- `summary` -- `signature` -- `error` +```json +{ + "verb": "", + "version": "1.1.0", + "input": "", + "mode": "" +} +``` + +The receipt contract is proof-oriented rather than transport-oriented: + +```json +{ + "verb": "", + "version": "1.1.0", + "status": "ok | error", + "timestamp": "", + "agent": "", + "request_hash": "sha256:<64 lowercase hex chars>", + "result_hash": "sha256:<64 lowercase hex chars>", + "result_cid": "", + "summary": "", + "signature": "", + "error": "" +} +``` -These schemas are intended to be easy to pin, easy to validate, and easy to consume directly from the package exports. +These fields let consumers verify that a signer attested to a specific request hash and, when present, a specific result hash or result CID. Commons does not define transport settlement, execution proofs beyond these fields, or any x402-specific wrapping. ## Table of Contents - [Real verbs. Real receipts.](#real-verbs-real-receipts) @@ -171,78 +223,64 @@ These schemas are intended to be easy to pin, easy to validate, and easy to cons - [Next Layers](#next-layers) - [References](#references) - --- ## Why this exists -Fragmented agents → isolated ecosystems → brittle automation. +Fragmented agents create isolated ecosystems and brittle automation. Protocol-Commons delivers: - **Shared semantics** -- **Typed request/receipt envelopes** -- **Receipt-level provability** +- **Typed request and receipt envelopes** +- **Signed receipts bound to request hashes** - **Portable behavior across runtimes** -- **Open standards alignment → one shared language for all autonomous agents** - - JSON Schema 2020-12 - - x402 - - ERC-8004 +- **A stable foundation other layers can build around** + +--- - --- - ## What Commons enables - **Deterministic action contracts** - **Runtime-level validation** -- **Trustable receipts** +- **Receipt verification through hashes and signatures** - **Cross-vendor interoperability** -- **Future-proof machine intent** +- **Versioned, immutable semantics** -Protocol-Commons is the **semantic foundation** of the CommandLayer stack. +Protocol-Commons is the semantic foundation of the CommandLayer stack. --- ## Canonical Verbs -The Commons defines 10 universal actions used across nearly all multi-agent workflows: +The Commons defines 10 universal actions used across common multi-agent workflows: +| Verb | Purpose | Guarantees | +|-----------|-------------------------------------------------------|--------------------------------------------------------| +| analyze | Extract insights from structured or unstructured data | Identifies meaning, relationships, or signals | +| classify | Categorize input according to a known schema | Deterministic label assignment | +| clean | Normalize or remove noise from data | Output retains meaning with improved quality | +| convert | Transform between formats or representations | Equivalent content in a different representation | +| describe | State what something *is* | Attributes, context, or defining properties | +| explain | State *why* or *how* something is true | Causal or relational justification | +| fetch | Retrieve data from a remote or indirect source | Receipt can attest to the requested content retrieval | +| format | Produce content in a structured or presentable shape | Output conforms to the declared representation intent | +| parse | Extract structured meaning from raw input | Typed structure extracted from unstructured content | +| summarize | Compress content while preserving key meaning | Core information retained with reduced verbosity | -| Verb | Purpose | Guarantees | -|-----------|------------------------------------------------------ |----------------------------------------------------------| -| analyze | Extract insights from structured or unstructured data | Identifies meaning, relationships, or signals | -| classify | Categorize input according to a known schema | Deterministic label assignment | -| clean | Normalize or remove noise from data | Output retains meaning with improved quality | -| convert | Transform between formats or representations | Semantically-equivalent output with different encoding | -| describe | State what something *is* | Attributes, context, or defining properties | -| explain | State *why* or *how* something is true | Causal or relational justification | -| format | Produce content in a structured/presentable shape | Output conforms to declared structure | -| parse | Extract structured meaning from raw input | Typed output from unstructured content | -| summarize | Compress content while preserving key meaning | Core information retained; verbosity reduced | -| fetch | Retrieve data from a remote or indirect source | Integrity of returned content | +Each verb defines: +- a canonical request format +- a canonical receipt format -**Each verb defines:** - -- a canonical **request** format -- a canonical **receipt** format -- strict typing and deterministic envelopes for x402 - -``` +```text +-----------------------------+ | Execution Runtime | (action is performed) +-------------▲---------------+ | v +-----------------------------+ -| x402 Transport Layer | (invocation + settlement) -| "How messages move" | -+-------------▲---------------+ - | - v -+-----------------------------+ -| Agent Cards (Identity) | (ENS discovery + routing) -| "Who does what, and where" | +| Identity / Routing | (discovery + addressing) +-------------▲---------------+ | v @@ -250,274 +288,159 @@ The Commons defines 10 universal actions used across nearly all multi-agent work | Protocol-Commons | (verbs + schemas) | "What actions mean" | +-----------------------------+ - ``` -**Each verb provides:** - -`.request.schema.json` - -`.receipt.schema.json` - -**Schemas define:** -- `input` structure -- `output` guarantees -- `required fields` -- optional context -- `x402 envelope` shape -- trace metadata -- version locking +Each verb provides: -No aliases. -No ambiguity. -**Each verb is an immutable, canonical action definition.** +- `.request.schema.json` +- `.receipt.schema.json` --- - + ## Overview -The **Commons** repository provides the canonical, immutable **verb schemas** for the CommandLayer Protocol. +Protocol-Commons is the schema package for canonical agent verbs. -These schemas define **what an agent can do — not how it runs**. -They form the universal foundation for: +For v1.1.0, the Commons layer is intentionally flat: -- **A2A = Autonomous-to-Autonomous — no humans required in the loop.** -- **agent-to-agent** (A2A) communication -- **multi-agent workflows** -- **LLM orchestration** -- **automated systems** -- **x402-aligned** execution flows +- requests contain the action intent and caller input +- receipts contain execution status plus signer-bound evidence +- versioned directories preserve immutability over time --- -### Key Principles +## Key Principles -- **Shared semantics** — every autonomous agent speaks the same actions -- **Deterministic envelopes** — strict request & receipt schemas, version-locked -- **Trustable execution** — verifiable, auditable receipts across runtimes -- **Portable behavior** — identical contract shapes across vendors & ecosystems -- **Neutral governance** — open, MIT-licensed semantics with immutable history -- **Standards aligned** — JSON Schema 2020-12, x402 transport, ERC-8004 discovery +1. **Semantic stability** — verb meanings do not drift within a published version. +2. **Strict validation** — schemas compile under Ajv 2020-12 strict mode. +3. **Immutable releases** — published version directories are append-only historical artifacts. +4. **Minimal envelopes** — Commons defines semantics, not every higher-layer concern. +5. **Verifiable receipts** — trust comes from request hashes, optional result hashes/CIDs, and signatures. -> Commons is the **linguistic core** of CommandLayer — -> the foundation on which identity, execution, and economic layers depend. -> --- ## This is not… -To avoid confusion, Protocol-Commons does **not** define: - -- **how agents run or where they live** -- **any economic model or execution pricing** -- **identity, discovery, or routing** (that is Agent-Cards + ENS) -- **commercial enforcement or proprietary extensions** -- **agent behavior beyond typed input/output guarantees** +Protocol-Commons is **not**: -Commons defines **semantics** — nothing more, nothing less. +- a payment protocol +- an identity registry +- a transport envelope standard +- a runtime execution engine +- a guarantee of result correctness beyond the attested hashes and signer identity -Everything else is layered cleanly on top. +Those concerns can be layered on top, but they are not defined by the v1.1.0 Commons schemas. --- ## CommandLayer Protocol Stack -| Layer | Role | -|---------------------|-------------------------------------------------------------------| -| Protocol-Commons | Canonical verbs & schemas (machine intent grammar) | -| Agent-Cards | Identity, discovery, and invocation metadata | -| Protocol-Commercial | Canonical commercial/economic verbs (schemas & receipt defaults) | -| Protocol-Runtime | Transport adapters, execution, and structured receipts | - - - -- **Commons** defines what actions exist and how they are structured. -- **Agent-Cards** bind those actions to real agents. -- **Protocol-Commercial** defines market-aligned economic verbs and receipt schemas. -- **Runtime** executes those actions and returns verifiable receipts (optionally over x402). - +```text +Execution / settlement layers + ↑ +Identity / routing layers + ↑ +Protocol-Commons (semantic verbs + schemas) +``` +Commons gives upper layers a stable meaning layer to build around. --- ## Status -- Canonical verb set defined -- Fully validated under JSON Schema 2020-12 (**strict**) -- Deterministic `$id` structure -- **Pinned to IPFS** (content-addressed) -- Request + receipt schemas for **all verbs** -- `GitHub Actions` validation is **green** -- `checksums.txt` ensures **immutability** +**Stable — v1.1.0 current** -This version is the **baseline** for SDKs, registries, resolvers, and identity layers. +- `v1.1.0` is the current flat Commons layout +- `v1.0.0` remains in-repo as a legacy schema family --- - ## Repository Structure + ```text -protocol-commons/ -├── schemas/ -│ └── v1.0.0/ -│ ├── commons/ -│ │ └── / -│ │ ├── requests/ -│ │ │ └── .request.schema.json -│ │ └── receipts/ -│ │ └── .receipt.schema.json -│ └── _shared/ -│ ├── x402.schema.json -│ ├── trace.schema.json -│ └── receipt.base.schema.json +. +├── README.md +├── SCHEMAS.md +├── SPEC.md +├── checksums.txt ├── examples/ │ ├── v1.0.0/ -│ │ └── commons/ -│ │ └── / -│ │ ├── valid/ -│ │ │ └── *.json -│ │ └── invalid/ -│ │ └── *.json +│ │ └── commons//{valid,invalid}/*.json │ └── v1.1.0/ -│ └── commons/ -│ └── / -│ ├── json/ -│ │ ├── valid/ -│ │ │ └── *.json -│ │ └── invalid/ -│ │ └── *.json -│ └── ts/ -│ ├── valid/ -│ │ └── *.ts -│ └── invalid/ -│ └── *.ts -├── checksums.txt +│ └── commons//json/{valid,invalid}/*.json ├── manifest.json -├── SPEC.md -├── POLICY.md -├── GOVERNANCE.md -├── SECURITY.md -├── SECURITY_PROVENANCE.md -├── COMPLIANCE.md -├── RESOLUTION.md -├── ONBOARDING.md -└── README.md - +├── package.json +├── schemas/ +│ ├── v1.0.0/ +│ │ ├── _shared/ +│ │ └── commons//{requests,receipts}/*.schema.json +│ └── v1.1.0/ +│ └── commons// +│ ├── .request.schema.json +│ └── .receipt.schema.json +└── scripts/ + ├── ajv-run.mjs + ├── validate-all.mjs + └── validate-examples.mjs ``` -## Manifest +--- -`manifest.json` includes: +## Manifest -- repository metadata -- schema root directories -- the IPFS CID for the versioned schema folder -- a verb index with direct request/receipt paths +`manifest.json` records release metadata for the package, including: -It is **not** an identity registry. -Identity lives in **agent-cards**. +- package version +- schema and example roots +- the current schema pin target +- per-verb request and receipt schema paths +- release CID status (`TBD (pre-release)` until a real CID is published) --- ## Immutability & Checksums -**All v1.0.0 schemas are pinned to IPFS:** -``` -bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m -``` - - -`checksums.txt` contains SHA-256 hashes for every file inside `schemas/v1.0.0`, enabling: - -- **offline verification** -- **reproducible validation** -- **auditability** -- **version locking** +Use the checksum and validation scripts shipped in the repo: -### **Any schema modification requires:** - -- new version (1.0.1, 1.1.0, etc.) -- new CID -- updated checksums -- updated manifest -- updated ENS TXT references +```bash +npm run checksums:verify +npm run validate +``` -Once published, **Commons v1.0.0 is immutable**. +Published version directories must not be edited in place. --- ## Validation -**All schemas are validated using:** +Available commands: -- AJV (2020-12) strict mode -- deterministic `$id` resolution -- no type coercion -- no additionalProperties leakage -- full valid+invalid example coverage +```bash +npm run validate:schemas +npm run validate:examples +npm run validate +``` -This ensures consistent behavior across runtimes, SDKs, and agent frameworks. +These commands compile schemas in strict Ajv mode and validate the shipped examples for both `v1.0.0` and `v1.1.0`. --- ## License -MIT — open, universal, fork-friendly. -Commons is designed to remain neutral and stable. +MIT. --- ## Next Layers -CommandLayer follows a clean separation of concerns: - -- **protocol-commons** → free canonical Commons schemas (specs) -- **protocol-commercial** → free canonical Commercial schemas (specs) -- **agent-cards** → identity & discovery for agents -- **protocol-runtime** → reference execution layer (endpoints, adapters, paywalls) -- **sdk-js / sdk-python** → client libraries that interact with the runtime +Commons is designed to be composed with other layers for identity, routing, transport, payment, or settlement. Those layers can wrap Commons requests and receipts, but they should not be confused with the Commons schema contract itself. - - ---- +--- ## References -- [ERC-8004 — Agent Schema Discovery](https://eips.ethereum.org/EIPS/eip-8004) -- [x402 — Machine-to-Machine Value Transport Envelope](https://github.com/ethereum/x402) -- [JSON Schema 2020-12 — Canonical validation standard](https://json-schema.org/specification-links) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +- `SPEC.md` +- `SCHEMAS.md` +- `manifest.json` +- `schemas/v1.1.0/commons/` diff --git a/SCHEMAS.md b/SCHEMAS.md index a858605..f2b6a61 100644 --- a/SCHEMAS.md +++ b/SCHEMAS.md @@ -2,52 +2,62 @@ This document specifies stability rules, versioning constraints, and change governance for all Protocol Commons schemas. - > This document is **NORMATIVE and ENFORCEABLE**. --- ## 1. Purpose -Protocol-Commons defines the **canonical verb and schema layer** for autonomous agents: +Protocol-Commons defines the canonical verb and schema layer for autonomous agents: -- Standardized verbs -- Strict JSON Schema 2020-12 validation -- Deterministic `$id` URLs -- x402 envelope embedding -- Trace + status requirements -- Immutable versioning rules +- standardized verbs +- strict JSON Schema 2020-12 validation +- deterministic `$id` URLs +- immutable versioning rules +- flat v1.1.0 request and receipt contracts -Once published, a version directory is **immutable**. +Once published, a version directory is immutable. --- ## 2. Directory Layout +### Current layout: v1.1.0 - +```text +schemas/v1.1.0/ +└── commons/ + └── / + ├── .request.schema.json + └── .receipt.schema.json ``` + +### Legacy layout: v1.0.0 + +```text schemas/v1.0.0/ -_shared/ -x402.schema.json -trace.schema.json -receipt.base.schema.json -commons/ -/ -requests/.request.schema.json -receipts/.receipt.schema.json +├── _shared/ +│ ├── identity.schema.json +│ ├── receipt.base.schema.json +│ ├── trace.schema.json +│ ├── verb.aliases.schema.json +│ └── x402.schema.json +└── commons/ + └── / + ├── requests/.request.schema.json + └── receipts/.receipt.schema.json ``` - ### Normative Rules -- **Paths MUST NOT change once published** -- Folder names MUST match canonical verb exactly -- No aliases or synonyms permitted +- Paths MUST NOT change once published +- Folder names MUST match the canonical verb exactly +- v1.1.0 Commons schemas MUST use the flat per-verb file layout +- Nested `requests/` and `receipts/` directories are legacy-only and MUST NOT be described as the v1.1.0 layout --- -## 3. Canonical Verb Set (v1.0.0) +## 3. Canonical Verb Set | Verb | Purpose | |------|---------| @@ -56,159 +66,192 @@ receipts/.receipt.schema.json | clean | Normalize input | | convert | Transform between formats | | describe | State defining properties | -| explain | Provide causal justification | +| explain | Provide rationale or clarification | | fetch | Retrieve external data | -| format | Produce structured output | +| format | Produce structured or presentable output | | parse | Extract structured meaning | | summarize | Condense content while preserving meaning | -Each verb MUST define: +Each verb MUST define exactly: -- One request schema -- One receipt schema +- one request schema +- one receipt schema --- ## 4. Deterministic `$id` Contract -Schemas MUST include fully-qualified, HTTPS-resolvable `$id` values: +### v1.1.0 request schemas -**Requests** +```text +https://commandlayer.org/schemas/v1.1.0/commons//.request.schema.json +``` +Example: -``` -https://commandlayer.org/schemas/v1.0.0/commons//requests/.request.schema.json +```text +https://commandlayer.org/schemas/v1.1.0/commons/summarize/summarize.request.schema.json ``` -### **Receipt** -``` -https://commandlayer.org/schemas/v1.0.0/commons//receipts/.receipt.schema.json -``` -### Shared +### v1.1.0 receipt schemas + +```text +https://commandlayer.org/schemas/v1.1.0/commons//.receipt.schema.json ``` -https://commandlayer.org/schemas/v1.0.0/_shared/.schema.json + +Example: + +```text +https://commandlayer.org/schemas/v1.1.0/commons/summarize/summarize.receipt.schema.json ``` -## 5. x402 Envelope Binding +### Legacy v1.0.0 note -### Requests MUST include: +Legacy v1.0.0 schemas retain their older nested `$id` patterns and `_shared` references. Those patterns are not the v1.1.0 contract. -```json -"x402": { - "verb": "", - "version": "1.0.0" -} -``` +All `$id` values MUST be fully qualified HTTPS URLs. -### Receipts MUST include: -``` -"x402": { - "verb": "", - "version": "1.0.0", - "status": "ok" | "error" -} +--- -``` -No additional properties allowed in `x402`. -Validated by `_shared/x402.schema.json.` - -## 6. Request Contract - -Every request MUST include: - -| Field | Source | Required | -| ------- | -------------------- | :------: | -| `x402` | x402 schema | ✓ | -| `actor` | Free-form identifier | ✓ | -| `trace` | trace schema | ✓ | -| `input` | verb-specific | ✓ | - -Missing required fields MUST fail validation. - -## 7. Receipt Contract -| Field | Conditional | -| -------- | ---------------------------- | -| `x402` | Always required | -| `trace` | Always required | -| `status` | `"ok"` or `"error"` | -| `result` | Required if `status="ok"` | -| `error` | Required if `status="error"` | - -No `result` in error receipts. -No `error` in success receipts. -Validated by` _shared/receipt.base.schema.json` - - -## 8. Trace Guarantees -Fields MUST include: - -- `requestId` -- `ts` -Receipts MUST echo: -``` -trace.requestId = request.trace.requestId -``` -Optional fields (if schema supports): +## 5. v1.1.0 Request Contract + +Every v1.1.0 request MUST include: -- `parentId`, -- `callbackUri`, -- `metrics` +| Field | Required | Notes | +|-----------|----------|-------| +| `verb` | Yes | Canonical verb constant | +| `version` | Yes | Must equal `1.1.0` | +| `input` | Yes | Non-empty string | +| `mode` | No | Optional verb-specific enum | -## 9. Versioning Rules -Once published under schemas/v1.0.0/: +Requests MUST reject additional properties. -The following actions are prohibited: +v1.1.0 requests do not use nested request objects, `x402`, `trace`, or `actor` fields. -- Editing schema content -- Changing behavior or requirements -- Updating $id values +--- -Any change requires: -- New version directory (e.g., v1.0.1/) -- New CID + updated manifest & checksums -- ENS TXT update -- Governance approval +## 6. v1.1.0 Receipt Contract -## 10. Validation Requirements -CI MUST enforce: -``` +Every v1.1.0 receipt MUST include: + +| Field | Required | +|----------------|----------| +| `verb` | Yes | +| `version` | Yes | +| `status` | Yes | +| `timestamp` | Yes | +| `request_hash` | Yes | +| `signature` | Yes | + +Additional shared fields are schema-supported but optional unless conditionally required: + +| Field | Requirement | +|---------------|-------------| +| `agent` | Optional | +| `result_hash` | Optional | +| `result_cid` | Optional | +| `summary` | Required when `status = "ok"` | +| `error` | Required when `status = "error"` | + +Receipts MUST reject additional properties. + +The trust model is limited to signer attestation plus request/result hash references. Implementations MUST NOT imply unsupported receipt substructures or execution-trace guarantees. + +--- + +## 7. Legacy v1.0.0 Scope + +v1.0.0 remains in-repo for compatibility and historical verification. + +Its schemas use: + +- `_shared` helper schemas +- nested `requests/` and `receipts/` folders +- older envelope conventions + +Documentation and tooling MUST distinguish that legacy structure from v1.1.0. + +--- + +## 8. Versioning Rules + +Once published under a version directory such as `schemas/v1.1.0/`, the following actions are prohibited: + +- editing schema content in place +- changing behavior or required fields for that version +- updating `$id` values for that version +- changing the directory layout for that version + +Any change requires a new version directory. + +--- + +## 9. Validation Requirements + +CI and local validation SHOULD enforce strict schema compilation behavior equivalent to: + +```text strict: true -strictTypes: true +strictSchema: true +allErrors: true +strictRequired: false allowUnionTypes: false -strictTuples: true ``` -All valid + invalid examples MUST pass CI. -## 11. Examples -Examples are REQUIRED for every verb: +Repository validation commands: +```bash +npm run validate:schemas +npm run validate:examples +npm run validate ``` -examples/v1.0.0/commons// + +All shipped valid and invalid examples MUST match the version-specific schema layout they target. + +--- + +## 10. Examples + +Examples are maintained per version. + +### v1.1.0 examples + +```text +examples/v1.1.0/commons//json/ valid/*.json invalid/*.json ``` -Minimum: - -- 3 valid examples -- 3 invalid examples +### v1.0.0 examples -## 12. Provenance & Integrity -Pinned schemas CID: -``` -bafybeieoynknzalaojwpzjzjy77kpnfe4kla5io7jbfnmyu7w7vyvuljpq +```text +examples/v1.0.0/commons// + valid/*.json + invalid/*.json ``` -Integrity tracked by: +--- + +## 11. Provenance & Integrity + +Integrity is tracked by: - `checksums.txt` - `manifest.json` -Resolvers MUST reject mismatched artifacts. +Current v1.1.0 schema CID status: + +```text +TBD (pre-release) +``` + +Resolvers and auditors MUST reject mismatched artifacts. + +--- -## 13. Contact +## 12. Contact -email dev@commandlayer.org -PGP 5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A +- dev@commandlayer.org +- PGP 5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A -Status: Stable · v1.0.0 locked +**Status:** Stable `v1.1.0` current; `v1.0.0` legacy diff --git a/SPEC.md b/SPEC.md index e897dc3..14ee644 100644 --- a/SPEC.md +++ b/SPEC.md @@ -10,12 +10,12 @@ MUST / MUST NOT / SHOULD / SHOULD NOT / MAY retain their RFC-defined meanings. ## 1. Purpose -Protocol-Commons defines the **canonical action grammar for autonomous agents**: +Protocol-Commons defines the canonical action grammar for autonomous agents: -- **Verbs** — What actions exist -- **Request/Receipt Schemas** — Typed message contracts -- **Trace + Status rules** — Deterministic provenance -- **Versioning + Immutability** — Trust guarantees +- **Verbs** — what actions exist +- **Request schemas** — typed invocation contracts +- **Receipt schemas** — typed execution evidence contracts +- **Versioning + immutability** — trust guarantees for published artifacts Execution, payment, identity, and routing are the domain of other layers. @@ -23,18 +23,19 @@ Execution, payment, identity, and routing are the domain of other layers. ## 2. Architecture Position -The Commons is the **lowest** layer of the CommandLayer Standard Stack: -``` +The Commons is the semantic base layer of the CommandLayer stack: + +```text ┌────────────────────────────┐ -│ Execution — Runtime layer │ (value + invocation) +│ Execution / settlement │ └──────────────▲─────────────┘ -│ + │ ┌──────────────┴─────────────┐ -│ Identity — Agent-Cards │ (ENS discovery) +│ Identity / routing │ └──────────────▲─────────────┘ -│ + │ ┌──────────────┴─────────────┐ -│ Semantics — Commons │ (canonical verbs) +│ Semantics — Commons │ └────────────────────────────┘ ``` @@ -42,259 +43,280 @@ The Commons is the **lowest** layer of the CommandLayer Standard Stack: --- -## 3. Canonical Verb Set (v1.0.0) +## 3. Canonical Verb Set The only canonical verbs are: -analyze, classify, clean, convert, describe, -explain, fetch, format, parse, summarize - +`analyze`, `classify`, `clean`, `convert`, `describe`, `explain`, `fetch`, `format`, `parse`, `summarize` Each verb MUST map to: - `.request.schema.json` - `.receipt.schema.json` -No aliases. No synonyms. +No aliases or synonyms are canonical. --- -## 4. Schema Directory Contract +## 4. Commons v1.1.0 -Every schema file MUST reside under: +Commons v1.1.0 is the current schema family for this repository. -schemas/v1.0.0/commons// +### 4.1 Directory contract -- `requests/.request.schema.json` -- `receipts/.receipt.schema.json` +Every v1.1.0 schema file MUST reside under: -**Shared primitives located at:** +```text +schemas/v1.1.0/commons// +``` -schemas/v1.0.0/_shared/ +with exactly these file names: -- `x402.schema.json` -- `trace.schema.json` -- `receipt.base.schema.json` +- `.request.schema.json` +- `.receipt.schema.json` -**Directory is version-locked.** -Moving files is a breaking change. +Moving published files is a breaking change. ---- +### 4.2 Request shape (flat) -## 5. Schema `$id` Rules (Deterministic) +Every v1.1.0 request MUST be a flat JSON object with: -Every schema **MUST** use this `$id` pattern: +| Field | Required | Constraints | +|-----------|----------|-------------| +| `verb` | Yes | String constant equal to the canonical verb | +| `version` | Yes | String constant equal to `1.1.0` | +| `input` | Yes | Non-empty string | +| `mode` | No | Verb-specific enum when present | -### Request -https://commandlayer.org/schemas/v1.0.0/commons//requests/.request.schema.json +Requests MUST NOT include undeclared properties. +A conforming request shape is: +```json +{ + "verb": "", + "version": "1.1.0", + "input": "", + "mode": "" +} +``` -### Receipt -https://commandlayer.org/schemas/v1.0.0/commons//receipts/.receipt.schema.json +Commons v1.1.0 does not require `x402`, `trace`, `actor`, or nested request wrappers. + +### 4.3 Receipt shape + +Every v1.1.0 receipt MUST be a flat JSON object with these shared fields: + +| Field | Required | Constraints | +|---------------|----------|-------------| +| `verb` | Yes | String constant equal to the canonical verb | +| `version` | Yes | String constant equal to `1.1.0` | +| `status` | Yes | `"ok"` or `"error"` | +| `timestamp` | Yes | RFC 3339 / JSON Schema `date-time` | +| `request_hash`| Yes | `sha256:` followed by 64 lowercase hex chars | +| `signature` | Yes | Base64url-style string, min length 32 | +| `agent` | No | Non-empty string signer identity | +| `result_hash` | No | `sha256:` followed by 64 lowercase hex chars | +| `result_cid` | No | Non-empty string content identifier | +| `summary` | Cond. | REQUIRED when `status = "ok"` | +| `error` | Cond. | REQUIRED when `status = "error"` | + +Receipts MUST NOT include undeclared properties. + +A conforming success receipt shape is: + +```json +{ + "verb": "", + "version": "1.1.0", + "status": "ok", + "timestamp": "", + "agent": "", + "request_hash": "sha256:<64 lowercase hex chars>", + "result_hash": "sha256:<64 lowercase hex chars>", + "result_cid": "", + "summary": "", + "signature": "" +} +``` + +A conforming error receipt shape is: + +```json +{ + "verb": "", + "version": "1.1.0", + "status": "error", + "timestamp": "", + "request_hash": "sha256:<64 lowercase hex chars>", + "signature": "", + "error": "" +} +``` +### 4.4 Trust model -### Shared -https://commandlayer.org/schemas/v1.0.0/_shared/.json +Commons v1.1.0 provides attestation-oriented receipts: +- `request_hash` binds the receipt to a specific request payload +- `result_hash` and `result_cid`, when present, bind the receipt to a specific result payload or content address +- `signature` binds the signer to the receipt contents +- `agent`, when present, identifies the signer in a stable application-level form -All `$id` values MUST be resolvable over HTTPS. +Commons v1.1.0 does **not** define settlement proofs, transport-level guarantees, execution traces, or result-object substructures. --- -## 6. x402 Envelope Binding +## 5. v1.0.0 Legacy Status -All requests MUST embed: +`v1.0.0` remains in the repository as a legacy schema family for compatibility and historical verification. -```jsonc -"x402": { - "verb": "", - "version": "1.0.0" -} -``` -All receipts MUST embed: - -``` -"x402": { - "verb": "", - "version": "1.0.0", - "status": "ok" | "error" -} -``` +Its structure differs materially from v1.1.0: -No additional properties permitted inside x402. +- nested request/receipt directories +- `_shared` referenced schemas +- transport-oriented `x402` and `trace` concepts ---- +Implementers MUST NOT project those legacy requirements onto v1.1.0. -## 7. Trace Guarantees -Every receipt MUST echo: +Legacy path pattern: -``` -trace.requestId = request.trace.requestId +```text +schemas/v1.0.0/commons//requests/.request.schema.json +schemas/v1.0.0/commons//receipts/.receipt.schema.json ``` -This is REQUIRED for chaining & auditability. +--- -Additional trace fields MAY exist (per `_shared/trace.schema.json`) -but MAY NOT weaken determinism or referential integrity. +## 6. Schema `$id` Rules ---- +Every v1.1.0 schema MUST use a resolvable HTTPS `$id` under this pattern. -## 8. Request Contract -Requests MUST contain: +### Request -| Field | Required | Source | -| ------- | -------- | --------------------------- | -| `x402` | Yes | `_shared/x402.schema.json` | -| `trace` | Yes | `_shared/trace.schema.json` | -| `input` | Yes | Verb-specific | +```text +https://commandlayer.org/schemas/v1.1.0/commons//.request.schema.json +``` +### Receipt + +```text +https://commandlayer.org/schemas/v1.1.0/commons//.receipt.schema.json +``` -Requests MUST validate in **strict Ajv mode.** +Legacy v1.0.0 `$id` layouts remain valid only for the legacy directory tree. --- -## 9. Receipt Contract -Receipts MUST contain: +## 7. Validation Requirements -| Field | Required | Conditional | -| -------- | -------- | ------------------- | -| `x402` | Yes | Always | -| `trace` | Yes | Always | -| `status` | Yes | `"ok"` or `"error"` | -| `result` | Yes | IF `status = ok` | -| `error` | Yes | IF `status = error` | +Implementations claiming v1.1.0 compatibility MUST: +1. Validate requests and receipts against the exact published schema files +2. Use JSON Schema draft 2020-12 support +3. Compile schemas in strict Ajv mode or equivalent +4. Reject undeclared properties +5. Enforce conditional receipt logic for `summary` and `error` -Strict conditional logic is canonical and MUST pass CI validation. +Repository validation commands are: -Error receipts MUST NOT include `result.` +```bash +npm run validate:schemas +npm run validate:examples +npm run validate +``` --- -## 10. Versioning + Immutability +## 8. Versioning + Immutability -Once published under: -``` -schemas/v1.0.0/ -``` +Once published under a version directory such as: -There MUST NEVER be: +```text +schemas/v1.1.0/ +``` -- File content changes -- Field requirement changes -- `$id` changes -- Behavior changes +there MUST NEVER be in-place mutation of: -Any mutation requires: +- schema file contents +- required field sets +- `$id` values +- documented semantics for that version -- New version directory (e.g. v1.0.1/) -- New CID -- Updated checksums + manifest -- ENS TXT update -- Governance approval +Any semantic or structural change requires a new version directory. --- -## 11. Provenance & Integrity (NORMATIVE) - -The canonical Protocol-Commons v1.0.0 release is uniquely identified by: -- Version directory: `schemas/v1.0.0/` -- Git tag: `commons-v1.0.0` -- IPFS directory CID: - `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` -- File-level hashes: `checksums.txt` (SHA-256) +## 9. Provenance & Integrity -Auditors and resolvers MUST: +The canonical Protocol-Commons v1.1.0 release is identified by: -1. Fetch `schemas/v1.0.0/` via HTTP(S) or IPFS using the canonical CID -2. Verify integrity: +- Version directory: `schemas/v1.1.0/` +- Package version: `1.1.0` +- Manifest entry: `manifest.json` +- File-level hashes: `checksums.txt` +- IPFS directory CID: `TBD (pre-release)` until a release CID is published - ```bash - sha256sum -c checksums.txt - ``` - -3. Treat any mismatch as an integrity failure and reject trust -`schemas/v1.0.0/` is immutable. +Auditors and resolvers SHOULD: -Any semantic change requires a new version directory. +1. Fetch the versioned schemas +2. Verify integrity locally +3. Treat mismatched artifacts as untrusted ---- - -## 12. Discovery + ENS TXT Responsibilities +Integrity check command: -Protocol-Commons governs **schema-related** TXT keys only: -``` -cl.verb -cl.version -cl.schema.request -cl.schema.receipt -cl.cid.schemas -cl.schemas.mirror.ipfs +```bash +npm run checksums:verify ``` -These keys MUST: -- **match the canonical schema metadata exactly** -- **resolve to the published CID-linked artifacts** -- be updated **only** when a new version is released and - recorded in `RESOLUTION.md` - -Resolvers MUST treat any mismatch as an **unauthenticated schema binding** and MUST NOT trust the resolution. - -Identity + invocation TXT keys (e.g., `cl.entry`, `cl.agentcard`) are governed by **Agent-Cards**, not Protocol-Commons. - --- -## 13. Implementations MUST: +## 10. Implementations MUST - 1. Validate requests & receipts in Ajv strict (2020-12) - 2. Support schema resolution from $id URLs - 3. Mirror schema CIDs correctly - 4. Treat version directories as immutable - 5. Respect full trace echo +An implementation supporting Commons v1.1.0 MUST: -A system supporting ANY canonical verb MAY claim: +1. Support the canonical verb names exactly +2. Validate the flat request shape exactly as published +3. Validate the flat receipt shape exactly as published +4. Treat published version directories as immutable +5. Preserve receipt trust semantics as hashes plus signatures, without inventing unsupported guarantees -**Commons-Compatible** +A system supporting any canonical verb MAY claim **Commons-Compatible** for that version. --- -## 14. Failure Modes +## 11. Failure Modes -If ANY of the following occur: +If any of the following occur: - `$id` mismatch -- CID mismatch between schema and ENS TXT -- TXT keys missing or malformed -- Request or receipt fails strict validation -- Trace does not echo `requestId` -- Version directory contents differ from published checksums -- Published artifact mutated in-place +- request or receipt fails strict validation +- required conditional receipt fields are missing +- published artifacts differ from expected checksums +- published artifacts are mutated in place -Resolvers MUST treat the result as **untrusted** and SHOULD: - -- Reject the request/receipt -- Emit a diagnostic error -- Fallback to a known-good version if available +consumers MUST treat the artifact as untrusted and SHOULD reject it. Silent degradation MUST NOT occur. --- -## 15. Security -Protocol-Commons is **Security-Critical Infrastructure:** -- No PII -- No execution logic -- No proprietary references -- No commercial conditions +## 12. Security -Security escalation MUST follow repository policy (SECURITY.md). +Protocol-Commons is security-relevant infrastructure. -### Status -**Stable — v1.0.0 locked** -CommandLayer Core Standards +It does not itself define: +- payment authorization +- invocation transport security +- identity registry semantics +- result correctness proofs beyond signed, hashed attestation +Security escalation MUST follow repository policy. +--- +## Status +**Stable — v1.1.0 current** +**Legacy — v1.0.0 retained for compatibility**