From 5bb8e18427eb4aa2db05e993edeb6d0eed82c60d Mon Sep 17 00:00:00 2001 From: Greg Soucy Date: Thu, 14 May 2026 23:08:19 -0400 Subject: [PATCH] docs: add CommandLayer stack contract --- contracts/commandlayer-stack-contract.md | 294 +++++++++++++++++++++++ 1 file changed, 294 insertions(+) create mode 100644 contracts/commandlayer-stack-contract.md diff --git a/contracts/commandlayer-stack-contract.md b/contracts/commandlayer-stack-contract.md new file mode 100644 index 0000000..654adbb --- /dev/null +++ b/contracts/commandlayer-stack-contract.md @@ -0,0 +1,294 @@ +# CommandLayer Stack Contract + +Status: Normative alignment contract +Scope: CommandLayer protocol stack + +This document defines the canonical cross-repository contract for the CommandLayer stack. It defines how repositories interpret the CommandLayer action receipt lifecycle and where responsibilities belong across the stack. + +This contract does not replace CLAS schemas, governance RFCs, or release policy. CLAS schemas remain the normative machine-readable artifacts. Governance RFCs remain the process for material protocol changes. This document binds implementation expectations across repositories so that receipt semantics, verification behavior, and public documentation do not drift. + +## 1. Authority and scope + +This file is the canonical alignment contract for the CommandLayer stack. + +Implementations that claim compatibility with the CommandLayer stack MUST align with this contract unless a later accepted governance RFC explicitly supersedes it. + +This contract applies to: + +- receipt construction +- receipt proof structure +- canonicalization +- hashing +- signature verification +- verifier result semantics +- repository responsibility boundaries +- cross-repository compatibility expectations + +This contract does not define commercial packaging, hosted service pricing, product tiers, or package publication status. + +## 2. Repository responsibility map + +The following responsibility boundaries are normative. + +| Repository | Responsibility | +| --- | --- | +| `commandlayer/governance` | Policy, RFCs, release coordination, compatibility matrix, audits, and security coordination. | +| `commandlayer/clas` | Normative CLAS schemas, specifications, and contract documents. | +| `commandlayer/runtime-core` | Canonicalization, hashing, signing, and verification primitives only. | +| `commandlayer/runtime` | Execution engine and receipt emission. | +| `commandlayer/agent-sdk` | Developer wrapper for emitting, submitting, and verifying CommandLayer receipts. | +| `commandlayer/verifyagent` | Public verifier implementation, UI, and API. | +| `commandlayer/mcp-server` | MCP bridge and transport integration. | +| `commandlayer/commandlayer-org` | Public website, documentation, registry, and demos. | + +No repository MAY redefine receipt semantics in a way that conflicts with this contract. + +## 3. Receipt object requirements + +A CommandLayer receipt is a signed record of an agent action. + +A compliant receipt MUST include the following top-level fields: + +- `receipt_id` +- `signer` +- `verb` +- `ts` +- `input` +- `output` +- `execution` +- `metadata` + +A compliant receipt MUST include a proof object at `metadata.proof`. + +The `metadata.proof` object MUST include: + +- `canonicalization` +- `hash.alg` +- `hash.value` +- `signature.alg` +- `signature.value` +- `signature.kid` + +The `signer` field MUST identify the claimed signer namespace or identity. + +The `verb` field MUST identify the action type or command family represented by the receipt. + +The `ts` field MUST identify the receipt timestamp in a schema-valid format. + +The `input`, `output`, and `execution` fields MUST preserve the action context required by the applicable CLAS schema. + +## 4. Canonicalization + +The normative canonicalization identifier is: + +```text +json.sorted_keys.v1 +``` + +Implementations MUST use deterministic JSON canonicalization. + +Implementations MUST sort object keys recursively. + +Implementations MUST preserve JSON value semantics. + +Implementations MUST NOT include `metadata.proof.signature.value` itself in the signed hash payload unless an applicable schema version explicitly defines otherwise. + +Verifiers MUST reject receipts that specify an unsupported canonicalization identifier. + +## 5. Hashing + +The normative hash algorithm is: + +```text +SHA-256 +``` + +The hash algorithm value in the receipt MUST identify SHA-256. + +Hash values MUST be encoded as lowercase hexadecimal unless a schema version explicitly defines another encoding. + +Verifiers MUST recompute the canonical payload hash. + +Verifiers MUST fail verification if the recomputed hash differs from `metadata.proof.hash.value`. + +## 6. Signatures + +The normative signature algorithm is: + +```text +Ed25519 +``` + +Signature verification MUST be real and MUST NOT be mocked, skipped, simulated, or replaced with placeholder logic. + +Verifiers MUST fail closed if the public key cannot be resolved. + +The signature key id MUST be represented by `metadata.proof.signature.kid`. + +The `signer` field MUST identify the claimed signer namespace or identity. + +ENS TXT records MAY be used for public key discovery where supported. + +No implementation MAY hardcode production public keys as the only verification path. + +Verifiers MUST reject receipts that specify an unsupported signature algorithm. + +## 7. Verifier result shape + +A verifier response MUST expose enough information for callers to determine whether the receipt verified and which checks passed or failed. + +A verified receipt SHOULD use the following minimum shape: + +```json +{ + "ok": true, + "status": "VERIFIED", + "checks": { + "schema": true, + "canonical_hash": true, + "signature": true, + "signer": true + }, + "errors": [] +} +``` + +An invalid receipt SHOULD use the following minimum shape: + +```json +{ + "ok": false, + "status": "INVALID", + "checks": { + "schema": false, + "canonical_hash": false, + "signature": false, + "signer": false + }, + "errors": [] +} +``` + +Implementations MAY include additional fields, but MUST NOT reverse the meaning of `ok`, `status`, `checks`, or `errors`. + +`status` MUST NOT be `VERIFIED` unless all required verification checks pass. + +## 8. Required verification checks + +A compliant verifier MUST check: + +- schema validity +- required fields +- canonicalization identifier +- hash algorithm +- recomputed hash match +- signature algorithm +- signature validity +- signer/key consistency +- unsupported algorithms +- malformed proof structure +- unsupported receipt version where versioning is present + +A verifier MUST fail closed when it cannot establish required proof validity. + +## 9. Standard error codes + +Implementations SHOULD use the following error codes when reporting verification failures: + +| Error code | Meaning | +| --- | --- | +| `ERR_INVALID_SIGNATURE` | Signature verification failed. | +| `ERR_HASH_MISMATCH` | Recomputed hash did not match receipt hash. | +| `ERR_SCHEMA_INVALID` | Receipt failed schema validation. | +| `ERR_ENS_KEY_NOT_FOUND` | ENS-backed public key discovery failed. | +| `ERR_CANONICALIZATION_MISMATCH` | Unsupported or mismatched canonicalization identifier. | +| `ERR_UNSUPPORTED_ALGORITHM` | Unsupported hash or signature algorithm. | +| `ERR_MISSING_REQUIRED_FIELD` | Required field is absent. | +| `ERR_SIGNER_MISMATCH` | Signer identity does not match resolved key material or expected signer. | +| `ERR_UNSUPPORTED_RECEIPT_VERSION` | Receipt version is unsupported. | +| `ERR_MALFORMED_PROOF` | Proof object is missing, malformed, or internally inconsistent. | + +Repositories MAY add narrower error codes, but SHOULD preserve these codes for cross-repository compatibility. + +## 10. Compatibility expectations + +### `commandlayer/runtime-core` + +`runtime-core` MUST NOT perform network calls. + +`runtime-core` MUST NOT emit runtime execution receipts. + +`runtime-core` MUST NOT contain website or demo UI code. + +`runtime-core` MUST provide compliant canonicalization, hashing, signing, and verification primitives. + +### `commandlayer/runtime` + +`runtime` MUST NOT redefine cryptographic semantics. + +`runtime` MUST use `runtime-core` or equivalent compliant primitives. + +`runtime` MUST emit receipts aligned with CLAS schemas and this contract. + +### `commandlayer/agent-sdk` + +`agent-sdk` MUST NOT invent alternate receipt shapes. + +`agent-sdk` MUST expose developer APIs aligned to CLAS. + +`agent-sdk` MUST NOT claim verification success unless verifier results satisfy this contract. + +### `commandlayer/verifyagent` + +`verifyagent` MUST verify using this contract. + +`verifyagent` MUST NOT mark receipts as verified if hash or signature checks fail. + +`verifyagent` MUST expose failure information without weakening cryptographic guarantees. + +### `commandlayer/mcp-server` + +`mcp-server` MUST bridge protocol actions without changing receipt semantics. + +`mcp-server` MUST NOT mutate receipt proof fields in a way that invalidates canonical verification. + +### `commandlayer/commandlayer-org` + +`commandlayer-org` MUST document only supported behavior. + +`commandlayer-org` MUST NOT claim unsupported package publication status or verification guarantees. + +`commandlayer-org` demos MUST make clear when data is sample, demo, or live verification output. + +### `commandlayer/governance` + +`governance` MUST coordinate material changes through RFCs and compatibility updates. + +`governance` MUST maintain release sequencing and compatibility records for contract-impacting changes. + +## 11. Rules for changing this contract + +Material changes to this contract require governance review. + +Breaking changes require an accepted RFC. + +Downstream repositories MUST be audited after contract-impacting changes. + +The compatibility matrix MUST be updated when contract-impacting behavior changes. + +Changes that alter receipt shape, canonicalization, hashing, signing, verifier status semantics, or repository boundaries MUST be treated as material. + +## 12. Non-goals + +This file does not define: + +- commercial pricing +- hosted API limits +- x402 payment rules +- UI requirements +- chain-specific deployment requirements +- package publication status +- business development strategy +- customer onboarding flows + +Those concerns MAY be documented in other repositories, but they MUST NOT conflict with this contract when they describe CommandLayer receipt behavior.