|
| 1 | +# POLICY — Protocol-Commons |
| 2 | +CommandLayer Core Standards · Semantic Layer |
1 | 3 |
|
2 | | -# Protocol-Commons Policy |
| 4 | +This document defines **publication rules** for Common verbs and schemas. |
| 5 | +`SPEC.md` remains the primary normative authority. |
3 | 6 |
|
4 | | -This document defines the canonical rules for creating, validating, versioning, and publishing verb schemas in the CommandLayer Protocol Commons. |
| 7 | +--- |
5 | 8 |
|
6 | | -The Commons is the universal grammar for autonomous agents. |
| 9 | +## 1. Canonical Verb Requirements |
7 | 10 |
|
8 | | ---- |
| 11 | +A canonical verb MUST: |
9 | 12 |
|
10 | | -## 1. Verbs Must Remain Canonical |
| 13 | +- Be a **single lowercase word** |
| 14 | +- Have exactly **one** interpretation |
| 15 | +- Be **domain-neutral** and non-commercial |
| 16 | +- Be approved through governance review PRIOR to publication |
11 | 17 |
|
12 | | -- Single lowercase word |
13 | | -- One meaning; no semantic overload |
14 | | -- Domain-neutral |
15 | | -- Published only after governance review |
| 18 | +Commons verbs SHALL NOT encode: |
16 | 19 |
|
17 | | -Common verbs **SHALL NOT** model: |
18 | | -- Payments |
19 | | -- Contracts / transfers |
20 | | -- Authentication |
21 | | -- Business logic |
| 20 | +- Payments or finance |
| 21 | +- Authentication or identity proofing |
| 22 | +- Business-specific logic |
22 | 23 |
|
23 | | -Those belong in the _Commercial_ layer. |
| 24 | +Those belong to **Commercial** standards. |
24 | 25 |
|
25 | 26 | --- |
26 | 27 |
|
27 | 28 | ## 2. Required Artifacts Per Verb |
28 | 29 |
|
29 | | -Each canonical verb MUST define: |
| 30 | +Each verb MUST include: |
30 | 31 |
|
31 | 32 | - `requests/<verb>.request.schema.json` |
32 | 33 | - `receipts/<verb>.receipt.schema.json` |
| 34 | +- Valid + invalid example sets: |
| 35 | + |
| 36 | +`examples/valid/.json` |
| 37 | +`examples/invalid/.json` |
33 | 38 |
|
34 | | -And MUST ship: |
35 | | -- |
36 | | -- `examples/valid/*.json` |
37 | | -- `examples/invalid/*.json` |
| 39 | +vbnet |
| 40 | +Copy code |
| 41 | +Schematics MUST reference shared primitives under: |
38 | 42 |
|
| 43 | +schemas/v1.0.0/_shared/ |
39 | 44 |
|
40 | 45 | --- |
41 | 46 |
|
42 | 47 | ## 3. JSON Schema Requirements |
43 | 48 |
|
44 | 49 | - Draft **2020-12** |
45 | | -- Ajv **strict mode** |
46 | | -- `"additionalProperties": false` at top level |
47 | | -- Deterministic `$id` and directory structure: |
| 50 | +- Ajv **strict** validation |
| 51 | +- `"additionalProperties": false` |
| 52 | +- Deterministic `$id` structure: |
48 | 53 |
|
49 | | -/schemas/v1.0.0/commons/<verb>/ |
| 54 | +https://commandlayer.org/schemas/v1.0.0/commons/<verb>/requests/<verb>.request.schema.json |
| 55 | +https://commandlayer.org/schemas/v1.0.0/commons/<verb>/receipts/<verb>.receipt.schema.json |
50 | 56 |
|
51 | 57 |
|
| 58 | +Directory layout MUST NOT vary. |
| 59 | + |
52 | 60 | --- |
53 | 61 |
|
54 | | -## 4. x402 Alignment |
| 62 | +## 4. x402 Alignment (Normative) |
| 63 | + |
| 64 | +**All requests MUST define:** |
55 | 65 |
|
56 | | -All requests: |
57 | | -`x402.verb = <verb>` |
58 | | -`x402.version = "1.0.0"` |
| 66 | +- x402.verb = <verb> |
| 67 | +- x402.version = "1.0.0" |
59 | 68 |
|
60 | 69 |
|
61 | | -All receipts: |
| 70 | +**All receipts MUST define:** |
| 71 | + |
62 | 72 | `x402.status = "ok" | "error"` |
63 | 73 |
|
| 74 | +Trace MUST echo `request.trace.requestId`. |
| 75 | + |
64 | 76 | --- |
65 | 77 |
|
66 | 78 | ## 5. Immutability |
67 | 79 |
|
68 | 80 | Once published: |
69 | | -- **No changes** in-place |
70 | | -- Any update requires a new version directory |
71 | | -- New CID + new checksums |
72 | | -- ENS TXT updates |
73 | | - |
74 | | ---- |
75 | | - |
76 | | -## 6. Breaking Change Rules |
77 | 81 |
|
78 | | -### Requires MAJOR version bump: |
79 | | -- Removing fields |
80 | | -- Changing requiredness |
81 | | -- New semantics for success/error |
82 | | -- Trace model changes |
| 82 | +- No modification permitted in-place |
| 83 | +- Breaking change → new major version dir |
| 84 | +- Additive change → minor version dir |
| 85 | +- Example/docs fixes → patch version |
83 | 86 |
|
84 | | -### Requires MINOR: |
85 | | -- Additive `input.*` or `result.*` |
| 87 | +New versions MUST include: |
86 | 88 |
|
87 | | -### PATCH: |
88 | | -- Example or documentation fixes |
| 89 | +- Updated CIDs |
| 90 | +- Updated checksums |
| 91 | +- ENS TXT update where applicable |
89 | 92 |
|
90 | 93 | --- |
91 | 94 |
|
92 | | -## 7. Governance Compliance |
| 95 | +## 6. Governance Compliance |
93 | 96 |
|
94 | 97 | Every change MUST: |
| 98 | + |
95 | 99 | - Have an issue link |
| 100 | +- Pass CI validation |
96 | 101 | - Be recorded in `RESOLUTION.md` |
| 102 | +- Be signed by governance maintainer |
97 | 103 |
|
| 104 | +--- |
98 | 105 |
|
99 | | - |
100 | | - |
101 | | - |
102 | | - |
103 | | - |
104 | | - |
105 | | - |
106 | | - |
| 106 | +_Last updated: v1.0.0 — Stable-Lock_ |
0 commit comments