From 0d779edc331b1a3b4fe7737ab4dd40eff48e9cfb Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Wed, 18 Mar 2026 12:42:57 -0400 Subject: [PATCH] Align v1.1.0 documentation status --- COMPLIANCE.md | 57 +++++++++++----- README.md | 18 +++-- SCHEMAS.md | 55 +++++++++------ SECURITY_PROVENANCE.md | 149 +++++++++++++++++++++-------------------- SPEC.md | 96 ++++++++++++++++---------- 5 files changed, 226 insertions(+), 149 deletions(-) diff --git a/COMPLIANCE.md b/COMPLIANCE.md index ea4e53d..2e76085 100644 --- a/COMPLIANCE.md +++ b/COMPLIANCE.md @@ -23,7 +23,22 @@ Compliance covers semantics and schema integrity only—identity bindings are go --- -## 2. Versioning & Immutability +## 2. Version-Aware Compliance Status + +Compliance claims MUST identify the version they apply to. + +Current repository status: + +- **v1.1.0** — current in-repo schema family; CID publication still pending +- **v1.0.0** — last fully pinned canonical release + +A system MAY claim **v1.1.0 schema compatibility** if it validates and enforces the published v1.1.0 schemas. + +A system MUST NOT claim **fully pinned canonical v1.1.0 release compliance** until the v1.1.0 CID and provenance record are published. + +--- + +## 3. Versioning & Immutability For any directory `schemas/vX.Y.Z/`: @@ -35,7 +50,7 @@ No in-place edits to: Any semantic change requires: - New version directory -- Updated CIDs + checksums +- Updated CIDs + checksums for canonical releases - Logged update in `RESOLUTION.md` - Governance approval @@ -43,22 +58,22 @@ Mutating a published version is **not compliant**. --- -## 3. JSON Schema Requirements +## 4. JSON Schema Requirements 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 verb-specific input + receipt contract +- Enforce the version-specific input + receipt contract Loose validation or altered `$id` resolution is **not compliant**. --- -## 4. CIDs & Checksums +## 5. CIDs & Checksums -Each release MUST: +Each canonical release MUST: - Pin the entire version folder to IPFS - Provide SHA-256 checksums @@ -66,8 +81,8 @@ Each release MUST: Compliance requires: -- `cl.cid.schemas` resolves to the correct CID -- IPFS mirrors match HTTP mirrors exactly +- Canonical TXT/CID bindings only for fully published releases +- IPFS mirrors match HTTP mirrors exactly for pinned releases Consumers SHOULD verify `checksums.txt` against the published schema artifacts prior to use. @@ -77,8 +92,11 @@ canonical compliance, and MUST reject mismatches. Mismatch = **integrity failure** +For v1.1.0 specifically, the schemas and checksums can still be validated locally, but the release MUST be described as pre-release until its CID publication is complete. + +--- -## 5. Security & Privacy +## 6. Security & Privacy Schemas are **semantic infrastructure**, not application output. @@ -91,7 +109,7 @@ Security incidents MUST follow `SECURITY.md`. --- -## 6. Governance Traceability +## 7. Governance Traceability Every canonical change MUST be reflected in: - `RESOLUTION.md` (what + why + who) @@ -101,18 +119,22 @@ An artifact **without a governance trail** is not canonical. --- -## 7. Ecosystem Alignment +## 8. Ecosystem Alignment Commons-compliant implementations SHOULD: - Support ERC-8004 discovery where relevant -- Enforce canonical x402 envelope + trace rules +- Apply only the requirements that are normative for the version they implement + +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 is allowed — but **compliance claims then MUST NOT be made**. +Divergence from the version-specific Commons contract means **compliance claims then MUST NOT be made**. --- -## 8. Deviation Handling +## 9. Deviation Handling If a deviation is found: @@ -123,15 +145,16 @@ If a deviation is found: --- -## 9. Compliance Checklist +## 10. Compliance Checklist -You may claim **Protocol-Commons compliant** if: +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 +- 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 pinned canonical or pre-release If uncertain → treat the implementation as **experimental**. diff --git a/README.md b/README.md index bb4f07f..7c5f66f 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ **The canonical semantic contract for autonomous agents.** *Verbs, schemas, and validation — or nothing interoperates.* -[![Schemas](https://img.shields.io/badge/Schemas-Stable%20v1.1.0-brightgreen)](https://github.com/commandlayer/protocol-commons) +[![Schemas](https://img.shields.io/badge/Schemas-v1.1.0%20candidate-yellow)](https://github.com/commandlayer/protocol-commons) [![NPM Version](https://img.shields.io/npm/v/@commandlayer/commons)](https://www.npmjs.com/package/@commandlayer/commons) [![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) @@ -26,10 +26,11 @@ Protocol-Commons is the foundation for portable machine intent: a stable set of > **Integrity Notice — Protocol-Commons v1.1.0** > -> Canonical schemas are pinned and immutable: +> `schemas/v1.1.0/commons` is the current in-repo schema family, but its release CID is still pending: > `schemas/v1.1.0/commons` — CID: `TBD (pre-release)` > -> Historical v1.0.0 artifacts remain in-repo for compatibility and verification. +> `v1.0.0` remains the last fully pinned canonical release: +> `schemas/v1.0.0/` — CID: `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` > > Verify integrity locally: > ```bash @@ -160,7 +161,9 @@ console.log(validate.errors ?? []); ## Commons v1.1.0 -Commons v1.1.0 introduces a simplified, flat schema surface for general-purpose agent actions. +Commons v1.1.0 is the active schema family in this repository. + +It is ready for schema validation and local integration work, but its release provenance is still **pre-release** until a real CID is published. - Each request schema is standalone - Each receipt schema is standalone @@ -349,10 +352,11 @@ Commons gives upper layers a stable meaning layer to build around. ## Status -**Stable — v1.1.0 current** +**v1.1.0 — active schema family, release CID pending** -- `v1.1.0` is the current flat Commons layout -- `v1.0.0` remains in-repo as a legacy schema family +- `v1.1.0` is the current flat Commons layout in this repo +- `v1.0.0` remains the last fully pinned canonical release +- Do not describe `v1.1.0` provenance as fully canonical until pinning is complete --- diff --git a/SCHEMAS.md b/SCHEMAS.md index f2b6a61..d07f929 100644 --- a/SCHEMAS.md +++ b/SCHEMAS.md @@ -20,9 +20,20 @@ Once published, a version directory is immutable. --- -## 2. Directory Layout +## 2. Version Status -### Current layout: v1.1.0 +This repository currently ships: + +- **v1.1.0** as the active in-repo schema family +- **v1.0.0** as the historical and last fully pinned canonical release + +Because `manifest.json` still reports the v1.1.0 schema CID as pending, documentation MUST describe v1.1.0 as **pre-release for provenance/pinning status** until a real CID is published. + +--- + +## 3. Directory Layout + +### Current in-repo layout: v1.1.0 ```text schemas/v1.1.0/ @@ -32,7 +43,7 @@ schemas/v1.1.0/ └── .receipt.schema.json ``` -### Legacy layout: v1.0.0 +### Historical pinned layout: v1.0.0 ```text schemas/v1.0.0/ @@ -57,7 +68,7 @@ schemas/v1.0.0/ --- -## 3. Canonical Verb Set +## 4. Canonical Verb Set | Verb | Purpose | |------|---------| @@ -79,7 +90,7 @@ Each verb MUST define exactly: --- -## 4. Deterministic `$id` Contract +## 5. Deterministic `$id` Contract ### v1.1.0 request schemas @@ -107,13 +118,13 @@ https://commandlayer.org/schemas/v1.1.0/commons/summarize/summarize.receipt.sche ### Legacy v1.0.0 note -Legacy v1.0.0 schemas retain their older nested `$id` patterns and `_shared` references. Those patterns 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 and are not the v1.1.0 contract. All `$id` values MUST be fully qualified HTTPS URLs. --- -## 5. v1.1.0 Request Contract +## 6. v1.1.0 Request Contract Every v1.1.0 request MUST include: @@ -130,7 +141,7 @@ v1.1.0 requests do not use nested request objects, `x402`, `trace`, or `actor` f --- -## 6. v1.1.0 Receipt Contract +## 7. v1.1.0 Receipt Contract Every v1.1.0 receipt MUST include: @@ -159,21 +170,21 @@ The trust model is limited to signer attestation plus request/result hash refere --- -## 7. Legacy v1.0.0 Scope +## 8. Legacy v1.0.0 Scope -v1.0.0 remains in-repo for compatibility and historical verification. +v1.0.0 remains in-repo for compatibility, historical verification, and canonical pin auditing. Its schemas use: - `_shared` helper schemas - nested `requests/` and `receipts/` folders -- older envelope conventions +- older envelope conventions including `x402` and `trace` -Documentation and tooling MUST distinguish that legacy structure from v1.1.0. +Documentation and tooling MUST distinguish that legacy structure from v1.1.0 and MUST NOT present those legacy fields as universally normative. --- -## 8. Versioning Rules +## 9. Versioning Rules Once published under a version directory such as `schemas/v1.1.0/`, the following actions are prohibited: @@ -186,7 +197,7 @@ Any change requires a new version directory. --- -## 9. Validation Requirements +## 10. Validation Requirements CI and local validation SHOULD enforce strict schema compilation behavior equivalent to: @@ -210,7 +221,7 @@ All shipped valid and invalid examples MUST match the version-specific schema la --- -## 10. Examples +## 11. Examples Examples are maintained per version. @@ -232,7 +243,7 @@ examples/v1.0.0/commons// --- -## 11. Provenance & Integrity +## 12. Provenance & Integrity Integrity is tracked by: @@ -245,13 +256,19 @@ Current v1.1.0 schema CID status: TBD (pre-release) ``` -Resolvers and auditors MUST reject mismatched artifacts. +Last pinned canonical release CID: + +```text +v1.0.0 → bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m +``` + +Resolvers and auditors MUST reject mismatched artifacts and MUST distinguish between a shipped schema family and a fully pinned canonical release. --- -## 12. Contact +## 13. Contact - dev@commandlayer.org - PGP 5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A -**Status:** Stable `v1.1.0` current; `v1.0.0` legacy +**Status:** v1.1.0 active in-repo schema family with pending CID; v1.0.0 retained as the historical pinned canonical release. diff --git a/SECURITY_PROVENANCE.md b/SECURITY_PROVENANCE.md index c1504e4..5c1a22a 100644 --- a/SECURITY_PROVENANCE.md +++ b/SECURITY_PROVENANCE.md @@ -1,71 +1,78 @@ -# Security Provenance — Protocol Commons -**Scope:** Protocol-Commons -**Status:** v1.0.0 — Stable-Lock -**This document is NORMATIVE and ENFORCEABLE.** - -Defines cryptographic provenance, integrity guarantees, and audit mechanisms -for canonical Protocol-Commons schemas. - ---- - -## Contact -If something seems incorrect, report immediately: - -Email: dev@commandlayer.org -PGP fingerprint: 5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A - -Private disclosure is preferred for security-sensitive findings. - ---- - -## Provenance & Version Integrity -Releases are **reproducible and content-addressed**. - -Current canonical version: **v1.0.0** - -Integrity sources: -- **CID:** `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` -- `checksums.txt` — file-level hashes -- CI strict validation (Ajv) -- `RESOLUTION.md` — immutable lifecycle history - -Any semantic update requires: -- New `schemas/vX.Y.Z/` directory -- New CID and updated checksums -- Governance approval + provenance record - -**No silent edits. No exceptions.** - -Auditors MUST verify: -- HTTP and IPFS mirrors match exactly -- Checksums remain unchanged -- Version directories are immutable - ---- - -## ENS TXT Summary -Protocol-Commons governs TXT keys that resolve **schema semantics**. - -Canonical rules under: -- `SPEC.md` - -Resolvers MUST reject any: -- TXT ↔ CID mismatch -- Unauthorized or missing TXT keys -- Out-of-sync version binding - ---- - -## 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. - ---- - -**Status:** Stable • Verifiable • Production-grade semantics • v1.0.0 locked - +# Security Provenance — Protocol Commons +**Scope:** Protocol-Commons +**Status:** v1.1.0 — Pre-Release Candidate; v1.0.0 remains the last pinned canonical release +**This document is NORMATIVE and ENFORCEABLE.** + +Defines cryptographic provenance, integrity guarantees, and audit mechanisms +for published and release-candidate Protocol-Commons schemas. + +--- + +## Contact +If something seems incorrect, report immediately: + +Email: dev@commandlayer.org +PGP fingerprint: 5016 D496 9F38 22B2 C5A2 FA40 99A2 6950 197D AB0A + +Private disclosure is preferred for security-sensitive findings. + +--- + +## Provenance & Version Integrity +Releases are **reproducible and content-addressed**. + +Current repository schema family: **v1.1.0** +Current canonical pinned release: **v1.0.0** + +Integrity sources: +- **v1.0.0 CID:** `bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m` +- **v1.1.0 CID:** `TBD (pre-release; 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 + +Until a v1.1.0 CID is published and recorded, resolvers and auditors MUST treat v1.1.0 as a pre-release schema family rather than the last fully pinned canonical release. + +Any semantic update requires: +- New `schemas/vX.Y.Z/` directory +- New CID and updated checksums for any canonical release +- Governance approval + provenance record + +**No silent edits. No exceptions.** + +Auditors MUST verify: +- HTTP and IPFS mirrors match exactly for pinned canonical releases +- Checksums remain unchanged +- Version directories are immutable +- A release is not described as fully canonical unless its CID publication is complete + +--- + +## ENS TXT Summary +Protocol-Commons governs TXT keys that resolve **schema semantics**. + +Canonical rules under: +- `SPEC.md` + +Resolvers MUST reject any: +- TXT ↔ CID mismatch +- Unauthorized or missing TXT keys +- Out-of-sync version binding + +For v1.1.0 specifically, TXT/CID binding MUST NOT be represented as canonical until the release CID is published. + +--- + +## 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. + +--- + +**Status:** v1.1.0 is the current in-repo schema family and release candidate; v1.0.0 remains the last fully verifiable pinned canonical release. diff --git a/SPEC.md b/SPEC.md index 14ee644..d3d7171 100644 --- a/SPEC.md +++ b/SPEC.md @@ -21,7 +21,25 @@ Execution, payment, identity, and routing are the domain of other layers. --- -## 2. Architecture Position +## 2. Release Status and Scope + +This repository contains two materially different Commons schema families: + +- **v1.1.0** — current in-repo schema family and active documentation target +- **v1.0.0** — legacy schema family and the last fully pinned canonical release + +Because the v1.1.0 release CID is still unpublished, v1.1.0 MUST be treated as a **pre-release candidate for provenance purposes** even though its schema contracts are fully present in this repository. + +Implementers MUST distinguish between: + +1. **Schema semantics** — what the v1.1.0 files require +2. **Release provenance status** — whether a version has completed CID publication and canonical pinning + +This specification therefore documents the v1.1.0 contract explicitly while preserving v1.0.0 as the last pinned canonical release until v1.1.0 pinning is complete. + +--- + +## 3. Architecture Position The Commons is the semantic base layer of the CommandLayer stack: @@ -43,7 +61,7 @@ The Commons is the semantic base layer of the CommandLayer stack: --- -## 3. Canonical Verb Set +## 4. Canonical Verb Set The only canonical verbs are: @@ -58,11 +76,11 @@ No aliases or synonyms are canonical. --- -## 4. Commons v1.1.0 +## 5. Commons v1.1.0 Schema Contract -Commons v1.1.0 is the current schema family for this repository. +Commons v1.1.0 is the current schema family documented in this repository. -### 4.1 Directory contract +### 5.1 Directory contract Every v1.1.0 schema file MUST reside under: @@ -77,7 +95,7 @@ with exactly these file names: Moving published files is a breaking change. -### 4.2 Request shape (flat) +### 5.2 Request shape (flat) Every v1.1.0 request MUST be a flat JSON object with: @@ -103,23 +121,23 @@ A conforming request shape is: Commons v1.1.0 does not require `x402`, `trace`, `actor`, or nested request wrappers. -### 4.3 Receipt shape +### 5.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"` | +| 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. @@ -154,7 +172,7 @@ A conforming error receipt shape is: } ``` -### 4.4 Trust model +### 5.4 Trust model Commons v1.1.0 provides attestation-oriented receipts: @@ -167,9 +185,9 @@ Commons v1.1.0 does **not** define settlement proofs, transport-level guarantees --- -## 5. v1.0.0 Legacy Status +## 6. v1.0.0 Legacy Status -`v1.0.0` remains in the repository as a legacy schema family for compatibility and historical verification. +`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: @@ -188,7 +206,7 @@ schemas/v1.0.0/commons//receipts/.receipt.schema.json --- -## 6. Schema `$id` Rules +## 7. Schema `$id` Rules Every v1.1.0 schema MUST use a resolvable HTTPS `$id` under this pattern. @@ -208,9 +226,9 @@ Legacy v1.0.0 `$id` layouts remain valid only for the legacy directory tree. --- -## 7. Validation Requirements +## 8. Validation Requirements -Implementations claiming v1.1.0 compatibility MUST: +Implementations claiming v1.1.0 schema compatibility MUST: 1. Validate requests and receipts against the exact published schema files 2. Use JSON Schema draft 2020-12 support @@ -228,7 +246,7 @@ npm run validate --- -## 8. Versioning + Immutability +## 9. Versioning + Immutability Once published under a version directory such as: @@ -247,9 +265,9 @@ Any semantic or structural change requires a new version directory. --- -## 9. Provenance & Integrity +## 10. Provenance & Integrity -The canonical Protocol-Commons v1.1.0 release is identified by: +The current v1.1.0 schema family is identified by: - Version directory: `schemas/v1.1.0/` - Package version: `1.1.0` @@ -257,11 +275,17 @@ The canonical Protocol-Commons v1.1.0 release is identified by: - File-level hashes: `checksums.txt` - IPFS directory CID: `TBD (pre-release)` until a release CID is published +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 as not yet fully pinned until its CID publication is complete Integrity check command: @@ -271,7 +295,7 @@ npm run checksums:verify --- -## 10. Implementations MUST +## 11. Implementations MUST An implementation supporting Commons v1.1.0 MUST: @@ -280,12 +304,13 @@ An implementation supporting Commons v1.1.0 MUST: 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 last fully pinned canonical release until CID publication is complete -A system supporting any canonical verb MAY claim **Commons-Compatible** for that version. +A system supporting any canonical verb MAY claim **Commons-Compatible** for that version, but provenance claims MUST accurately reflect whether the relevant version is fully pinned or still pre-release. --- -## 11. Failure Modes +## 12. Failure Modes If any of the following occur: @@ -294,6 +319,7 @@ If any of the following occur: - required conditional receipt fields are missing - published artifacts differ from expected checksums - published artifacts are mutated in place +- a pre-release version is misrepresented as fully pinned canonical provenance consumers MUST treat the artifact as untrusted and SHOULD reject it. @@ -301,7 +327,7 @@ Silent degradation MUST NOT occur. --- -## 12. Security +## 13. Security Protocol-Commons is security-relevant infrastructure. @@ -318,5 +344,5 @@ Security escalation MUST follow repository policy. ## Status -**Stable — v1.1.0 current** -**Legacy — v1.0.0 retained for compatibility** +**v1.1.0:** current schema family, documented here, CID still pending +**v1.0.0:** legacy schema family and last pinned canonical release