diff --git a/.gitignore b/.gitignore index 6b4c4b6..c2658d7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1 @@ node_modules/ -NUL diff --git a/CHANGELOG.md b/CHANGELOG.md index e5bce7a..e9dd4b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,17 +2,20 @@ ## 1.1.0 -- Added simplified self-contained Commons schemas under `schemas/v1.1.0/commons` -- Added 10 Commons verbs as request/receipt schema pairs +Released as the current Protocol-Commons version and active schema line. + +- Added the flat Commons schema family under `schemas/v1.1.0/commons` +- Published self-contained request and receipt schemas for the 10 canonical Commons verbs - Removed shared `$ref` dependencies from the v1.1.0 Commons schema family -- Standardized Commons receipts around a minimal proof-first structure -- Added conditional receipt requirements for success/error states -- Established Commons v1.1.0 as the active in-repo schema surface for new integrations -- Retained v1.0.0 as the last pinned canonical release until v1.1.0 pinning is completed -- Preserved earlier schema versions for compatibility and historical reference +- Standardized v1.1.0 receipts around a compact attestation-oriented structure +- Documented v1.1.0 as the current release and active schema line +- Retained v1.0.0 only as a historical legacy release for compatibility review and auditing +- Clarified that HTTPS schema hosting and IPFS pinning are separate publication layers ## 1.0.0 +Historical legacy release. + - Initial Protocol-Commons release with versioned Commons schemas, shared primitives, and example vectors under `schemas/v1.0.0` and `examples/v1.0.0` - Introduced the canonical Commons verb set and request/receipt validation model for cross-runtime interoperability -- Established the historical pinned release line that `v1.1.0` now extends as the current in-repo schema family +- Established the legacy schema layout that predates the flat v1.1.0 structure diff --git a/COMPLIANCE.md b/COMPLIANCE.md index da4b886..08f2ce3 100644 --- a/COMPLIANCE.md +++ b/COMPLIANCE.md @@ -1,6 +1,6 @@ # Compliance — Protocol Commons -This document defines what it means to be Protocol-Commons compliant and how to **assert** and **maintain** that status over time. +This document defines what it means to be Protocol-Commons compliant and how to assert that status accurately. --- @@ -8,18 +8,11 @@ This document defines what it means to be Protocol-Commons compliant and how to These rules apply to: -- Schemas under `schemas/v*/commons/` -- Shared primitives under `schemas/v*/_shared/` -- Examples under `examples/v*/commons/` +- schemas under `schemas/v*/commons/` +- shared primitives under `schemas/v*/_shared/` +- examples under `examples/v*/commons/` -**ENS TXT Summary** -This document only summarizes TXT responsibilities. -The canonical definitions and enforcement rules are specified in: -- `SPEC.md` (Protocol-Commons) - -Compliance cannot override normative definitions in SPEC.md. - -Compliance covers semantics and schema integrity only—identity bindings are governed by Agent-Cards. +Compliance cannot override normative definitions in `SPEC.md`. --- @@ -29,32 +22,31 @@ Compliance claims MUST identify the version they apply to. Current repository status: -- **v1.1.0** — current canonical HTTPS-hosted schema family; repository metadata still records IPFS CID publication as pending -- **v1.0.0** — historical pinned release line +- **v1.1.0** — current release and active schema line +- **v1.0.0** — historical legacy release A system MAY claim **v1.1.0 schema compatibility** if it validates and enforces the published v1.1.0 schemas. -A system MUST describe provenance accurately and MUST NOT claim that v1.1.0 is the historical pinned release while IPFS CID publication remains unpublished in repository metadata. - --- -## 3. Versioning & Immutability +## 3. Versioning and Immutability -For any directory `schemas/vX.Y.Z/`: +For any directory `schemas/vX.Y.Z/`, there are no in-place edits to: -No in-place edits to: -- Request/receipt schemas +- request or receipt schemas - `_shared` primitives - `$id` values -- Normative behavior +- normative behavior Any semantic change requires: -- New version directory -- Updated CIDs + checksums for canonical releases -- Logged update in `RESOLUTION.md` -- Governance approval -Mutating a published version is **not compliant**. +- a new version directory +- updated `manifest.json` metadata +- updated `checksums.txt` when schema artifacts change +- a logged update in `RESOLUTION.md` +- governance approval + +Mutating a published version is not compliant. --- @@ -62,48 +54,45 @@ Mutating a published version is **not compliant**. All Protocol-Commons schemas MUST: -- Use JSON Schema Draft 2020-12 -- Validate under **Ajv strict mode** -- Use deterministic HTTPS-resolvable `$id` values matching SPEC.md -- Enforce the version-specific input + receipt contract - -Loose validation or altered `$id` resolution is **not compliant**. +- use JSON Schema Draft 2020-12 +- validate under strict Ajv mode or equivalent +- use deterministic HTTPS-resolvable `$id` values matching `SPEC.md` +- enforce the version-specific request and receipt contract --- -## 5. CIDs & Checksums - -Each canonical release MUST: +## 5. Release Metadata and Integrity Requirements -- Pin the entire version folder to IPFS -- Provide SHA-256 checksums -- Publish `manifest.json` +Each release MUST include: -Compliance requires: +- `checksums.txt` +- `manifest.json` +- versioned schema paths -- Canonical TXT/CID bindings only for fully published releases -- IPFS mirrors match HTTP mirrors exactly for pinned releases +Releases claimed as canonically pinned on IPFS MUST also include: -Consumers SHOULD verify `checksums.txt` against the published schema -artifacts prior to use. +- a recorded CID for the relevant version +- IPFS publication metadata that matches the release contents -Automated resolvers and runtimes MUST verify checksums as part of -canonical compliance, and MUST reject mismatches. +Compliance requires: -Mismatch = **integrity failure** +- checksum verification against shipped schema artifacts +- manifest metadata that matches the version being claimed +- accurate separation of HTTPS hosting and IPFS publication state -For v1.1.0 specifically, the schemas and checksums can be validated locally, and compliance statements MUST distinguish the current canonical HTTPS-hosted line from the historical pinned release until IPFS CID publication is complete. +IPFS pinning is required for canonical publication when that publication mode is being claimed. --- -## 6. Security & Privacy +## 6. Security and Privacy -Schemas are **semantic infrastructure**, not application output. +Schemas are semantic infrastructure, not application output. Therefore: -- No PII -- No secrets or private routing data -- No execution logic + +- no PII +- no secrets +- no embedded execution logic Security incidents MUST follow `SECURITY.md`. @@ -112,10 +101,12 @@ Security incidents MUST follow `SECURITY.md`. ## 7. Governance Traceability Every canonical change MUST be reflected in: -- `RESOLUTION.md` (what + why + who) -- `SECURITY_PROVENANCE.md` (CIDs + checksums) -An artifact **without a governance trail** is not canonical. +- `RESOLUTION.md` for what changed and why +- `manifest.json` for release metadata +- `checksums.txt` when schema artifacts change + +An artifact without a documented governance trail is not canonical. --- @@ -123,38 +114,31 @@ An artifact **without a governance trail** is not canonical. Commons-compliant implementations SHOULD: -- Support ERC-8004 discovery where relevant -- Apply only the requirements that are normative for the version they implement +- support only the version-specific requirements they actually implement +- distinguish v1.1.0 flat contracts from v1.0.0 legacy structures For v1.0.0 legacy implementations, that can include older `x402` envelope and `trace` requirements. -For v1.1.0 implementations, those older `x402` and `trace` requirements are **not automatically normative** unless another layer explicitly adopts them outside the Commons schemas. - -Divergence from the version-specific Commons contract means **compliance claims then MUST NOT be made**. +For v1.1.0 implementations, those older requirements are not automatically normative unless another layer adopts them separately. --- -## 9. Deviation Handling +## 9. Future Hardening -If a deviation is found: +Future hardening MAY add optional signed publication mechanisms, but those mechanisms are not part of the current compliance baseline. -1. File an Issue (or follow `SECURITY.md` if sensitive) -2. Describe affected version and impact -3. Steward determines whether to publish a corrected version -4. Changes documented in `RESOLUTION.md` +Until then, the required baseline is checksum verification plus documented release metadata. --- ## 10. Compliance Checklist -You may claim **Protocol-Commons compliant** for a specific version if: - -- Strict Ajv validation enforced -- Version directories treated as immutable -- `$id` URLs resolve correctly -- CIDs and checksums match content when the version is claimed as canonical and pinned -- Changes logged and signed -- ENS TXT duties respected per SPEC.md -- Version status is described accurately as current canonical HTTPS-hosted or historical pinned release +You may claim Protocol-Commons compliance for a specific version if: -If uncertain → treat the implementation as **experimental**. +- strict Ajv validation is enforced +- version directories are treated as immutable +- `$id` URLs resolve correctly +- releases include checksums +- releases include manifest metadata +- IPFS publication state is described accurately when applicable +- version status is described accurately as current or historical diff --git a/GOVERNANCE.md b/GOVERNANCE.md index bb6e312..c6d5eda 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,189 +1,123 @@ # Governance — Protocol Commons -**Scope:** Protocol-Commons (primary), Agent-Cards (identity bindings) -**Status:** v1.0.0 — Historical Pinned Release; v1.1.0 — Current Canonical Working Line +**Scope:** Protocol-Commons +**Status:** v1.1.0 current release and active schema line; v1.0.0 historical legacy release -> This governance is **NORMATIVE, ENFORCEABLE, AND PERMANENT**. -> Control is custodial today and **designed to decentralize** as adoption grows. +> This governance document is normative for repository process and change control. --- -## 1. Mandate of Commons Governance +## 1. Governance Mandate -Protocol-Commons governs **semantic truth**: +Protocol-Commons governance maintains: -- Canonical verbs -- Request/receipt schemas -- TXT semantics for schema binding -- Normative version changes -- Immutable historical provenance +- canonical verb definitions +- request and receipt schema policy +- versioning discipline +- release documentation +- publication records -It MUST protect: - -- **Machine-readable meaning** -- **Interoperability continuity** -- **Permanent public access** - -> **Commons is the constitution of agent intent.** -> Everything else derives authority from it — not the other way around. +Its purpose is procedural: preserve stable semantics, transparent changes, and consistent release records. --- -## 2. Strict Scope Limits — NORMATIVE - -### Commons MAY govern: -- Semantic contracts (schema language, grammar, behavior) -- Required validation mode (strict, draft 2020-12) -- TXT keys that bind semantic truth (`cl.schema.*`) +## 2. Scope Limits -### Commons MUST NOT govern: -- Pricing or economics -- Runtime topology -- Execution performance or SLAs -- Vendor-specific commercial logic +Governance MAY define: -Commercial and Runtime layers MUST remain **subordinate**: +- semantic contracts +- validation requirements +- schema publication rules +- release documentation requirements -> **Execution is business. -> Semantics are public goods.** +Governance MUST NOT define: -Commercial schemas may reference Commons semantics — they **may not alter them**. +- pricing +- runtime topology +- service levels +- vendor-specific business logic - -- **SPEC.md is the single source of normative truth.** -- Where documents disagree, **SPEC.md SHALL prevail** without exception. +`SPEC.md` remains the primary normative source for schema behavior. --- -## 3. Stewardship — Bootstrap to Neutrality - -**Founding Steward:** `commandlayer.eth` - -Responsible for: +## 3. Stewardship -- Canonical schema publishing -- Signed manifest + checksum updates -- Security revocations + provenance logs -- Transparency for all normative decisions +**Founding Steward:** `commandlayer.eth` -### Decentralization Phases +Stewardship responsibilities include: -| Phase | Governance Form | Trigger | -|-------|----------------|---------| -| 1 — Bootstrap | Single-operator Safe | Initial production adoption | -| 2 — Multi-Maintainer | ≥3 independent vendors in Safe | Cross-vendor reliance | -| 3 — Standards Committee | Public RFC review + voting | Global ecosystem dependence | -| 4 — Neutral Standards Body | Community-elected | Entrenched industry standard | +- publishing schema releases +- maintaining manifest metadata and checksums +- recording governance decisions in repository documents +- handling security disclosures and release corrections -Vendor diversity REQUIRED — **no single affiliation may dominate**. - -A non-profit legal wrapper SHALL be established before Phase 3. +This is a procedural authority model. Repository documentation records who approved a release decision; it does not imply cryptographic enforcement. --- -## 4. Immutable Semantic Guarantees (Anti-Rug) - -Once published: - -- `$id`, CID, and version MUST NEVER change -- Historical schemas MUST remain resolvable -- Governance history MUST NOT be rewritten +## 4. Release Controls -Commercial schemas inherit similar guarantees: +Once a schema version is published: -> **Commercial schemas are permanently free** — -> **economics only occur at runtime, never in the semantic layer.** +- paths MUST NOT change in place +- schema contents MUST NOT change in place +- `$id` values MUST NOT change in place +- release history MUST remain documented -Attempts to mutate semantics in place MUST be treated as **UNTRUSTED**. +Current interpretation: -The current lock states are interpreted strictly: - -- **v1.0.0 historical pinned release** means the legacy release line with published CID, immutable checksums, and locked provenance -- **v1.1.0 current canonical HTTPS-hosted line** means the current repository contract, primary documentation target, and live HTTPS schema namespace; IPFS CID publication remains pending in repository provenance metadata +- **v1.1.0** is the current release and active schema line +- **v1.0.0** is historical legacy material only +- IPFS publication for v1.1.0 is tracked separately from HTTPS hosting in repository metadata --- -## 5. TXT Key Governance — NORMATIVE - -TXT semantics are partitioned: +## 5. ENS TXT Governance -| Prefix | Authority | Meaning | Mutation Allowed? | -|--------|-----------|---------|------------------| -| `cl.schema.*` | Commons | Semantic bindings | NEVER | -| `cl.agentcard` | Agent-Cards | Identity binding | NEVER (per version) | -| `cl.runtime.*` | Runtime | Operational endpoints | Yes, logged | +TXT semantics are versioned publication metadata. -Resolvers MUST: +Resolvers SHOULD: -- Reject TXT ↔ CID mismatches -- Treat unauthorized TXT keys as **UNTRUSTED** -- Enforce immutability of all versioned schema keys +- reject TXT ↔ CID mismatches +- reject unauthorized schema TXT keys +- treat versioned schema bindings as immutable once published -> **Schema TXT is sacred. -> Runtime TXT is operational.** +TXT governance is operational and procedural. It should not be described as a signed governance mechanism. --- -## 6. ENS Custody — NORMATIVE - -Canonical ENS: +## 6. Change Classification -- `commandlayer.eth` -- `{verb}agent.eth` identities - -Custody SHALL transition to a **3-of-5 Safe** before Phase 2: - -- Hardware-backed keys -- Signer identities publicly logged -- Rotation MUST be recorded in `SECURITY_PROVENANCE.md` - -No single key may modify canonical semantics. - ---- - -## 7. Change Classification - -**All** normative proposals **MUST** originate from a public GitHub Issue linked to a PR. -Silent or undocumented changes are **STRICTLY FORBIDDEN.** +All normative proposals SHOULD originate from a public GitHub issue linked to a pull request. | Change Class | Version Rule | Required Log | |--------------|--------------|--------------| -| **Normative** (behavior change) | `1 → 2` | `RESOLUTION.md` | -| **Compat-affecting** | `1.0 → 1.1` | `RESOLUTION.md` | -| **Non-behavioral** | `1.0.0 → 1.0.1` | Commit history | - -Every semantic release MUST publish new CIDs + checksums. +| Normative behavior change | new version | `RESOLUTION.md` | +| Compatibility-affecting change | new minor or major version | `RESOLUTION.md` | +| Non-behavioral documentation update | same version docs | commit history | -Until IPFS CID publication is complete, contributors MUST describe that version accurately as the current canonical HTTPS-hosted line and MUST NOT misstate it as the historical pinned release. +Every release update MUST maintain accurate release metadata. When schema artifacts change, the release update MUST also refresh checksums. --- -## 8. Security Governance +## 7. Security Governance -- Responsible disclosure contact MUST be active -- No silent patches or overwritten history -- Emergency revocation allowed to protect downstream users +- responsible disclosure contact MUST remain active +- no silent overwrites of published schema content +- release corrections MUST be documented -Transparency ALWAYS wins. +Transparency and repeatable process take priority over informal claims. --- -## 9. Enforcement of Compatibility Claims - -Products MAY claim: - -- **Commons-Compatible** -- **Agent-Cards-Compatible** - -ONLY if: +## 8. Compatibility Claims -- `$id` + CID validation passes -- Ajv strict mode enforced -- Traceable receipt conformance -- Adherence to this Governance +Products MAY claim Commons compatibility only if they: -False claims REQUIRE public enforcement action. +- validate against the correct versioned schemas +- enforce the documented contract for that version +- describe release status accurately +- do not represent historical v1.0.0 material as the active v1.1.0 line -_Last updated: v1.0.0 retained as the historical pinned release; v1.1.0 documented as the current canonical HTTPS-hosted line_ -Steward declaration (plain-text repository statement, not a cryptographic signature): **`commandlayer.eth`** -*Founding Steward — CommandLayer Semantic Standards* +_Last updated for v1.1.0 documentation normalization._ diff --git a/ONBOARDING.md b/ONBOARDING.md index 43ab6af..dccd50f 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -1,122 +1,99 @@ # Onboarding — Protocol Commons -Welcome to **Protocol-Commons** — the canonical verb + schema layer for autonomous agents. +Welcome to Protocol-Commons, the semantic layer for CommandLayer agents. -This repo defines the **semantic contract** for the active **v1.1.0** schema family and preserves **v1.0.0** as historical pinned context: - -- What actions exist (**canonical verbs**) -- How requests and receipts are structured (**typed schemas**) -- How versioned schema families are governed, published, and verified - -Stable semantics here protect the entire agent ecosystem. Legacy v1.0.0 materials still document the older x402/trace-oriented layout, but those assumptions do **not** automatically apply to v1.1.0. +This repository defines the **current v1.1.0 release** and preserves **v1.0.0** only as historical legacy material. --- -## 1. Who This Repo Is For +## 1. What This Repo Does -You’re in the right place if you are: +Protocol-Commons defines: -- Protocol / infra engineer defining canonical verbs -- Agent runtime / router implementer mapping verbs → handlers -- Validator enforcing strict JSON Schema behavior -- Contributor extending neutral A2A semantics +- canonical verbs +- JSON Schemas for requests and receipts +- versioned schema publication rules +- release metadata and checksum records -> Quick start: implement a Commons verb (e.g., `summarize`) and validate strict request/receipt compatibility. -> It gets you typing — not just reading. - -For identity metadata + ENS discovery → see **agent-cards**. +It does **not** define payment, routing, identity ownership, or runtime execution policy. --- -## 2. Mental Model - -Protocol-Commons is the **bottom** layer: - -``` -[ Execution ] runtimes and transport envelopes -[ Identity ] Agent-Cards (discovery + ownership) -[ Semantics ] Protocol-Commons (verbs + schemas) -``` - -It answers: +## 2. Version Orientation -“What is this agent trying to do — and what must this message look like?” +Keep these distinctions clear: -## 3. Repo Layout +- **v1.1.0** is the current release and active schema line +- **v1.0.0** is historical legacy material only +- HTTPS hosting and IPFS pinning are separate publication layers +- repository integrity is based on checksums plus documented release metadata -| Folder/File | Meaning | -| --------------------------------- | -------------------------------------------------------------------- | -| `schemas/v1.1.0/commons/` | Current canonical in-repo Commons schemas | -| `examples/v1.1.0/commons/` | Active v1.1.0 example payloads and vectors | -| `schemas/v1.0.0/commons/` | Historical pinned Commons schemas (immutable canonical release) | -| `schemas/v1.0.0/_shared/` | Historical shared primitives used by v1.0.0 | -| `examples/v1.0.0/commons/` | Historical v1.0.0 test vectors | -| `manifest.json` + `checksums.txt` | Integrity, provenance, and active-versus-historical release metadata | -| `SPEC.md` | Canonical rules | -| `SCHEMAS.md` | Schema family and layout rules | -| `GOVERNANCE.md` | Change authority + approvals | -| `SECURITY*.md` | Disclosure + provenance | -| `RESOLUTION.md` | Change log (signed provenance) | - -Authoritative docs: +--- -- `SPEC.md` — normative rules -- `SCHEMAS.md` — versioning, layout, and schema-family guidance -- `GOVERNANCE.md` — approval of normative changes -- `SECURITY*.md` — provenance + integrity guarantees -- `RESOLUTION.md` — canonical lifecycle log +## 3. Repository Layout + +| Path | Meaning | +|------|---------| +| `schemas/v1.1.0/commons/` | Current v1.1.0 Commons schemas | +| `examples/v1.1.0/commons/` | Current repository examples for v1.1.0 | +| `schemas/v1.0.0/commons/` | Historical legacy schemas | +| `schemas/v1.0.0/_shared/` | Historical shared primitives for v1.0.0 | +| `examples/v1.0.0/commons/` | Historical legacy examples | +| `manifest.json` | Release metadata and publication record | +| `checksums.txt` | Schema checksum record | +| `SPEC.md` | Normative schema contract | +| `SCHEMAS.md` | Layout and versioning policy | +| `GOVERNANCE.md` | Repository process and authority model | +| `SECURITY_PROVENANCE.md` | Integrity and publication tracking | +| `RESOLUTION.md` | Release log | -If a change is not reflected here → **not canonical.** +--- -**ENS TXT Summary** -Protocol-Commons governs TXT keys that resolve schema semantics. -Canonical definitions → `SPEC.md`. +## 4. First Commands -## 4. Working Norms +Run these from the repository root: -``` +```bash npm install npm run validate ``` -Use a subcommand only when you need a narrower loop after the aggregate pass: +Useful narrower loops: -``` +```bash npm run validate:schemas +npm run validate:examples +npm run checksums:verify ``` -`npm run validate` already includes `npm run validate:examples`. Run `validate:examples` separately only when you intentionally want an examples-only loop. +--- -5. Update `RESOLUTION.md`, provenance -6. Submit PR with version class (MAJOR/MINOR/PATCH) +## 5. Practical Working Norms -If you are preparing a contribution, follow `CONTRIBUTING.md`. +1. Treat v1.1.0 as the default target for new documentation and validation work. +2. Treat v1.0.0 as reference material only. +3. Do not edit published schema semantics in place. +4. Update release-facing docs when version status language changes. +5. Keep `manifest.json`, `checksums.txt`, and `RESOLUTION.md` aligned with release history. -## 5. What “Good” Looks Like +--- -- Clear, single-purpose PR -- Schema + example alignment -- No edits to existing version folders -- Fully traceable governance + checksums -- Deterministic canonical `$id` values, with live HTTP resolution added when publication is completed +## 6. Examples Guidance -## 5A. Fixture Rules +When editing `examples/`: -When you touch `examples/`, keep the validation surface credible: +- keep valid examples realistic +- keep invalid examples focused on a clear failure mode +- keep fixtures aligned to the version they target +- remember that examples are repository assets, not npm package contents -- valid examples should be realistic, not cartoon placeholders -- invalid examples should usually test one clear failure, not five at once -- filenames should explain the scenario (`missing-input`, `invalid-version`, `extra-property`, etc.) -- request examples must stay verb-aligned; do not copy an invalid fixture from one verb directory into another -- valid receipts should use realistic `sha256:` digests and CID-shaped values -- unless the repo ships the exact corresponding payload artifacts, treat example digests/signatures/CIDs as format-realistic illustrative evidence rather than independently verifiable production proofs +TypeScript examples are illustrative and are not currently validated by CI. -Default assumption: **new version** for any semantic change. +--- -## 6. Support +## 7. Support -Governance contact: dev@commandlayer.org -PGP fingerprint: 5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A +- Governance contact: `dev@commandlayer.org` +- Steward record: `commandlayer.eth` -Protocol-Commons is a **neutral shared layer.** -Precision here preserves interoperability everywhere else. +Precision in these docs protects downstream interoperability. diff --git a/README.md b/README.md index d020073..b4da8d1 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # CommandLayer Protocol — Commons **The canonical semantic contract for autonomous agents.** -*Verbs, schemas, and validation — or nothing interoperates.* +*Verbs, schemas, and validation for the current v1.1.0 release.* [![Schemas](https://img.shields.io/badge/Schemas-v1.1.0%20current-blue)](https://github.com/commandlayer/protocol-commons) [![NPM Version](https://img.shields.io/npm/v/@commandlayer/commons)](https://www.npmjs.com/package/@commandlayer/commons) @@ -10,111 +10,59 @@ --- -> **Integrity Notice — Protocol-Commons v1.1.0** -> -> `schemas/v1.1.0/commons` is the current canonical schema family in this repository, and its HTTPS schema URLs are live under `https://commandlayer.org/schemas/v1.1.0/...`. -> Its metadata still says `schemas_cid: PENDING`, so v1.1.0 is **not yet the IPFS-pinned canonical release**. -> -> `v1.0.0` remains the last **externally pinned canonical release**: -> `schemas/v1.0.0/` — CID: `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` -> -> Verify in-repo integrity locally: -> ```bash -> npm run checksums:verify -> ``` -> -> Any mismatch indicates modified artifacts. New versions MUST use a new version directory and, once published, a new CID. +Protocol-Commons defines the shared semantic layer for CommandLayer agents: + +- canonical verbs +- strict JSON Schema validation +- versioned schema publication +- checksum-based integrity records +- documented release metadata + +The current release is **v1.1.0**. The active schema line is **`schemas/v1.1.0/commons`**. Version **v1.0.0** is preserved only as a historical legacy line. + +## Release Status + +- **Current release:** `v1.1.0` +- **Active schema line:** `schemas/v1.1.0/commons` +- **Pinned canonical release after CID insertion:** `v1.1.0` +- **Current IPFS publication state for v1.1.0:** `schemas_cid: PENDING` in `manifest.json`, meaning IPFS publication is tracked separately from the HTTPS-hosted schema line +- **Historical release:** `v1.0.0` with CID `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` + +HTTPS hosting and IPFS pinning are separate distribution layers: + +- HTTPS hosting provides the live canonical schema URLs used by the `$id` fields +- IPFS pinning records a separate content-addressed publication state for the same version when a CID is published + +You do not need IPFS context to understand or validate the schemas. For in-repo integrity checks, use: + +```bash +npm run checksums:verify +``` ## Table of Contents - [Why Now](#why-now) -- [Real verbs. Real receipts.](#real-verbs-real-receipts) - [Quickstart](#quickstart) +- [Package Notes](#package-notes) - [Commons v1.1.0](#commons-v110) -- [What Commons enables](#what-commons-enables) -- [Why this exists](#why-this-exists) - [Canonical Verbs](#canonical-verbs) -- [Overview](#overview) -- [Key Principles](#key-principles) -- [This is not…](#this-is-not) -- [CommandLayer Protocol Stack](#commandlayer-protocol-stack) -- [Status](#status) - [Repository Structure](#repository-structure) -- [Manifest](#manifest) -- [Immutability & Checksums](#immutability--checksums) +- [Manifest and Integrity Records](#manifest-and-integrity-records) - [Validation](#validation) -- [Fixture discipline](#fixture-discipline) +- [Examples](#examples) - [License](#license) -- [Next Layers](#next-layers) -- [References](#references) - ---- ## Why Now -Autonomous agents are finally leaving the lab — but without shared meaning, they fragment into isolated API silos. - -CommandLayer separates the stack into clear responsibilities: - -- **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 - -Protocol-Commons is the foundation for portable machine intent: a stable set of verbs plus strict JSON Schemas for requests and receipts. - ---- - -Without a shared verb layer, ecosystems degrade into: - -- 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 canonical action language: - -- Verbs + JSON Schemas + strict validation -- Stable request envelopes -- Signed receipts with hash-based verification evidence - -If agents cannot agree on what actions mean, interoperability breaks. - ---- - -## Real verbs. Real receipts. - -```jsonc -// summarize.request -{ - "verb": "summarize", - "version": "1.1.0", - "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" -} - -// summarize.receipt -{ - "verb": "summarize", - "version": "1.1.0", - "status": "ok", - "timestamp": "2026-03-18T12:00:00Z", - "request_hash": "sha256:4b87d90208e62430a5d8f577938fd26d02d646f092d137cee66216c0daac8243", - "result_hash": "sha256:8b5d2d4dfb4a8bb7d4d1ed436e78c5f4bcf6ca9714ec93a8db8e5ec6ed8b1b8d", - "result_cid": "bafybeif6h8j0l2n4p6r8t0v2x4z6b8d0f2h4j6l8n0p2r4t6v8x0z2bd", - "summary": "Commons v1.1.0 makes requests smaller and receipts easier to verify while preserving stable verb semantics.", - "signature": "MEUCID4fG6hJ8kL0mN2pQ4rS6tU8vW0xY2zA4bC6dE8fG0hAiEAzB1dD3fF5hH7jJ9lL1nP3rT5vX7zA9cC1eE3gH5iJ7" -} -``` - -Every v1.1.0 Commons receipt shares the same required core evidence fields: +Autonomous agents need shared meaning to interoperate across runtimes, vendors, and transport layers. -- `status` -- `timestamp` -- `request_hash` -- `signature` +Protocol-Commons provides that shared meaning through: -`summary` is required on success receipts. `error` is required on error receipts. `result_hash`, `result_cid`, and `agent` are optional evidence fields that may appear when the implementation can surface them honestly. +- a stable verb set +- versioned JSON Schemas +- strict request and receipt validation +- release metadata and checksum verification ---- +Execution, identity, payment, routing, and storage can evolve independently around those semantics. ## Quickstart @@ -124,36 +72,16 @@ Install Commons and AJV: npm install @commandlayer/commons ajv ajv-formats ajv-errors ``` -**Validate the full repo surface** +Validate the full repository surface locally: ```bash npm install npm run validate ``` -`npm run validate` is the primary command: it compiles every schema and then checks that all shipped examples pass or fail exactly as intended. - -**Validate a specific example against the shipped 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 -``` +`npm run validate` is the primary repository check. It compiles the schemas and validates the shipped example fixtures against their intended outcomes. -**Programmatic usage (Node.js/ESM)** +### Programmatic usage (Node.js / ESM) ```js import Ajv2020 from 'ajv/dist/2020.js'; @@ -168,7 +96,7 @@ const validate = ajv.compile(summarizeRequestSchema); const input = { verb: 'summarize', version: '1.1.0', - input: 'CommandLayer Commons v1.1.0 simplifies every request into a flat shape.', + input: 'Protocol-Commons v1.1.0 uses a flat request shape.', mode: 'brief' }; @@ -176,36 +104,34 @@ console.log(validate(input)); console.log(validate.errors ?? []); ``` ---- +## Package Notes -## Commons v1.1.0 +- Examples are available in the GitHub repository and are **not included** in the npm package. +- Do not assume `examples/` exists locally after `npm install @commandlayer/commons`. +- TypeScript examples in this repository are illustrative and are **not currently validated by CI**. -Commons v1.1.0 is the current canonical schema family in this repository. +If you want to validate repository fixtures directly, clone the repository and use the local paths from the repo root. -It is the primary documentation and validation target for Commons, and its canonical HTTPS `$id` URLs are live. The repository still records IPFS CID publication as pending, so `v1.1.0` should be treated as the current HTTPS-published schema family rather than the last IPFS-pinned release. `v1.0.0` is retained as the historical pinned release line. +## Commons v1.1.0 -- 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 +Commons v1.1.0 is the **current release** and the **active schema line** for this repository. -Example schema paths: +It is the primary documentation and validation target for Commons. Its schema files live under `schemas/v1.1.0/commons/`, and its canonical HTTPS `$id` values resolve under `https://commandlayer.org/schemas/v1.1.0/...`. -- `schemas/v1.1.0/commons/analyze/analyze.request.schema.json` -- `schemas/v1.1.0/commons/analyze/analyze.receipt.schema.json` +Version `v1.0.0` remains available only for historical reference, compatibility review, and legacy auditing. It is not the active schema line. -The request contract is intentionally small: +The v1.1.0 contract is intentionally small: ```json { "verb": "", "version": "1.1.0", - "input": "", - "mode": "" + "input": "", + "mode": "" } ``` -The receipt contract is proof-oriented rather than transport-oriented: +Receipts use a flat structure with checksum-oriented evidence fields and optional content-address references: ```json { @@ -217,248 +143,103 @@ The receipt contract is proof-oriented rather than transport-oriented: "result_hash": "sha256:<64 lowercase hex chars>", "result_cid": "", "summary": "", - "signature": "", + "signature": "", "error": "" } ``` -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. - -## Why this exists - -Fragmented agents create isolated ecosystems and brittle automation. - -Protocol-Commons delivers: - -- **Shared semantics** -- **Typed request and receipt envelopes** -- **Signed receipts bound to request hashes** -- **Portable behavior across runtimes** -- **A stable foundation other layers can build around** - ---- - -## What Commons enables - -- **Deterministic action contracts** -- **Runtime-level validation** -- **Receipt verification through hashes and signatures** -- **Cross-vendor interoperability** -- **Versioned, immutable semantics** - -Protocol-Commons is the semantic foundation of the CommandLayer stack. - ---- +Protocol-Commons documents schema structure and validation rules. It does not define transport guarantees, settlement logic, or signed release provenance. ## Canonical Verbs -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 | - -Each verb defines: +The Commons verb set for v1.1.0 is: -- a canonical request format -- a canonical receipt format +- `analyze` +- `classify` +- `clean` +- `convert` +- `describe` +- `explain` +- `fetch` +- `format` +- `parse` +- `summarize` -```text -+-----------------------------+ -| Execution Runtime | (action is performed) -+-------------▲---------------+ - | - v -+-----------------------------+ -| Identity / Routing | (discovery + addressing) -+-------------▲---------------+ - | - v -+-----------------------------+ -| Protocol-Commons | (verbs + schemas) -| "What actions mean" | -+-----------------------------+ -``` - -Each verb provides: +Each verb has exactly two schema files in v1.1.0: - `.request.schema.json` - `.receipt.schema.json` ---- - -## Overview - -Protocol-Commons is the schema package for canonical agent verbs. - -For v1.1.0, the Commons layer is intentionally flat: - -- requests contain the action intent and caller input -- receipts contain execution status plus signer-bound evidence -- versioned directories preserve immutability over time - ---- - -## Key Principles - -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. - ---- - -## This is not… - -Protocol-Commons is **not**: - -- 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 - -Those concerns can be layered on top, but they are not defined by the v1.1.0 Commons schemas. - ---- - -## CommandLayer Protocol Stack - -```text -Execution / settlement layers - ↑ -Identity / routing layers - ↑ -Protocol-Commons (semantic verbs + schemas) -``` - -Commons gives upper layers a stable meaning layer to build around. - ---- - -## Status +Example paths: -**v1.1.0 — current canonical HTTPS-hosted schema line** - -- `v1.1.0` is the current flat Commons layout in this repo -- `v1.0.0` remains the historical pinned release line -- Do not describe `v1.1.0` as IPFS-pinned or historically locked until CID publication is complete - ---- +- `schemas/v1.1.0/commons/analyze/analyze.request.schema.json` +- `schemas/v1.1.0/commons/analyze/analyze.receipt.schema.json` ## Repository Structure ```text . -├── README.md -├── SCHEMAS.md -├── SPEC.md -├── checksums.txt ├── examples/ │ ├── v1.0.0/ -│ │ └── commons//{valid,invalid}/*.json │ └── v1.1.0/ -│ └── commons//json/{valid,invalid}/*.json -├── manifest.json -├── package.json ├── schemas/ │ ├── v1.0.0/ -│ │ ├── _shared/ -│ │ └── commons//{requests,receipts}/*.schema.json │ └── v1.1.0/ -│ └── commons// -│ ├── .request.schema.json -│ └── .receipt.schema.json -└── scripts/ - ├── validate-all.mjs - └── validate-examples.mjs +├── CHANGELOG.md +├── COMPLIANCE.md +├── GOVERNANCE.md +├── manifest.json +├── ONBOARDING.md +├── RESOLUTION.md +├── SCHEMAS.md +├── SECURITY_PROVENANCE.md +└── SPEC.md ``` ---- - -## Manifest - -`manifest.json` records release metadata for the package, including: +## Manifest and Integrity Records -- package version -- schema and example roots -- the current schema pin target -- per-verb request and receipt schema paths -- HTTPS hosting status (live for `https://commandlayer.org/schemas/v1.1.0/...`) -- CID publication status (`PENDING` in `manifest.json` until published) +`manifest.json` records the release metadata for the current package version, including: -Treat `schemas_cid: PENDING` as an explicit signal that IPFS provenance for v1.1.0 is still awaiting publication, even though the v1.1.0 HTTPS schema identifiers are already live and this is the repo's current schema target. +- active release version +- schema roots +- example roots +- IPFS publication state +- historical release metadata ---- - -## Immutability & Checksums +`checksums.txt` records SHA-256 checksums for shipped schema artifacts. -Use the checksum and validation scripts shipped in the repo: - -```bash -npm run checksums:verify -npm run validate -``` +Together they provide: -Published version directories must not be edited in place. +- checksum-based integrity +- a versioned publication record +- documented release history +- IPFS publication tracked separately from HTTPS hosting ---- +This repository does **not** currently publish signed release artifacts. ## Validation -Use `npm run validate` as the canonical repo-wide validation command. For targeted checks, the repo also exposes: +Use the following checks from the repository root: ```bash npm run validate npm run validate:schemas npm run validate:examples +npm run checksums:verify ``` -- `npm run validate` — the main contributor command. Compiles every schema, then validates every shipped example. -- `npm run validate:schemas` — schema compilation only. Useful when changing schema files or Ajv configuration. -- `npm run validate:examples` — fixture pass/fail verification only. Useful when editing examples or improving failure coverage. - -For `v1.1.0`, fixture discipline matters as much as schema compilation: valid examples must look operationally plausible, and invalid examples should usually fail for one clear reason that matches the filename. - ---- +## Examples -## Fixture discipline +Repository fixtures under `examples/` are intended to be practical references for implementers. -For `examples/v1.1.0/commons/`, contributors should treat fixtures as protocol evidence, not filler: +Guidelines: -- valid examples should look realistic enough that an implementer could model against them -- invalid examples should usually exercise one clear failure mode -- filenames should describe the exact failure being tested -- request fixtures must stay aligned with the verb directory they live in; deliberate wrong-verb cases must be explicitly named -- valid receipts should use realistic digest and CID-shaped values instead of toy placeholders -- unless the repo ships the exact corresponding payload artifacts, treat example digests/signatures/CIDs as format-realistic illustrative evidence rather than independently verifiable production proofs +- valid examples should model plausible protocol payloads +- invalid examples should usually demonstrate one clear failure mode +- fixtures should stay version-aligned with the schema family they target +Again: examples live in the GitHub repository, not the npm package. ## License MIT. - ---- - -## Next Layers - -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 - -- `SPEC.md` -- `SCHEMAS.md` -- `manifest.json` -- `schemas/v1.1.0/commons/` diff --git a/RESOLUTION.md b/RESOLUTION.md index 9f82b20..d6ab404 100644 --- a/RESOLUTION.md +++ b/RESOLUTION.md @@ -1,52 +1,34 @@ # Resolution Log — Protocol Commons -*Lifecycle log for canonical verbs & schemas.* +This file is the documented release log for Protocol-Commons schema history. -This file tracks **every** lifecycle decision for Protocol-Commons: -verb additions, corrections, deprecations, and removals. +It records: -If a change is **not** documented here, it is **not** considered valid. +- version +- release date +- release status +- scope of change +- approving steward --- -## Entry Requirements +## Release Log -- **Date** — final decision date -- **Verb(s)** — affected canonical verbs -- **Action** — Added · Deprecated · Replaced · Removed · Revised -- **Reason** — interoperability, security, redundancy, etc. -- **Resolution** — final state (including replacements, if any) -- **Approver(s)** — Governance sign-off +| Date | Version | Status | Summary | Approver | +|------|---------|--------|---------|----------| +| 2025-12-06 | 1.0.0 | Historical legacy release | Initial Protocol-Commons release with versioned schemas, shared primitives, and the original nested Commons layout. Historical CID: `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m`. | Founding Steward | +| 2026-03-18 | 1.1.0 | Current release and active schema line | Published the flat Commons schema family under `schemas/v1.1.0/commons`, simplified request and receipt contracts, and documented v1.1.0 as the active schema line. IPFS publication is tracked separately and remains `PENDING` in `manifest.json` until a CID is recorded. | Founding Steward | --- -## Decision Log +## Release Notes Policy -| Date | Verb(s) | Action | Class | Reason | Resolution | Approver(s) | -|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|---------|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|-------------------| -| 2025-12-06 | analyze, classify, clean, convert, describe, explain, fetch, format, parse, summarize | Added | Commons | Initial canonical verb set | v1.0.0 published — immutable directory `schemas/v1.0.0/` — CID: `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` | Founding Steward | -| 2026-03-18 | analyze, classify, clean, convert, describe, explain, fetch, format, parse, summarize | Revised | Commons | Simplified attestation-oriented receipt contract, flat layout, removal of universal x402/trace assumptions from the new schema family | v1.1.0 canonical HTTPS schema hosting live; IPFS CID publication pending | Founding Steward | +A release entry SHOULD state: -> Any future semantic change requires a **new version directory** and **new CID** prior to approval and publication in this Resolution Log. +- version +- release date +- what changed +- whether the release is current or historical +- CID information when published ---- - -## Policy - -1. No silent changes — **every** protocol semantic update goes here -2. Minimum **90-day** deprecation before removal -3. Changes requiring new schema version: - - `$id` changes - - Field contract changes - - Meaning changes -4. Governance Council **must** approve every entry -5. Stability > speed - ---- - -Maintainers must review before any merge: -- `SPEC.md` -- `GOVERNANCE.md` -- `SECURITY_PROVENANCE.md` - -**Status:** v1.1.0 canonical HTTPS schema hosting is live, IPFS CID publication remains pending; v1.0.0 remains the historical pinned release. +Repository history is documented in plain repository records. This log does not represent signed governance history. diff --git a/SCHEMAS.md b/SCHEMAS.md index 9c49bfb..834f94b 100644 --- a/SCHEMAS.md +++ b/SCHEMAS.md @@ -1,39 +1,39 @@ # Schemas Policy — Protocol Commons -This document specifies stability rules, versioning constraints, and change governance for all Protocol Commons schemas. +This document specifies stability rules, versioning constraints, and layout rules for Protocol-Commons schemas. -> This document is **NORMATIVE and ENFORCEABLE**. +> This document is **NORMATIVE**. --- ## 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 -- immutable versioning rules -- flat v1.1.0 request and receipt contracts +This policy covers: -Once published, a version directory is immutable. +- versioned schema layout +- `$id` requirements +- request and receipt structure +- immutability rules +- validation expectations --- ## 2. Version Status -This repository currently ships: +This repository currently uses: -- **v1.1.0** as the active in-repo schema family -- **v1.0.0** as the historical and last fully pinned canonical release +- **v1.1.0** as the current release and active schema line +- **v1.0.0** as the legacy historical schema line -Because `manifest.json` still reports the v1.1.0 schema CID as pending, documentation MUST describe v1.1.0 accurately as the current canonical HTTPS-hosted schema line and MUST distinguish it from the historical pinned release until a real CID is published. +The manifest tracks IPFS publication for v1.1.0 separately from the HTTPS-hosted schema URLs. That publication record does not alter the schema layout defined here. --- ## 3. Directory Layout -### Current in-repo layout: v1.1.0 +### Current layout: v1.1.0 ```text schemas/v1.1.0/ @@ -43,7 +43,7 @@ schemas/v1.1.0/ └── .receipt.schema.json ``` -### Historical pinned layout: v1.0.0 +### Legacy layout: v1.0.0 ```text schemas/v1.0.0/ @@ -63,7 +63,7 @@ schemas/v1.0.0/ - 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 +- v1.1.0 MUST use the flat per-verb file layout shown above - Nested `requests/` and `receipts/` directories are legacy-only and MUST NOT be described as the v1.1.0 layout --- @@ -98,27 +98,15 @@ Each verb MUST define exactly: https://commandlayer.org/schemas/v1.1.0/commons//.request.schema.json ``` -Example: - -```text -https://commandlayer.org/schemas/v1.1.0/commons/summarize/summarize.request.schema.json -``` - ### v1.1.0 receipt schemas ```text https://commandlayer.org/schemas/v1.1.0/commons//.receipt.schema.json ``` -Example: - -```text -https://commandlayer.org/schemas/v1.1.0/commons/summarize/summarize.receipt.schema.json -``` - ### Legacy v1.0.0 note -Legacy v1.0.0 schemas retain their older nested `$id` patterns and `_shared` references. Those patterns are legacy-only and are not the v1.1.0 contract. +Legacy v1.0.0 schemas retain their older nested `$id` patterns and `_shared` references. Those patterns are legacy-only. All `$id` values MUST be fully qualified HTTPS URLs. @@ -166,13 +154,13 @@ Additional shared fields are schema-supported but optional unless conditionally 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. +The receipt contract is limited to the fields defined in the schemas. It MUST NOT be described as providing live execution verification, transport guarantees, or signed release provenance. --- ## 8. Legacy v1.0.0 Scope -v1.0.0 remains in-repo for compatibility, historical verification, and canonical pin auditing. +v1.0.0 remains in-repo only for compatibility review, historical reference, and legacy auditing. Its schemas use: @@ -180,7 +168,7 @@ Its schemas use: - nested `requests/` and `receipts/` folders - older envelope conventions including `x402` and `trace` -Documentation and tooling MUST distinguish that legacy structure from v1.1.0 and MUST NOT present those legacy fields as universally normative. +Documentation and tooling MUST distinguish that legacy structure from v1.1.0. --- @@ -193,23 +181,13 @@ Once published under a version directory such as `schemas/v1.1.0/`, the followin - updating `$id` values for that version - changing the directory layout for that version -Any change requires a new version directory. +Any semantic change requires a new version directory. --- ## 10. Validation Requirements -CI and local validation SHOULD enforce strict schema compilation behavior equivalent to: - -```text -strict: true -strictSchema: true -allErrors: true -strictRequired: false -allowUnionTypes: false -``` - -Repository validation commands: +Repository validation commands are: ```bash npm run validate:schemas @@ -221,60 +199,40 @@ All shipped valid and invalid examples MUST match the version-specific schema la --- -## 11. Examples - -Examples are maintained per version. +## 11. Examples Layout ### v1.1.0 examples ```text examples/v1.1.0/commons//json/ - valid/*.json - invalid/*.json ``` ### v1.0.0 examples ```text examples/v1.0.0/commons// - valid/*.json - invalid/*.json ``` --- -## 12. Provenance & Integrity - -Integrity is tracked by: - -- `checksums.txt` -- `manifest.json` +## 12. Publication Record Summary -Current v1.1.0 canonical HTTPS schema root: +Current HTTPS schema root: ```text https://commandlayer.org/schemas/v1.1.0/ ``` -Current v1.1.0 schema CID status: +Manifest-tracked IPFS publication state for v1.1.0: ```text PENDING ``` -Last pinned canonical release content identifier: +Historical legacy CID record: ```text v1.0.0 → bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m ``` -Resolvers and auditors MUST reject mismatched artifacts and MUST distinguish between the current canonical HTTPS-hosted schema family and the historical pinned release. - ---- - -## 13. Contact - -- dev@commandlayer.org -- PGP 5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A - -**Status:** v1.1.0 current canonical HTTPS-hosted schema family with pending CID publication metadata; v1.0.0 retained as the historical pinned release. +**Status:** v1.1.0 is the current release and active schema line. v1.0.0 is legacy only. diff --git a/SECURITY_PROVENANCE.md b/SECURITY_PROVENANCE.md index 915fc1a..3154099 100644 --- a/SECURITY_PROVENANCE.md +++ b/SECURITY_PROVENANCE.md @@ -1,79 +1,89 @@ # Security Provenance — Protocol Commons -**Scope:** Protocol-Commons -**Status:** v1.1.0 — Current Canonical In-Repo Line; v1.0.0 remains the historical pinned release -**This document is NORMATIVE and ENFORCEABLE.** -Defines cryptographic provenance, integrity guarantees, and audit mechanisms -for published and current in-repo Protocol-Commons schemas. +**Scope:** Protocol-Commons +**Status:** v1.1.0 current release and active schema line; v1.0.0 historical legacy release +**This document is NORMATIVE.** ---- +This document describes repository integrity records, release metadata, and publication tracking. ## Contact -If something seems incorrect, report immediately: -Email: dev@commandlayer.org -PGP fingerprint: 5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A +If something appears incorrect, report it promptly. + +- Email: `dev@commandlayer.org` +- PGP fingerprint for contact verification: `5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A` Private disclosure is preferred for security-sensitive findings. ---- +## Integrity Model + +Integrity in this repository is provided through: + +- `checksums.txt` for checksum verification of shipped schema artifacts +- `manifest.json` for documented release metadata and publication state +- versioned schema paths such as `schemas/v1.1.0/` and `schemas/v1.0.0/` + +These records provide checksum-based integrity, a versioned publication record, and documented release history. + +**This repository does not currently publish signed release artifacts.** -## Provenance & Version Integrity -Releases are **reproducible and content-addressed**. +## Release Tracking -Current repository schema family: **v1.1.0** -Current canonical pinned release: **v1.0.0** +Release tracking in this repository includes: -Integrity sources: -- **v1.0.0 CID:** `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` -- **v1.1.0 HTTPS canonical root:** `https://commandlayer.org/schemas/v1.1.0/` (live) -- **v1.1.0 CID:** `PENDING` (IPFS pinning not yet published) -- `checksums.txt` — file-level hashes -- CI strict validation (Ajv) -- `RESOLUTION.md` — immutable lifecycle history -- `manifest.json` — current package metadata and pin target state +- version +- schema roots +- package metadata +- CID values when published +- documented history in `CHANGELOG.md` and `RESOLUTION.md` -Until a v1.1.0 CID is published and recorded, resolvers and auditors MUST treat v1.1.0 as the current canonical HTTPS-hosted schema family rather than the historical pinned release. +Current release state: -Any semantic update requires: -- New `schemas/vX.Y.Z/` directory -- New CID and updated checksums for any canonical release -- Governance approval + provenance record +- **Current release:** `v1.1.0` +- **Active schema line:** `schemas/v1.1.0/commons` +- **Manifest-tracked CID for v1.1.0:** `PENDING` +- **Historical legacy release:** `v1.0.0` +- **Historical v1.0.0 CID:** `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` -**No silent edits. No exceptions.** +IPFS publication is tracked separately from HTTPS hosting. The v1.1.0 HTTPS schema URLs can be live while the manifest still records `schemas_cid: PENDING` for the IPFS publication step. -Auditors MUST verify: -- HTTPS and IPFS mirrors match exactly for pinned canonical releases -- Checksums remain unchanged -- Version directories are immutable -- The current canonical HTTPS-hosted line is not misdescribed as the historical pinned release before CID publication is complete +## Publication Layers ---- +Protocol-Commons uses two separate distribution layers: + +1. **HTTPS hosting** for canonical schema URLs and `$id` resolution +2. **IPFS pinning** for content-addressed publication records when a CID is published + +These layers should not be conflated. HTTPS availability does not by itself mean that IPFS publication has been recorded, and IPFS publication metadata is not required to understand the schema contracts. + +## Auditor Expectations + +Auditors and integrators SHOULD verify: + +- checksums in `checksums.txt` against the shipped schema files +- schema paths and release metadata in `manifest.json` +- version-specific history in `CHANGELOG.md` and `RESOLUTION.md` +- immutability of published version directories + +For a release with a published CID, auditors SHOULD also verify that the recorded IPFS publication matches the documented version metadata. ## ENS TXT Summary -Protocol-Commons governs TXT keys that resolve **schema semantics**. -Canonical rules under: -- `SPEC.md` +Protocol-Commons governs TXT keys that resolve schema semantics. -Resolvers MUST reject any: -- TXT ↔ CID mismatch -- Unauthorized or missing TXT keys -- Out-of-sync version binding +Resolvers SHOULD reject: -For v1.1.0 specifically, TXT/CID binding MUST NOT be represented as a published pinned release until CID publication is complete. +- TXT ↔ CID mismatches +- unauthorized or missing schema TXT keys +- out-of-sync version bindings ---- +TXT records are part of publication metadata. They are not, by themselves, signed release artifacts. ## Security Posture -- No PII -- No execution or proprietary logic -- Minimal surface area -- Predictable and stable - -Breakage here causes **ecosystem-wide** failures. -Recovery requires **transparent governance** — never mutation in place. ---- +- No PII in schema artifacts +- No embedded execution logic +- Minimal semantic surface area +- Immutable versioned publication records -**Status:** v1.1.0 is the current canonical HTTPS-hosted schema family with pending IPFS CID publication; v1.0.0 remains the historical fully verifiable pinned release. +If a mistake is discovered, the remedy is a documented follow-up release or metadata update, not a silent rewrite of published schema content. diff --git a/SPEC.md b/SPEC.md index d78e32e..f1bd483 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,7 +1,7 @@ # Specification — Protocol Commons CommandLayer Core Standards · Semantic Layer -> This document is **NORMATIVE and ENFORCEABLE**. +> This document is **NORMATIVE**. ## RFC 2119 Keywords MUST / MUST NOT / SHOULD / SHOULD NOT / MAY retain their RFC-defined meanings. @@ -10,62 +10,35 @@ 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 semantic contract for autonomous agents: -- **Verbs** — what actions exist -- **Request schemas** — typed invocation contracts -- **Receipt schemas** — typed execution evidence contracts -- **Versioning + immutability** — trust guarantees for published artifacts +- verbs +- request schemas +- receipt schemas +- versioning and immutability rules -Execution, payment, identity, and routing are the domain of other layers. +Execution, payment, identity, routing, and storage belong to other layers. --- -## 2. Release Status and Scope +## 2. Release Scope -This repository contains two materially different Commons schema families: +This repository contains two Commons schema families: -- **v1.1.0** — current canonical schema family, active documentation target, and live HTTPS-hosted identifier set -- **v1.0.0** — legacy schema family and historical pinned release +- **v1.1.0** — current release and active schema line +- **v1.0.0** — legacy historical schema line -Repository metadata still records v1.1.0 IPFS CID publication as pending. Implementers MUST therefore distinguish between: - -1. **Schema semantics and canonical HTTPS identifiers** — what the v1.1.0 files require and where their `$id` values resolve -2. **Release provenance status** — whether a version has completed IPFS CID publication and canonical pinning - -This specification documents the v1.1.0 contract as the current canonical schema family while preserving v1.0.0 as the historical pinned release until v1.1.0 IPFS pinning is complete. +The v1.1.0 schema family is the normative target for current implementations. The repository tracks its IPFS publication state separately in `manifest.json`. That publication state does not change the schema requirements defined in this specification. --- -## 3. Architecture Position - -The Commons is the semantic base layer of the CommandLayer stack: - -```text -┌────────────────────────────┐ -│ Execution / settlement │ -└──────────────▲─────────────┘ - │ -┌──────────────┴─────────────┐ -│ Identity / routing │ -└──────────────▲─────────────┘ - │ -┌──────────────┴─────────────┐ -│ Semantics — Commons │ -└────────────────────────────┘ -``` - -**Commons answers: “What is this agent trying to do?”** - ---- - -## 4. Canonical Verb Set +## 3. Canonical Verb Set The only canonical verbs are: `analyze`, `classify`, `clean`, `convert`, `describe`, `explain`, `fetch`, `format`, `parse`, `summarize` -Each verb MUST map to: +Each verb MUST map to exactly: - `.request.schema.json` - `.receipt.schema.json` @@ -74,11 +47,7 @@ No aliases or synonyms are canonical. --- -## 5. Commons v1.1.0 Schema Contract - -Commons v1.1.0 is the current schema family documented in this repository. - -### 5.1 Directory contract +## 4. v1.1.0 Directory Contract Every v1.1.0 schema file MUST reside under: @@ -93,7 +62,9 @@ with exactly these file names: Moving published files is a breaking change. -### 5.2 Request shape (flat) +--- + +## 5. v1.1.0 Request Contract Every v1.1.0 request MUST be a flat JSON object with: @@ -117,9 +88,11 @@ A conforming request shape is: } ``` -Commons v1.1.0 does not require `x402`, `trace`, `actor`, or nested request wrappers. +v1.1.0 requests do not include nested request wrappers, `x402`, `trace`, or `actor` fields. + +--- -### 5.3 Receipt shape +## 6. v1.1.0 Receipt Contract Every v1.1.0 receipt MUST be a flat JSON object with these shared fields: @@ -131,7 +104,7 @@ Every v1.1.0 receipt MUST be a flat JSON object with these shared fields: | `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 | +| `agent` | No | Non-empty string | | `result_hash` | No | `sha256:` followed by 64 lowercase hex chars | | `result_cid` | No | Non-empty string content identifier | | `summary` | Cond. | REQUIRED when `status = "ok"` | @@ -155,8 +128,6 @@ A conforming success receipt shape is: } ``` -`agent` MAY be added to either success or error receipts when the signer identity is being surfaced at the application layer. - A conforming error receipt shape is: ```json @@ -171,45 +142,28 @@ A conforming error receipt shape is: } ``` -### 5.4 Trust model - -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 - -Commons v1.1.0 does **not** define settlement proofs, transport-level guarantees, execution traces, or result-object substructures. +The receipt schemas bind receipt content to versioned payload fields. They do not guarantee execution success, transport delivery, or any verification beyond schema-conformant data structures. --- -## 6. v1.0.0 Legacy Status - -`v1.0.0` remains in the repository as a legacy schema family for compatibility, historical verification, and canonical pin verification. - -Its structure differs materially from v1.1.0: - -- nested request/receipt directories -- `_shared` referenced schemas -- transport-oriented `x402` and `trace` concepts +## 7. Legacy v1.0.0 Status -Implementers MUST NOT project those legacy requirements onto v1.1.0. +`v1.0.0` remains in the repository only as a historical legacy schema family for compatibility review and auditing. -Legacy path pattern: +Its legacy path pattern is: ```text schemas/v1.0.0/commons//requests/.request.schema.json schemas/v1.0.0/commons//receipts/.receipt.schema.json ``` ---- +Implementers MUST NOT project legacy v1.0.0 layout or field expectations onto v1.1.0. -## 7. Schema `$id` Rules +--- -Every v1.1.0 schema MUST use the canonical HTTPS `$id` namespace under this pattern. +## 8. Schema `$id` Rules -Those `$id` values are stable canonical schema identifiers. For v1.1.0 they MUST match the live HTTPS-hosted schema namespace and MUST resolve at the published HTTPS locations. This HTTPS hosting state is distinct from any separate IPFS CID publication record. +Every v1.1.0 schema MUST use the canonical HTTPS `$id` namespace under these patterns. ### Request @@ -227,15 +181,15 @@ Legacy v1.0.0 `$id` layouts remain valid only for the legacy directory tree. --- -## 8. Validation Requirements +## 9. Validation Requirements Implementations claiming v1.1.0 schema compatibility MUST: -1. Validate requests and receipts against the exact schema files shipped for the version being claimed +1. Validate requests and receipts against the exact shipped v1.1.0 schemas 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` +5. Enforce the conditional `summary` and `error` receipt rules Repository validation commands are: @@ -247,104 +201,30 @@ npm run validate --- -## 9. Versioning + Immutability +## 10. Versioning and Publication Records -Once published under a version directory such as: +Once published under a version directory such as `schemas/v1.1.0/`, the schema contents, paths, and `$id` values for that version MUST NOT change in place. -```text -schemas/v1.1.0/ -``` +Release records are documented through repository metadata such as: -there MUST NEVER be in-place mutation of: +- `manifest.json` +- `checksums.txt` +- `CHANGELOG.md` +- `RESOLUTION.md` -- schema file contents -- required field sets -- `$id` values -- documented semantics for that version - -Any semantic or structural change requires a new version directory. +Those records support checksum verification and version tracking. They do not constitute signed release provenance. --- -## 10. Provenance & Integrity - -The current v1.1.0 schema family is identified by: - -- Version directory: `schemas/v1.1.0/` -- Package version: `1.1.0` -- Manifest entry: `manifest.json` -- File-level hashes: `checksums.txt` -- Canonical HTTPS schema host: `https://commandlayer.org/schemas/v1.1.0/` -- IPFS directory CID: `PENDING` until IPFS CID publication is complete - -The last fully pinned canonical release is: - -- Version directory: `schemas/v1.0.0/` -- IPFS directory CID: `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` - -Auditors and resolvers SHOULD: - -1. Fetch the versioned schemas -2. Verify integrity locally -3. Treat mismatched artifacts as untrusted -4. Treat v1.1.0 HTTPS identifiers as live canonical schema references, while treating IPFS provenance for v1.1.0 as pending until a CID is published - -Integrity check command: - -```bash -npm run checksums:verify -``` - ---- - -## 11. Implementations MUST +## 11. Conformance Summary An implementation supporting Commons v1.1.0 MUST: -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 -6. Avoid representing v1.1.0 as the historical pinned release until its IPFS CID publication is complete - -A system supporting any canonical verb MAY claim **Commons-Compatible** for that version, but provenance claims MUST accurately reflect whether the relevant version is the current canonical HTTPS-hosted schema family or the historical pinned release. - ---- - -## 12. Failure Modes - -If any of the following occur: - -- `$id` mismatch -- request or receipt fails strict validation -- required conditional receipt fields are missing -- published artifacts differ from expected checksums -- published artifacts are mutated in place -- a current canonical HTTPS-hosted version is misrepresented as the historical pinned release - -consumers MUST treat the artifact as untrusted and SHOULD reject it. - -Silent degradation MUST NOT occur. - ---- - -## 13. Security - -Protocol-Commons is security-relevant infrastructure. - -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 +1. Use the canonical verb names exactly +2. Enforce the flat request contract +3. Enforce the flat receipt contract +4. Use the exact v1.1.0 `$id` namespace +5. Treat v1.0.0 as historical legacy material only -**v1.1.0:** current canonical schema family documented here; HTTPS hosting is live and IPFS CID publication remains pending in repository metadata -**v1.0.0:** legacy schema family and historical pinned release +**v1.1.0** is the current release and active schema line. +**v1.0.0** is historical legacy material only. diff --git a/manifest.json b/manifest.json index a8264a5..a7ba864 100644 --- a/manifest.json +++ b/manifest.json @@ -2,7 +2,11 @@ "name": "@commandlayer/commons", "version": "1.1.0", "package_version": "1.1.0", +<<<<<<< codex/normalize-documentation-for-v1.1.0-release + "description": "Commons verb + schema package metadata for the current v1.1.0 release and active schema line; IPFS publication for v1.1.0 is tracked separately until a CID is recorded.", +======= "description": "Current release metadata for the v1.1.0 commons package.", +>>>>>>> main "owner": "commandlayer.eth", "contact": "dev@commandlayer.org", "license": "MIT", @@ -151,10 +155,23 @@ ], "active_release": { "version": "1.1.0", - "status": "current release", + "status": "current release and active schema line", "schemas_root": "schemas/v1.1.0", "commons_root": "schemas/v1.1.0/commons", "examples_root": "examples/v1.1.0", +<<<<<<< codex/normalize-documentation-for-v1.1.0-release + "schemas_cid": "PENDING", + "pin_status": "awaiting-cid-insertion" + }, + "pinned_canonical_release": { + "version": "1.1.0", + "status": "pinned canonical release after CID insertion", + "schemas_root": "schemas/v1.1.0", + "commons_root": "schemas/v1.1.0/commons", + "examples_root": "examples/v1.1.0", + "schemas_cid": "PENDING", + "pin_status": "awaiting-cid-insertion" +======= "schemas_cid": "__INSERT_V1_1_0_CID__", "pin_status": "published" }, @@ -166,5 +183,6 @@ "examples_root": "examples/v1.1.0", "schemas_cid": "__INSERT_V1_1_0_CID__", "pin_status": "published" +>>>>>>> main } } diff --git a/package.json b/package.json index 0e8590c..52efafb 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@commandlayer/commons", "version": "1.1.0", - "description": "Canonical Commons verbs and strict JSON Schemas for autonomous agents \u2014 active v1.1.0 HTTPS-hosted schema line, historical pinned v1.0.0 release, and cross-runtime interoperability.", + "description": "Canonical Commons verbs and strict JSON Schemas for autonomous agents \u2014 current v1.1.0 release, active schema line, documented release metadata, and cross-runtime interoperability.", "private": false, "type": "module", "license": "MIT",