From a2521eeeaf33247fa98ea6a10093e94e9cc39ccd Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Wed, 18 Mar 2026 13:07:04 -0400 Subject: [PATCH] Fix blocking protocol commons audit items --- GOVERNANCE.md | 16 +++---- ONBOARDING.md | 48 ++++++++++----------- RESOLUTION.md | 11 ++--- SECURITY.md | 3 +- manifest.json | 76 +++++++++++++++++++++++++++++++++- scripts/build-manifest.mjs | 17 +++++++- scripts/find-union-types.mjs | 2 +- scripts/generate-checksums.mjs | 17 ++++---- 8 files changed, 140 insertions(+), 50 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index c11b8f5..a2390c7 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,7 +1,7 @@ # Governance — Protocol Commons **Scope:** Protocol-Commons (primary), Agent-Cards (identity bindings) -**Status:** v1.0.0 — Stable-Lock +**Status:** v1.0.0 — Stable-Lock; v1.1.0 — Active In-Repo Pre-Release Candidate > This governance is **NORMATIVE, ENFORCEABLE, AND PERMANENT**. > Control is custodial today and **designed to decentralize** as adoption grows. @@ -96,6 +96,11 @@ Commercial schemas inherit similar guarantees: Attempts to mutate semantics in place MUST be treated as **UNTRUSTED**. +The current lock states are interpreted strictly: + +- **v1.0.0 Stable-Lock** means the last fully pinned canonical release with published CID, immutable checksums, and locked provenance +- **v1.1.0 active in-repo schema family** means the current repository contract under review and validation, but still a pre-release candidate until pinning is complete + --- ## 5. TXT Key Governance — NORMATIVE @@ -141,9 +146,6 @@ No single key may modify canonical semantics. **All** normative proposals **MUST** originate from a public GitHub Issue linked to a PR. Silent or undocumented changes are **STRICTLY FORBIDDEN.** - - - | Change Class | Version Rule | Required Log | |--------------|--------------|--------------| | **Normative** (behavior change) | `1 → 2` | `RESOLUTION.md` | @@ -152,6 +154,8 @@ Silent or undocumented changes are **STRICTLY FORBIDDEN.** Every semantic release MUST publish new CIDs + checksums. +Until a new release CID is published, contributors MUST describe that version as an active in-repo pre-release candidate rather than a fully pinned canonical release. + --- ## 8. Security Governance @@ -180,8 +184,6 @@ ONLY if: False claims REQUIRE public enforcement action. ---- - -_Last updated: v1.0.0 — Stable-Lock_ +_Last updated: v1.0.0 locked as the last fully pinned canonical release; v1.1.0 active in repo as a pre-release candidate_ Signed: **`commandlayer.eth`** *Founding Steward — CommandLayer Semantic Standards* diff --git a/ONBOARDING.md b/ONBOARDING.md index 760a98c..d971088 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -2,13 +2,13 @@ Welcome to **Protocol-Commons** — the canonical verb + schema layer for autonomous agents. -This repo defines the **semantic contract**: +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 they bind into **x402 envelopes** and **trace primitives** +- How versioned schema families are governed, published, and verified -Stable semantics here protect the entire agent ecosystem. +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. --- @@ -33,7 +33,7 @@ For identity metadata + ENS discovery → see **agent-cards**. Protocol-Commons is the **bottom** layer: ``` -[ Execution ] x402 runtimes (invocation + receipts) +[ Execution ] runtimes and transport envelopes [ Identity ] Agent-Cards (discovery + ownership) [ Semantics ] Protocol-Commons (verbs + schemas) ``` @@ -43,40 +43,38 @@ It answers: “What is this agent trying to do — and what must this message look like?” ## 3. Repo Layout - - -| Folder/File | Meaning | -| --------------------------------- | --------------------------------------- | -| `schemas/v1.0.0/commons/` | Canonical verb schemas (immutable) | -| `schemas/v1.0.0/_shared/` | Shared primitives (trace/x402/receipts) | -| `examples/v1.0.0/commons/` | Valid + invalid test vectors | -| `manifest.json` + `checksums.txt` | Integrity + provenance | -| `SPEC.md` | Canonical rules | -| `POLICY.md` | Schema enforcement rules | -| `GOVERNANCE.md` | Change authority + approvals | -| `SECURITY*.md` | Disclosure + provenance | -| `RESOLUTION.md` | Change log (signed provenance) | - +| Folder/File | Meaning | +| --------------------------------- | -------------------------------------------------------------------- | +| `schemas/v1.1.0/commons/` | Active in-repo Commons schemas (current pre-release candidate) | +| `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 - -- `POLICY.md` — versioning and extension governance +- `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 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.` +**ENS TXT Summary** +Protocol-Commons governs TXT keys that resolve schema semantics. +Canonical definitions → `SPEC.md`. ## 4. Contribution Flow 1. Open an Issue describing context + verb(s) -2. Design change per POLICY.md +2. Design change per `SCHEMAS.md` 3. Update schemas + examples 4. Validate: diff --git a/RESOLUTION.md b/RESOLUTION.md index a8a46b7..2a6ad38 100644 --- a/RESOLUTION.md +++ b/RESOLUTION.md @@ -13,7 +13,7 @@ If a change is **not** documented here, it is **not** considered valid. - **Date** — final decision date - **Verb(s)** — affected canonical verbs -- **Action** — Added · Deprecated · Replaced · Removed +- **Action** — Added · Deprecated · Replaced · Removed · Revised - **Reason** — interoperability, security, redundancy, etc. - **Resolution** — final state (including replacements, if any) - **Approver(s)** — Governance sign-off @@ -22,9 +22,10 @@ If a change is **not** documented here, it is **not** considered valid. ## Decision Log -| 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 | +| 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 pre-release candidate published, CID pending | Founding Steward | > Any future semantic change requires a **new version directory** and **new CID** prior to approval and publication in this Resolution Log. @@ -48,4 +49,4 @@ Maintainers must review before any merge: - `GOVERNANCE.md` - `SECURITY_PROVENANCE.md` -**Status:** Stable · v1.0.0 locked +**Status:** v1.1.0 pre-release candidate published, CID pending; v1.0.0 remains locked as the last pinned canonical release. diff --git a/SECURITY.md b/SECURITY.md index bcfbf9a..74020cf 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -46,5 +46,4 @@ These guarantees keep Commons safe to depend on long-term. --- -Status: Stable • Verifiable • Production-grade semantics • v1.0.0 locked - +Status: v1.0.0 locked as the last fully pinned canonical release • v1.1.0 active as the current pre-release candidate • verifiable semantics diff --git a/manifest.json b/manifest.json index 84013a6..0506ac4 100644 --- a/manifest.json +++ b/manifest.json @@ -11,7 +11,7 @@ "schemas_root": "schemas/v1.1.0", "examples_root": "examples/v1.1.0", "checksum_file": "checksums.txt", - "schemas_cid": "PENDING", + "schemas_cid": "PENDING (pre-release candidate; pinning not yet published)", "tag": "commons-schemas-v1.1.0", "verbs": [ { @@ -76,5 +76,77 @@ } ], "latest_commons_root": "schemas/v1.1.0/commons", - "pin_target": "schemas/v1.1.0/commons" + "pin_target": "schemas/v1.1.0/commons", + "status": "pre-release-candidate", + "historical_releases": [ + { + "version": "1.0.0", + "status": "locked", + "schemas_root": "schemas/v1.0.0", + "examples_root": "examples/v1.0.0", + "schemas_cid": "bafybeigvf6nkzws7dblos74dqqjkguwkrwn4a2c27ieygoxmgofyzdkz6m", + "verbs": [ + { + "name": "analyze", + "category": "cognition", + "request_schema": "schemas/v1.0.0/commons/analyze/requests/analyze.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/analyze/receipts/analyze.receipt.schema.json" + }, + { + "name": "classify", + "category": "cognition", + "request_schema": "schemas/v1.0.0/commons/classify/requests/classify.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/classify/receipts/classify.receipt.schema.json" + }, + { + "name": "fetch", + "category": "io", + "request_schema": "schemas/v1.0.0/commons/fetch/requests/fetch.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/fetch/receipts/fetch.receipt.schema.json" + }, + { + "name": "format", + "category": "transform", + "request_schema": "schemas/v1.0.0/commons/format/requests/format.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/format/receipts/format.receipt.schema.json" + }, + { + "name": "parse", + "category": "structure", + "request_schema": "schemas/v1.0.0/commons/parse/requests/parse.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/parse/receipts/parse.receipt.schema.json" + }, + { + "name": "summarize", + "category": "cognition", + "request_schema": "schemas/v1.0.0/commons/summarize/requests/summarize.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/summarize/receipts/summarize.receipt.schema.json" + }, + { + "name": "clean", + "category": "transform", + "request_schema": "schemas/v1.0.0/commons/clean/requests/clean.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/clean/receipts/clean.receipt.schema.json" + }, + { + "name": "convert", + "category": "transform", + "request_schema": "schemas/v1.0.0/commons/convert/requests/convert.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/convert/receipts/convert.receipt.schema.json" + }, + { + "name": "describe", + "category": "cognition", + "request_schema": "schemas/v1.0.0/commons/describe/requests/describe.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/describe/receipts/describe.receipt.schema.json" + }, + { + "name": "explain", + "category": "cognition", + "request_schema": "schemas/v1.0.0/commons/explain/requests/explain.request.schema.json", + "receipt_schema": "schemas/v1.0.0/commons/explain/receipts/explain.receipt.schema.json" + } + ] + } + ] } diff --git a/scripts/build-manifest.mjs b/scripts/build-manifest.mjs index 70b786d..9ee03f8 100644 --- a/scripts/build-manifest.mjs +++ b/scripts/build-manifest.mjs @@ -1 +1,16 @@ -// TODO +#!/usr/bin/env node +/** + * This script is intentionally a non-functional stub. + * + * `manifest.json` currently contains release-state metadata that is curated by maintainers, + * including active versus historical release status and CID publication state. Because this + * workflow is not yet fully derived from repository contents alone, this script is not wired + * into the release process and MUST NOT be relied on to regenerate canonical manifest data. + * + * Canonical source today: the checked-in `manifest.json` reviewed through governance. + */ + +console.error( + 'build-manifest.mjs is not wired into the release workflow and must not be used as a canonical manifest generator.' +); +process.exit(1); diff --git a/scripts/find-union-types.mjs b/scripts/find-union-types.mjs index dfaa268..42abfba 100644 --- a/scripts/find-union-types.mjs +++ b/scripts/find-union-types.mjs @@ -16,7 +16,7 @@ import { promises as fs } from 'fs'; import path from 'path'; const ROOT_DIR = process.cwd(); -const SCHEMAS_ROOT = path.join(ROOT_DIR, 'schemas', 'v1.0.0'); +const SCHEMAS_ROOT = path.join(ROOT_DIR, 'schemas'); async function collectSchemaFiles(dir) { const entries = await fs.readdir(dir, { withFileTypes: true }); diff --git a/scripts/generate-checksums.mjs b/scripts/generate-checksums.mjs index 8037cf0..bba1272 100644 --- a/scripts/generate-checksums.mjs +++ b/scripts/generate-checksums.mjs @@ -1,4 +1,9 @@ #!/usr/bin/env node +/** + * NOTE: This Node.js helper is not the canonical checksum generator for release workflows. + * The canonical generator remains scripts/generate-checksums.sh, which package.json invokes. + * Keep this helper behavior aligned with the shell script's text-mode `checksums.txt` output. + */ import fs from "fs"; import path from "path"; import crypto from "crypto"; @@ -10,7 +15,7 @@ function die(msg) { } // --- Args: [rootDir] [outFile] -const rootDirArg = process.argv[2] || "schemas/v1.0.0"; +const rootDirArg = process.argv[2] || "schemas"; const outFileArg = process.argv[3] || "checksums.txt"; // Resolve repo root (scripts/..) @@ -52,9 +57,8 @@ function walkDir(absDir, relBasePosix, acc) { const stat = fs.statSync(absChild); if (stat.isDirectory()) { walkDir(absChild, relChildPosix, acc); - } else if (stat.isFile()) { - // Canonical scope: JSON schemas only - if (relChildPosix.endsWith(".json")) acc.push(relChildPosix); + } else if (stat.isFile() && relChildPosix.endsWith(".json")) { + acc.push(relChildPosix); } } } @@ -64,7 +68,7 @@ function main() { const st = fs.statSync(rootAbs); if (!st.isDirectory()) die(`Root is not a directory: ${rootDirArg}`); - const relRootPosix = toPosix(rootDirArg); + const relRootPosix = toPosix(path.relative(repoRoot, rootAbs)) || "."; const files = []; walkDir(rootAbs, relRootPosix, files); @@ -73,8 +77,7 @@ function main() { const lines = files.map((relPosix) => { const absPath = path.join(repoRoot, relPosix); const hash = sha256File(absPath); - // Match common sha256sum style (binary marker *) - return `${hash} *${relPosix}`; + return `${hash} ${relPosix}`; }); fs.writeFileSync(outAbs, lines.join("\n") + "\n", "utf8");