docs: add CommandLayer stack contract for cross-repo alignment

contracts/commandlayer-stack-contract.md

@@ -1,172 +1,187 @@
-# CommandLayer Stack Contract (Canonical Cross-Repository Contract)
-
-## 1. Authority and Scope
-
-This document is the canonical protocol-level contract for the CommandLayer stack.
-
-**Normative authority:** All participating repositories **MUST** align protocol behavior, data shapes, and verification outcomes with this contract.
-
-This contract applies to interoperability between:
-- `runtime-core`
-- `runtime`
-- `agent-sdk`
-- `verifyagent`
-- `mcp-server`
-- `commandlayer-org`
-- `governance`
-
-This contract defines protocol requirements only. It does not define implementation internals unless explicitly stated.
-
-## 2. Repository Responsibility Map
-
-The following responsibilities are normative:
-
-- `runtime-core` **MUST** provide canonical protocol primitives for receipt generation and verification input preparation.
-- `runtime` **MUST** produce receipts and signature proof objects compliant with this contract.
-- `agent-sdk` **MUST** expose APIs that preserve contract-required fields without lossy transformation.
-- `verifyagent` **MUST** evaluate receipts and proofs using the required canonicalization, hash, signature, and validation checks defined herein.
-- `mcp-server` **MUST** transport and expose receipt and verifier result payloads without altering normative fields.
-- `commandlayer-org` **MUST** maintain operational guidance and cross-repo alignment artifacts that reflect this contract.
-- `governance` **MUST** control versioned changes to this contract and adjudicate backward-compatibility expectations.
-
-## 3. Receipt Object Requirements
-
-A receipt is the canonical protocol artifact for command execution evidence.
-
-A conforming receipt object:
-- **MUST** be valid JSON.
-- **MUST** include all required fields defined in Section 4.
-- **MUST** be canonicalizable using `json.sorted_keys.v1` (Section 5).
-- **MUST** be hashable with SHA-256 (Section 6).
-- **MUST** be signable/verifiable with Ed25519 (Section 7).
-- **MAY** include additional non-required fields only if they do not alter required-field semantics.
-
-## 4. Required Receipt Fields
-
-A conforming receipt object **MUST** include, at minimum, the following top-level fields:
-
-- `receiptVersion` (string): protocol receipt version identifier.
-- `receiptId` (string): globally unique receipt identifier.
-- `issuedAt` (string): timestamp in RFC 3339 format.
-- `issuer` (object): issuer identity descriptor.
-- `subject` (object): subject identity descriptor.
-- `payload` (object): command/result payload covered by hashing/signature.
-- `canonicalizationId` (string): **MUST** be `json.sorted_keys.v1`.
-- `hashAlgorithm` (string): **MUST** be `SHA-256`.
-- `payloadHash` (string): digest of the canonicalized payload.
-- `signatureProof` (object): proof object meeting Section 8.
-
-Receipts **SHOULD** avoid nullable required fields. If a required field is present, its value **MUST NOT** be semantically empty for protocol validation.
-
-## 5. Canonicalization ID: `json.sorted_keys.v1`
-
-The canonicalization identifier for this contract is fixed:
-
-- `canonicalizationId` **MUST** equal `json.sorted_keys.v1`.
-
-Normative behavior for `json.sorted_keys.v1`:
-- JSON object keys **MUST** be serialized in lexicographically sorted order at every object depth.
-- Array order **MUST** be preserved as-is.
-- No non-deterministic whitespace **MAY** affect the canonicalized byte sequence.
-- Canonicalization output **MUST** be deterministic for equivalent semantic input.
-
-## 6. Hash Algorithm: SHA-256
-
-- `hashAlgorithm` **MUST** equal `SHA-256`.
-- `payloadHash` **MUST** be computed over the canonicalized payload bytes.
-- Hex or base64 encoding form **MUST** be consistent within an implementation and **SHOULD** be documented by that repository’s API surface.
-
-## 7. Signature Algorithm: Ed25519
-
-- Signature generation and verification **MUST** use `Ed25519`.
-- Implementations **MUST NOT** silently substitute a different algorithm.
-- If a non-supported algorithm is requested or encountered, verifiers **MUST** emit `ERR_UNSUPPORTED_ALGORITHM`.
-
-## 8. Signature Proof Object Requirements
-
-The `signatureProof` object **MUST** contain:
-
-- `algorithm` (string): **MUST** be `Ed25519`.
-- `publicKeyId` (string): stable key reference identifier.
-- `signature` (string): signature over canonicalized/hash-bound receipt material.
-- `signedAt` (string): RFC 3339 timestamp.
-
-The proof object **MAY** include key-discovery metadata (e.g., ENS linkage), but required verification semantics **MUST** remain deterministic from required fields.
-
-## 9. Verifier Result Shape
-
-A verifier result object **MUST** include:
-
-- `ok` (boolean): overall verification outcome.
-- `receiptId` (string): identifier of the evaluated receipt.
-- `checks` (array): per-check outcomes.
-- `errors` (array): zero or more standardized error entries.
-
-Each check entry **SHOULD** include:
-- `name` (string)
-- `ok` (boolean)
-- `code` (string, optional when `ok=true`)
-- `message` (string, optional)
-
-Each error entry **MUST** include:
-- `code` (string)
-- `message` (string)
-
-## 10. Required Verification Checks
-
-Verifiers **MUST** perform, at minimum, the following checks:
-
-1. Receipt structure and required-field presence.
-2. Schema validity against applicable receipt schema.
-3. Canonicalization ID support and deterministic canonicalization conformance.
-4. Hash algorithm support and recomputed hash equality.
-5. Signature algorithm support.
-6. Signature cryptographic validity.
-7. Key resolution/discovery success for declared key identifier.
-
-A failed required check **MUST** set `ok=false` and **MUST** include at least one standardized error code from Section 11.
-
-## 11. Standard Error Codes
-
-Verifiers **MUST** use the following standardized error codes where applicable:
+# CommandLayer Stack Contract
 
+## 1. Authority and scope
+
+This document is the canonical cross-repository alignment contract for the CommandLayer stack.
+
+**Normative requirements:**
+- This contract **MUST** be treated as binding for how participating repositories interpret and enforce receipt lifecycle semantics.
+- This contract **MUST NOT** be interpreted as replacing normative CLAS schemas.
+- This contract **MUST NOT** be interpreted as replacing governance RFC processes.
+- Where schema text and this contract appear to diverge, implementers **MUST** resolve the divergence through governance RFC and schema updates rather than ad hoc implementation behavior.
+
+## 2. Repository responsibility map
+
+The following responsibilities are authoritative:
+
+- **commandlayer/governance**: policy, RFCs, release coordination, compatibility matrix, audits.
+- **commandlayer/clas**: normative CLAS schemas, specs, and contract documents.
+- **commandlayer/runtime-core**: canonicalization, hashing, signing, verification primitives only.
+- **commandlayer/runtime**: execution engine and receipt emission.
+- **commandlayer/agent-sdk**: developer wrapper for emitting and submitting receipts.
+- **commandlayer/verifyagent**: public verifier implementation, UI, and API.
+- **commandlayer/mcp-server**: MCP bridge and transport integration.
+- **commandlayer/commandlayer-org**: public website, docs, registry, and demos.
+
+## 3. Receipt object requirements
+
+A receipt is a signed record of an agent action.
+
+**Normative required top-level fields:**
+- `receipt_id`
+- `signer`
+- `verb`
+- `ts`
+- `input`
+- `output`
+- `execution`
+- `metadata`
+
+**Normative required `metadata.proof` fields:**
+- `canonicalization`
+- `hash.alg`
+- `hash.value`
+- `signature.alg`
+- `signature.value`
+- `signature.kid`
+
+Implementations **MUST** reject receipts missing required fields.
+
+## 4. Canonicalization
+
+Normative canonicalization ID: `json.sorted_keys.v1`.
+
+**Normative requirements:**
+- Implementations **MUST** use deterministic JSON canonicalization.
+- Implementations **MUST** sort object keys recursively.
+- Implementations **MUST** preserve JSON value semantics.
+- Implementations **MUST NOT** include the signature value itself in the signed hash payload unless explicitly specified by the schema.
+
+## 5. Hashing
+
+Normative hash algorithm: `SHA-256`.
+
+**Normative requirements:**
+- Hash value **MUST** be encoded as lowercase hexadecimal unless a schema version explicitly defines another encoding.
+- Verifiers **MUST** recompute the canonical payload hash.
+- Verifiers **MUST** fail if the recomputed hash differs from `metadata.proof.hash.value`.
+
+## 6. Signatures
+
+Normative signature algorithm: `Ed25519`.
+
+**Normative requirements:**
+- Signature verification **MUST** be real and never mocked.
+- Verifiers **MUST** fail closed if the public key cannot be resolved.
+- 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.
+
+## 7. Verifier result shape
+
+Verifiers **MUST** return, at minimum, the following shape for a verified receipt:
+
+```json
+{
+  "ok": true,
+  "status": "VERIFIED",
+  "checks": {
+    "schema": true,
+    "canonical_hash": true,
+    "signature": true,
+    "signer": true
+  },
+  "errors": []
+}
+```
+
+For invalid receipts, verifiers **MUST** return, at minimum:
+
+```json
+{
+  "ok": false,
+  "status": "INVALID",
+  "checks": {
+    "schema": false,
+    "canonical_hash": false,
+    "signature": false,
+    "signer": false
+  },
+  "errors": []
+}
+```
+
+## 8. Required verification checks
+
+Verifiers **MUST** check all of the following:
+- schema validity
+- canonicalization ID
+- hash algorithm
+- recomputed hash match
+- signature algorithm
+- signature validity
+- signer/key consistency
+- required fields
+- unsupported algorithms
+
+## 9. Standard error codes
+
+Verifiers **MUST** support the following standard error codes:
 - `ERR_INVALID_SIGNATURE`
 - `ERR_HASH_MISMATCH`
 - `ERR_SCHEMA_INVALID`
 - `ERR_ENS_KEY_NOT_FOUND`
 - `ERR_CANONICALIZATION_MISMATCH`
 - `ERR_UNSUPPORTED_ALGORITHM`
+- `ERR_MISSING_REQUIRED_FIELD`
+- `ERR_SIGNER_MISMATCH`
+- `ERR_UNSUPPORTED_RECEIPT_VERSION`
+- `ERR_MALFORMED_PROOF`
+
+## 10. Compatibility expectations
+
+### runtime-core
+- **MUST NOT** perform network calls.
+- **MUST NOT** emit runtime execution receipts.
+- **MUST NOT** contain website or demo code.
 
-Error payloads **MAY** include implementation-specific details, but the code values above **MUST** remain exact.
+### runtime
+- **MUST NOT** redefine cryptographic semantics.
+- **MUST** use `runtime-core` or equivalent compliant primitives.
 
-## 12. Compatibility Expectations
+### agent-sdk
+- **MUST NOT** invent alternate receipt shapes.
+- **MUST** expose developer APIs aligned to CLAS.
 
-- `runtime-core` **MUST** maintain contract-level compatibility for canonicalization, hash, and signature primitives.
-- `runtime` **MUST** emit receipts and proofs that pass required checks in conforming verifiers.
-- `agent-sdk` **MUST** preserve normative fields and **MUST NOT** mutate canonicalized/signature-covered content implicitly.
-- `verifyagent` **MUST** emit verifier result shapes and standardized error codes per this contract.
-- `mcp-server` **MUST** relay payloads and results without semantic mutation of normative fields.
-- `commandlayer-org` **SHOULD** publish ecosystem guidance mapped to this contract version.
-- `governance` **MUST** enforce change control and versioning discipline for normative updates.
+### verifyagent
+- **MUST** verify using this same contract.
+- **MUST NOT** mark receipts verified if hash or signature checks fail.
 
-## 13. Rules for Changing This Contract
+### mcp-server
+- **MUST** bridge protocol actions without changing receipt semantics.
 
-Any change to normative requirements in this document:
+### commandlayer-org
+- **MUST** document only supported behavior.
+- **MUST NOT** claim unsupported package status or verification guarantees.
 
-- **MUST** be proposed through governance review.
-- **MUST** include explicit compatibility impact analysis.
-- **MUST** define migration expectations for all repositories listed in Section 2.
-- **MUST** increment contract version metadata when such metadata is introduced.
-- **SHOULD** preserve backward compatibility when feasible; otherwise, breaking changes **MUST** be clearly labeled.
+### governance
+- **MUST** coordinate changes through RFCs and compatibility updates.
 
-No repository **MAY** unilaterally redefine normative terms in this contract.
+## 11. Rules for changing this contract
 
-## 14. Non-Goals
+**Normative requirements:**
+- Material changes **MUST** require governance review.
+- Breaking changes **MUST** require an RFC.
+- Downstream repositories **MUST** be audited after contract changes.
+- Compatibility matrix **MUST** be updated when contract-impacting behavior changes.
 
-This contract does **NOT**:
+## 12. Non-goals
 
-- Define language-specific APIs or SDK ergonomics.
-- Mandate repository-internal file layouts.
-- Declare production rollout status for any repository.
-- Override existing governance process for release, publication, merge, or deployment policy.
-- Introduce schema or export changes by itself.
+This contract does not define:
+- commercial pricing
+- hosted API limits
+- x402 payment rules
+- UI requirements
+- chain-specific deployment requirements
+- package publication status