Skip to content

Commit fc5bbd3

Browse files
authored
Update SPEC.md
1 parent 788c122 commit fc5bbd3

1 file changed

Lines changed: 66 additions & 67 deletions

File tree

SPEC.md

Lines changed: 66 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -113,141 +113,140 @@ All requests MUST embed:
113113
"verb": "<verb>",
114114
"version": "1.0.0"
115115
}
116+
```
116117
All receipts MUST embed:
117118

119+
```
118120
jsonc
119121
Copy code
120122
"x402": {
121123
"verb": "<verb>",
122124
"version": "1.0.0",
123125
"status": "ok" | "error"
124126
}
127+
```
128+
125129
No additional properties permitted inside x402.
126130

127-
7. Trace Guarantees
131+
## 7. Trace Guarantees
128132
Every receipt MUST echo:
129133

134+
```
130135
ini
131136
Copy code
132137
trace.requestId = request.trace.requestId
138+
```
139+
133140
This is REQUIRED for chaining & auditability.
134141

135-
Additional trace fields MAY exist (per _shared/trace.schema.json)
142+
Additional trace fields MAY exist (per `_shared/trace.schema.json`)
136143
but MAY NOT weaken determinism or referential integrity.
137144

138-
8. Request Contract
145+
## 8. Request Contract
139146
Requests MUST contain:
140147

141-
Field Required Source of Truth
142-
x402 Yes _shared/x402.schema.json
143-
actor Yes Freeform identifier
144-
trace Yes _shared/trace.schema.json
145-
input Yes Verb-specific
148+
| Field | Required | Source |
149+
| ------- | -------- | --------------------------- |
150+
| `x402` | Yes | `_shared/x402.schema.json` |
151+
| `actor` | Yes | Freeform identifier |
152+
| `trace` | Yes | `_shared/trace.schema.json` |
153+
| `input` | Yes | Verb-specific |
154+
c
146155

147-
Requests MUST validate in strict Ajv mode.
156+
Requests MUST validate in **strict Ajv mode.**
148157

149-
9. Receipt Contract
158+
## 9. Receipt Contract
150159
Receipts MUST contain:
151160

152-
Field Required Conditional
153-
x402 Yes Always
154-
trace Yes Always
155-
status Yes "ok" or "error"
156-
result Yes IF status = ok
157-
error Yes IF status = error
161+
| Field | Required | Conditional |
162+
| -------- | -------- | ------------------- |
163+
| `x402` | Yes | Always |
164+
| `trace` | Yes | Always |
165+
| `status` | Yes | `"ok"` or `"error"` |
166+
| `result` | Yes | IF `status = ok` |
167+
| `error` | Yes | IF `status = error` |
168+
158169

159170
Strict conditional logic is canonical and MUST pass CI validation.
160171

161-
Error receipts MUST NOT include result.
172+
Error receipts MUST NOT include `result.`
162173

163-
10. Versioning + Immutability
164-
Once published under:
174+
## 10. Versioning + Immutability
165175

166-
bash
167-
Copy code
176+
Once published under:
177+
```
168178
schemas/v1.0.0/
169-
There MUST NEVER be:
170-
171-
File content changes
172-
173-
Field requirement changes
179+
```
174180

175-
$id changes
181+
There MUST NEVER be:
176182

177-
Behavior changes
183+
- File content changes
184+
- Field requirement changes
185+
- `$id` changes
186+
- Behavior changes
178187

179188
Any mutation requires:
180189

181-
New version directory (e.g. v1.0.1/)
182-
183-
New CID
184-
185-
Updated checksums + manifest
190+
- New version directory (e.g. v1.0.1/)
191+
- New CID
192+
- Updated checksums + manifest
193+
- ENS TXT update
194+
- Governance approval
186195

187-
ENS TXT update
196+
## 11. Discovery + ENS TXT Responsibilities
188197

189-
Governance approval
190-
191-
11. Discovery + ENS TXT Responsibilities
192198
Protocol-Commons governs ONLY:
193199

194-
pgsql
195-
Copy code
196200
cl.verb
197201
cl.version
198202
cl.schema.request
199203
cl.schema.receipt
200204
cl.cid.schemas
201205
cl.schemas.mirror.ipfs
206+
202207
These MUST be correct or the schema is unauthenticated.
203208

204209
Identity pointers (cl.agentcard, etc.) are NOT in scope here.
205210

206-
12. Conformance Requirements
211+
## 12. Conformance Requirements
207212
Implementations MUST:
208213

209-
1️⃣ Validate requests & receipts in Ajv strict (2020-12)
210-
2️⃣ Support schema resolution from $id URLs
211-
3️⃣ Mirror schema CIDs correctly
212-
4️⃣ Treat version directories as immutable
213-
5️⃣ Respect full trace echo
214+
1. Validate requests & receipts in Ajv strict (2020-12)
215+
2. Support schema resolution from $id URLs
216+
3. Mirror schema CIDs correctly
217+
4. Treat version directories as immutable
218+
5. Respect full trace echo
214219

215220
A system supporting ANY canonical verb MAY claim:
216221

217-
Commons-Compatible
222+
**Commons-Compatible**
218223

219-
13. Failure Modes
220-
If ANY of the following occur:
224+
## 13. Failure Modes
221225

222-
$id mismatch
223-
224-
Incorrect CID root
225-
226-
trace.requestId mismatch
227-
228-
status mismatch
226+
If ANY of the following occur:
229227

230-
Request/receipt schema drift
228+
- `$id` mismatch
229+
- Incorrect CID root
230+
- trace.requestId mismatch
231+
- status mismatch
232+
- Request/receipt schema drift
231233

232234
→ Schema is INVALID
233235
→ Execution MUST be rejected
234236
→ Incident MUST be logged
235237

236-
14. Security
237-
Protocol-Commons is Security-Critical Infrastructure:
238-
239-
No PII
240-
241-
No execution logic
242-
243-
No proprietary references
238+
## 14. Security
239+
Protocol-Commons is **Security-Critical Infrastructure:**
244240

245-
No commercial conditions
241+
- No PII
242+
- No execution logic
243+
- No proprietary references
244+
- No commercial conditions
246245

247246
Security escalation MUST follow repository policy (SECURITY.md).
248247

249-
Status
250-
Stable — v1.0.0 locked
248+
### Status
249+
**Stable — v1.0.0 locked**
251250
CommandLayer Core Standards
252251

253252

0 commit comments

Comments
 (0)