monarchic-agent-protocol 0.1.15 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4801d875e1da1deb2b027141f245e2ff1f3c325893c5b1c03fd091e680c89652
4
- data.tar.gz: d2cf9a6e1b0dffdef3979f5862f704622dd87aa3c64721c35b746fefc39045c5
3
+ metadata.gz: e70cc011515a1d46f8b369074834a2abc5ee0d30f928636b333d78e1bcbda9af
4
+ data.tar.gz: 39007a55b96bd1273f66c377063c0a3adba90acff4044be335a8dd2dbcbcb041
5
5
  SHA512:
6
- metadata.gz: 25ac118fd8a512b2208c6c096bdbf63eff81fc3addf365b4e8f86606fbb151164185e200185e08249d4b630b22b1dd8c8df8ddc45514b81b8479537c5862ea2d
7
- data.tar.gz: 6ae5a3cc87278132d49bf4ad26a4bb900640a090444b47e63dc1ed41b76e3d1647d0356dce88d177483dfa9b884f7e9a8fa33357e461e1202e144944375746c3
6
+ metadata.gz: 74384051cc3abf842ec9725ce9cc4842a84481c26ddf4247f423d620ec3a5ff87a36d8721525f839745f188d5f4d236596d42055689acc27ccd478bd86b3328e
7
+ data.tar.gz: 408137845db2c3e52def8b77a0c6c33fb80d7da283cd1c44c816f35fd862bff5ed427831873ed7aebe97db6366b2530d2c90848c132e5aad8400c91a224a53e3
data/README.md CHANGED
@@ -32,6 +32,7 @@ Install the published package for your language, then use the generated bindings
32
32
 
33
33
  - Rust: `examples/rust/task.rs`
34
34
  - TypeScript: `examples/ts/task.ts`
35
+ - JSON (non-protobuf): `examples/json/objective_spec.minimal.json`
35
36
  - Protobuf C++: `examples/proto/cpp/task.cpp`
36
37
  - Protobuf Java: `examples/proto/java/TaskExample.java`
37
38
  - Protobuf Kotlin: `examples/proto/kotlin/TaskExample.kt`
@@ -42,11 +43,106 @@ Install the published package for your language, then use the generated bindings
42
43
  - Protobuf Dart: `examples/proto/dart/task.dart`
43
44
  - Protobuf Rust: `examples/proto/rust/task.rs`
44
45
 
46
+ ### Non-protobuf language support
47
+
48
+ For languages that do not use protobuf bindings, exchange protocol objects as JSON and validate payloads against the versioned schemas before handoff.
49
+
50
+ - Canonical JSON example for non-protobuf consumers: `examples/json/objective_spec.minimal.json`
51
+ - Validate a typed payload against a specific schema: `bash scripts/validate-protocol-json.sh schemas/v1/objective_spec.json schemas/fixtures/valid/objective_spec.minimal.json`
52
+ - Validate the canonical non-protobuf JSON example: `bash scripts/validate-protocol-json.sh schemas/v1/objective_spec.json examples/json/objective_spec.minimal.json`
53
+
54
+ Project-state contract fixtures used by the shell verification suite live under `fixtures/project-state/`, not the repo root.
55
+
45
56
  ### Versioning
46
57
 
47
58
  - Protocol versions live under `schemas/v1/`.
48
59
  - Each v1 object requires `version: "v1"`.
49
60
  - New versions must be added under a new directory (e.g. `schemas/v2/`) without changing existing v1 files.
61
+ - The package/crate transition operator runbook lives at
62
+ [`docs/protocol-release-transition-runbook.md`](docs/protocol-release-transition-runbook.md).
63
+
64
+ ### Client boundary contracts
65
+
66
+ The Rust crate also exposes a frozen client-boundary surface under `monarchic_agent_protocol::client_boundary`.
67
+
68
+ Frozen v1 client-boundary types:
69
+
70
+ - `Intent`
71
+ - `Plan`
72
+ - `PlanStep`
73
+ - `ExecutionReceipt`
74
+ - `VerificationReceipt`
75
+ - `PublicationAction`
76
+ - `ModerationDecision`
77
+ - `ReviewDecision`
78
+ - `RerunScope`
79
+ - `BlockedOutcome`
80
+ - `ArtifactDescriptor`
81
+
82
+ Canonical JSON fixtures for these contracts live under `fixtures/client_boundary/v1/`.
83
+ The protocol-owned MAP operation handoff bundle for downstream client snapshots
84
+ also lives there as `map_operation_bundle.v1.json`.
85
+ Legacy runtime compatibility fixtures live under `fixtures/client_boundary/v0/`.
86
+
87
+ ### Durable authority contracts
88
+
89
+ The Rust crate also exposes a frozen durable-authority surface under `monarchic_agent_protocol::durable_authority`.
90
+
91
+ Frozen v1 durable-authority types:
92
+
93
+ - `FencingToken`
94
+ - `Lease`
95
+ - `RunLifecycleState`
96
+ - `StepLifecycleState`
97
+ - `LeaseRejectionReason`
98
+ - `RecoveryEvent`
99
+ - `ManualOverrideRecord`
100
+
101
+ Canonical JSON fixtures for these contracts live under `fixtures/durable_authority/v1/`.
102
+
103
+ ### Service boundary contracts
104
+
105
+ The Rust crate also exposes a frozen service-boundary surface under `monarchic_agent_protocol::service_boundary`.
106
+
107
+ Frozen v1 service-boundary types:
108
+
109
+ - `PrincipalRef`
110
+ - `TenantRef`
111
+ - `AuthContext`
112
+ - `UsageRecord`
113
+ - `AuditExportManifest`
114
+ - `ControlPlaneQueueJob`
115
+ - `ControlPlaneDispatchRequest`
116
+
117
+ The queue job contract uses the explicit wire marker
118
+ `monarchic.control-plane.queue-job.v1` because it is consumed across the API,
119
+ control-plane queue, and worker boundary. Canonical JSON fixtures for
120
+ service-boundary contracts live under `fixtures/service_boundary/v1/`.
121
+ The cross-service protocol ownership boundary is documented in
122
+ [`docs/service-boundary-architecture.md`](docs/service-boundary-architecture.md).
123
+
124
+ ## Lean4 Formalization
125
+
126
+ A Lean4 proof model now lives under `formal/lean/`.
127
+
128
+ It currently formalizes a bounded set of invariants derived from real downstream usage in this workspace:
129
+
130
+ - client-boundary id safety heuristics
131
+ - role normalization aliases
132
+ - verification receipt status consistency
133
+ - terminal lifecycle sink behavior
134
+ - plan dependency grounding
135
+ - protobuf message well-formedness and cross-message integrity
136
+ - protobuf lifecycle transitions and bounded lease control-plane safety
137
+ - protobuf request/report admissibility and fencing-token monotonicity
138
+ - bounded protobuf control-plane trace safety and authority preservation
139
+ - inductive consistency preservation over protobuf control-plane event traces
140
+ - continuous active-authority traces preserve the bound `(run_id, step_id, task_id)` scope
141
+ - active traces exclude competing authorities for the same `(run_id, step_id)` scope
142
+ - a checked protobuf coverage manifest makes the currently formalized subset explicit relative to the full `.proto` surface
143
+ - the schema-side Lean coverage manifest is generated from `schemas/v1/monarchic_agent_protocol.proto` and validated in CI
144
+
145
+ See `docs/lean4-formal-verification.md` for scope and usage.
50
146
 
51
147
  ### Schema summary
52
148
 
@@ -58,9 +154,16 @@ Schema files live under `schemas/v1/`:
58
154
  - `schemas/v1/artifact.json`
59
155
  - `schemas/v1/event.json`
60
156
  - `schemas/v1/gate_result.json`
157
+ - `schemas/v1/failure_class.json`
158
+ - `schemas/v1/plan_status.json`
159
+ - `schemas/v1/failure_detail.json`
160
+ - `schemas/v1/role_provenance.json`
161
+ - `schemas/v1/plan_provenance.json`
162
+ - `schemas/v1/plan_step.json`
163
+ - `schemas/v1/plan.json`
164
+ - `schemas/v1/execution_receipt.json`
61
165
  - `schemas/v1/run_context.json`
62
166
  - `schemas/v1/run_outcome.json`
63
- - `schemas/v1/delivery_contract.json`
64
167
  - `schemas/v1/agent_role.json`
65
168
  - `schemas/v1/dataset_ref.json`
66
169
  - `schemas/v1/experiment_spec.json`
@@ -80,12 +183,69 @@ All schemas allow additional properties for forward compatibility.
80
183
  - `schemas/v1/artifact.json`
81
184
  - `schemas/v1/event.json`
82
185
  - `schemas/v1/gate_result.json`
186
+ - `schemas/v1/failure_class.json`
187
+ - `schemas/v1/plan_status.json`
188
+ - `schemas/v1/failure_detail.json`
189
+ - `schemas/v1/role_provenance.json`
190
+ - `schemas/v1/plan_provenance.json`
191
+ - `schemas/v1/plan_step.json`
192
+ - `schemas/v1/plan.json`
193
+ - `schemas/v1/execution_receipt.json`
83
194
  - `schemas/v1/run_context.json`
84
- - `schemas/v1/run_outcome.json`
195
+ - `schemas/v1/dataset_ref.json`
196
+ - `schemas/v1/experiment_spec.json`
197
+ - `schemas/v1/objective_spec.json`
198
+ - `schemas/v1/eval_result.json`
199
+ - `schemas/v1/provenance.json`
85
200
 
86
201
  `schemas/v1/agent_role.json` is a shared schema used by `task.json`.
87
- `schemas/v1/dataset_ref.json`, `schemas/v1/experiment_spec.json`, `schemas/v1/objective_spec.json`,
88
- `schemas/v1/eval_result.json`, and `schemas/v1/provenance.json` are referenced by top-level schemas.
202
+ `schemas/v1/failure_class.json` is a shared schema used by `event.json` and `gate_result.json`.
203
+
204
+ ### TaskMessage and TaskMessageAck
205
+
206
+ These types define the shared contract for orchestrator-mediated runner
207
+ communication.
208
+
209
+ They are intended for:
210
+
211
+ - durable handoff messages between active tasks
212
+ - clarification requests and responses
213
+ - blocker notices
214
+ - artifact-ready notifications
215
+ - explicit acknowledgement state
216
+
217
+ They are not intended to imply direct peer-to-peer runner transport. The
218
+ protocol defines the message shape, but routing, persistence, and delivery are
219
+ owned by the orchestrator.
220
+
221
+ `TaskMessage` carries:
222
+
223
+ - sender and recipient task ids
224
+ - message kind
225
+ - optional subject/body
226
+ - referenced artifact ids
227
+ - optional reply chaining
228
+ - acknowledgement requirement
229
+
230
+ `TaskMessageAck` records recipient acknowledgement state separately so mailbox
231
+ delivery can remain append-only and auditable.
232
+
233
+ Recommended acknowledgement semantics:
234
+
235
+ - `received`: the recipient has seen the message in its inbox
236
+ - `accepted`: the recipient accepts the request and plans to act on it
237
+ - `rejected`: the recipient explicitly declines or cannot act on it
238
+ - `resolved`: the recipient completed the requested follow-up or supplied the
239
+ final response
240
+
241
+ Recommended routing semantics:
242
+
243
+ - message ids should be unique within one run
244
+ - sender and recipient should be tasks from the same run
245
+ - `reply_to`, when present, should reference an earlier message id from the
246
+ same run log
247
+ - `requires_ack=true` should imply at least one corresponding
248
+ `TaskMessageAck` record from the recipient
89
249
 
90
250
  ### AgentRole
91
251
 
@@ -98,6 +258,7 @@ Enum values:
98
258
  - `reviewer`
99
259
  - `security`
100
260
  - `ops`
261
+ - `publisher`
101
262
 
102
263
  Example:
103
264
 
@@ -107,6 +268,78 @@ Example:
107
268
  }
108
269
  ```
109
270
 
271
+ ### PipelineSpec
272
+
273
+ Represents a planned pipeline before execution.
274
+
275
+ Required fields:
276
+
277
+ - `version`: `"v1"`
278
+ - `pipeline_id`: stable identifier
279
+ - `objective`: human-readable campaign or pipeline objective
280
+ - `project_key`: member/project scope identifier
281
+ - `tasks`: ordered `PipelineTask[]`
282
+
283
+ This is the shared planning shape that bootstrap generation, orchestration
284
+ validation, and UI preview should converge on.
285
+
286
+ Current shared planning fields now include:
287
+
288
+ - `PipelineSpec`
289
+ - `PipelineTask`
290
+ - `TaskDependency`
291
+ - `SkillRef`
292
+ - `RoleDefinition`
293
+ - `ResolvedRoleBundle`
294
+
295
+ These are available in the protobuf and language bindings even where the checked-in
296
+ JSON Schema index has not yet been expanded to cover each planning helper type.
297
+
298
+ ### RoleDefinition and ResolvedRoleBundle
299
+
300
+ These types provide the shared contract between:
301
+
302
+ - role catalogs in `monarchic-agent-roles`
303
+ - orchestration-time validation
304
+ - runner-time execution bundles
305
+
306
+ `RoleDefinition` describes a canonical role, its capabilities, and its declared
307
+ skill requirements. `ResolvedRoleBundle` is the runtime handoff shape that can
308
+ pair a concrete role definition with the resolved skills and rendered template
309
+ path used for one task execution.
310
+
311
+ ### Canonical Pipeline Layout
312
+
313
+ `PipelineSpec` and `PipelineTask` are now the canonical role-aware planning
314
+ layout across the stack.
315
+
316
+ For compatibility, older minimal pipeline files may still only carry:
317
+
318
+ - `pipeline_id`
319
+ - `tasks[].id`
320
+ - `tasks[].task`
321
+
322
+ But once a pipeline opts into the role-aware contract by declaring any of:
323
+
324
+ - `objective`
325
+ - `project_key`
326
+ - `tasks[].role`
327
+ - `tasks[].goal`
328
+ - `tasks[].required_skills`
329
+
330
+ the intended canonical shape is:
331
+
332
+ - `PipelineSpec.objective`: required, non-empty
333
+ - `PipelineSpec.project_key`: required, non-empty
334
+ - `PipelineTask.role`: required, non-empty
335
+ - `PipelineTask.goal`: required, non-empty
336
+ - `PipelineTask.required_skills`: optional list of `SkillRef`, but when present it
337
+ must be internally well-formed and deduplicated
338
+
339
+ This is the contract `monarch` should generate, `monarchic-orchestrator` should
340
+ validate, and `monarchic-runner` should ultimately execute through resolved role
341
+ bundles.
342
+
110
343
  ### Task
111
344
 
112
345
  Represents work assigned to an agent.
@@ -124,7 +357,6 @@ Optional fields:
124
357
  - `constraints`: free-form object
125
358
  - `gates_required`: list of gate names to run (ex: `["qa", "security"]`)
126
359
  - `run_context`: `RunContext`
127
- - `delivery_contract`: typed acceptance and risk contract for autonomous delivery loops
128
360
  - `objective_spec`: objective scoring contract for deterministic outcome evaluation
129
361
  - `experiment_spec`: typed experiment design contract for deterministic in silico runs
130
362
 
@@ -154,19 +386,6 @@ Example:
154
386
  }
155
387
  ```
156
388
 
157
- ### DeliveryContract
158
-
159
- Typed acceptance contract for autonomous delivery execution.
160
-
161
- Required fields:
162
-
163
- - `objective`: plain-language objective statement
164
- - `definition_of_done`: ordered completion checklist
165
- - `required_checks`: required gate/check names for merge readiness
166
- - `risk_tier`: `low | medium | high | critical`
167
-
168
- Optional fields include cycle/turn budgets (`max_cycle_minutes`, `max_agent_turns`) and PR/review/rollback strategy hints.
169
-
170
389
  ### RunContext
171
390
 
172
391
  Execution hints for a runner.
@@ -243,6 +462,7 @@ Optional fields:
243
462
  - `message`: human-readable details
244
463
  - `provenance`: typed runtime/source hashes for event attribution
245
464
  - `eval_results`: optional metric snapshot payloads
465
+ - `failure_class`: typed failure taxonomy payload for machine-actionable triage
246
466
 
247
467
  Example:
248
468
 
@@ -270,6 +490,7 @@ Required fields:
270
490
  Optional fields:
271
491
 
272
492
  - `reason`: short explanation
493
+ - `failure_class`: typed failure taxonomy payload for deterministic failure routing
273
494
  - `evidence`: free-form object with supporting data
274
495
 
275
496
  Example:
@@ -287,21 +508,125 @@ Example:
287
508
  }
288
509
  ```
289
510
 
290
- ### RunOutcome
511
+ ### FailureClass
291
512
 
292
- Typed summary contract for objective/cost/risk decisions captured at the end of a run.
513
+ Typed taxonomy payload for classifying protocol failures.
293
514
 
294
515
  Required fields:
295
516
 
296
- - `version`: `"v1"`
297
- - `task_id`: task identifier
298
- - `objective_decision`: objective decision label
299
- - `cost_decision`: cost decision label
300
- - `risk_decision`: risk decision label
301
- - `final_decision`: aggregate decision label
517
+ - `category`: `validation`, `dependency`, `environment`, `timeout`, `conflict`, `permission`, `resource`, `internal`, or `unknown`
518
+ - `code`: stable machine-readable failure code
519
+ - `retryable`: whether automated retry is expected to be useful
520
+
521
+ Optional fields include `detail`, `scope`, `source`, and `next_action`.
522
+
523
+ ### PlanStatus
524
+
525
+ Plan lifecycle status used for typed execution plans and receipts.
526
+
527
+ Allowed values:
528
+
529
+ - `unspecified`
530
+ - `draft`
531
+ - `planned`
532
+ - `executing`
533
+ - `complete`
534
+ - `bounded`
535
+ - `failed`
536
+ - `cancelled`
537
+ - `unknown`
538
+
539
+ ### FailureDetail
540
+
541
+ Failure detail attached to a plan or receipt.
542
+
543
+ Required fields:
544
+
545
+ - `class`: one of `validation`, `execution`, `agent`, `infra`, `policy`, or `unknown`
546
+ - `code`: machine-readable failure code
547
+ - `message`: operator-readable failure message
548
+
549
+ Optional fields:
550
+
551
+ - `details`: bounded extension object with implementation diagnostics
552
+
553
+ ### RoleProvenance
554
+
555
+ Role metadata for deterministic role-template binding.
556
+
557
+ Required fields:
558
+
559
+ - `role_name`
560
+ - `template_hash`
561
+ - `render_hash`
562
+
563
+ ### PlanProvenance
564
+
565
+ Generation metadata for a plan and policy context.
566
+
567
+ Required fields:
568
+
569
+ - `generated_by`
570
+ - `generated_at_ms`
571
+
572
+ Optional fields:
573
+
574
+ - `policy_profile`
575
+ - `role`
302
576
 
303
- Optional fields include `run_id`, `objective_metric`, `objective_score`, cost budget metrics,
304
- risk detail fields, `summary`, and `evidence`.
577
+ ### PlanStep
578
+
579
+ Execution step in a plan, with dependency and template fields.
580
+
581
+ Required fields:
582
+
583
+ - `step_id`
584
+ - `description`
585
+ - `task_template`
586
+
587
+ Optional fields:
588
+
589
+ - `depends_on`
590
+ - `failure`
591
+
592
+ ### Plan
593
+
594
+ Canonical plan contract.
595
+
596
+ Required fields:
597
+
598
+ - `contract_version`: required contract tag (for now `"v1"`)
599
+ - `plan_id`
600
+ - `objective`
601
+ - `status`
602
+ - `created_at_ms`
603
+ - `updated_at_ms`
604
+ - `provenance`
605
+ - `steps`
606
+
607
+ Optional fields:
608
+
609
+ - `run_id`
610
+
611
+ ### ExecutionReceipt
612
+
613
+ Deterministic execution contract for a run.
614
+
615
+ Required fields:
616
+
617
+ - `contract_version`: required contract tag (for now `"v1"`)
618
+ - `run_id`
619
+ - `plan_id`
620
+ - `plan_hash`
621
+ - `task_hashes`
622
+ - `artifact_hashes`
623
+ - `outcome_hash`
624
+ - `status`
625
+ - `generated_at_ms`
626
+
627
+ Optional fields:
628
+
629
+ - `failure`
305
630
 
306
631
  ### DatasetRef
307
632
 
@@ -367,10 +692,7 @@ Required fields:
367
692
 
368
693
  Optional fields include dataset hashes/references and command/task/pipeline hashes.
369
694
 
370
-
371
- ### Language bindings
372
-
373
- #### Rust
695
+ ## Rust
374
696
 
375
697
  The crate lives at the repo root with sources under `src/rust/lib.rs`.
376
698
 
@@ -381,6 +703,7 @@ let task = Task {
381
703
  version: PROTOCOL_VERSION.to_string(),
382
704
  task_id: "task-123".to_string(),
383
705
  role: AgentRole::Dev as i32,
706
+ role_id: "dev".to_string(),
384
707
  goal: "Implement protocol".to_string(),
385
708
  inputs: None,
386
709
  constraints: None,
@@ -415,7 +738,11 @@ github.com/monarchic-ai/monarchic-agent-protocol/src/go
415
738
 
416
739
  #### Protobuf
417
740
 
418
- The v1 protobuf schema lives at `schemas/v1/monarchic_agent_protocol.proto`. It mirrors the JSON schema and uses `google.protobuf.Struct` for free-form objects (`inputs`, `constraints`, `evidence`, `extensions`). Additional JSON properties should be stored in the `extensions` field on each message.
741
+ The v1 protobuf schema lives at `schemas/v1/monarchic_agent_protocol.proto`. Its portable object messages mirror the JSON schema and use `google.protobuf.Struct` for free-form objects (`inputs`, `constraints`, `evidence`, `extensions`). Additional JSON properties should be stored in the `extensions` field on each message.
742
+
743
+ The protobuf file also contains transport-only service definitions for machine-to-machine control-plane RPC, starting with `RunnerControlService`. Those protobuf-only contracts cover registration, heartbeats, lease acquisition, lease renewal, lease resume, step progress/outcome reporting, and cancellation acknowledgement, and they are not mirrored into the JSON schema index.
744
+
745
+ The Rust crate published from this repository currently exports protobuf message types. Runtime repositories that need gRPC client/server bindings should generate transport stubs from the canonical proto with their chosen toolchain, such as `tonic-build`.
419
746
 
420
747
  Language packages are published per registry. Use the registry package for your language instead of generating local outputs.
421
748
 
@@ -454,11 +781,15 @@ Dart sources live under `src/dart`.
454
781
  - `nix develop` provides Rust, Node, jq, Python `jsonschema`, and `protoc`.
455
782
  - `nix flake check` validates JSON schemas, protobuf codegen, and package imports (PyPI + Rust + npm + Go).
456
783
  - JSON Schema test: `scripts/test-json-schema.sh`.
784
+ - Language-agnostic schema validation helper: `scripts/validate-protocol-json.sh`.
785
+ - Language-agnostic schema validator regression test: `scripts/test-validate-protocol-json.sh`.
457
786
  - Pre-commit schema JSON parse check: `scripts/pre-commit-schema-json-parse.sh`.
458
787
  - Pre-commit schema parse smoke test: `scripts/test-pre-commit-schema-json-parse.sh`.
459
788
  - Schema edit changelog: `schemas/SCHEMA_CHANGELOG.md`.
460
789
  - Schema changelog format test: `scripts/test-schema-changelog-format.sh`.
461
790
  - README schema index coverage test: `scripts/test-readme-schema-index-coverage.sh`.
791
+ - README examples coverage test: `scripts/test-readme-examples-coverage.sh`.
792
+ - README/examples examples synchronization test: `scripts/test-readme-examples-sync.sh`.
462
793
  - Protobuf codegen test (all languages): `scripts/test-proto.sh`.
463
794
  - Protobuf availability smoke test: `scripts/test-proto-availability-smoke.sh`.
464
795
  - Protobuf codegen (write to `src/<lang>`): `scripts/generate-proto.sh`.
@@ -466,28 +797,20 @@ Dart sources live under `src/dart`.
466
797
  - JSON Schema regeneration only: `scripts/generate-json-schema.sh`.
467
798
  - JSON Schema generation requires `protoc-gen-jsonschema` (install with `go install github.com/chrusty/protoc-gen-jsonschema/cmd/protoc-gen-jsonschema@latest`).
468
799
 
469
- Use the Nix apps (preferred) or the scripts directly:
470
-
471
- - `nix run .#generate-proto` (`scripts/generate-proto.sh`): regenerate protobuf outputs into `src/<lang>`.
472
- - `nix run .#generate-json-schema` (`scripts/generate-json-schema.sh`): regenerate JSON Schemas from the protobuf source.
473
- - `nix run .#update-local-hashes` (`scripts/update-local-hashes.sh`): refresh hashes for local build inputs.
474
- - `nix run .#update-version -- <version>` (`scripts/update-version.sh`): bump version across manifests and tags (expects `vX.Y.Z` input).
475
- - `nix run .#update-registry-hashes` (`scripts/update-registry-hashes.sh`): refresh hashes for published registries (npm, crates, PyPI, RubyGems, NuGet, JitPack, GitHub source).
476
-
477
- For every schema change, generate protobuf outputs and update local hashes.
478
-
479
- For every release, tag the commit, update versions, push, and update registry hashes *after pushing*.
480
-
481
800
  ### Schema validation workflow
482
801
 
483
802
  1. Run full schema lint and semantic checks: `bash scripts/lint-schemas.sh`.
484
803
  2. Run direct schema fixture checks: `bash scripts/test-json-schema.sh`.
485
- 3. Validate staged schema JSON before commit: `bash scripts/pre-commit-schema-json-parse.sh`.
486
- 4. Verify pre-commit checker behavior is deterministic: `bash scripts/test-pre-commit-schema-json-parse.sh`.
487
- 5. Verify schema changelog entry format: `bash scripts/test-schema-changelog-format.sh`.
488
- 6. Verify README schema index coverage stays aligned: `bash scripts/test-readme-schema-index-coverage.sh`.
489
-
490
- ### Nix packages
804
+ 3. Validate language-agnostic payloads through JSON schema: `bash scripts/validate-protocol-json.sh schemas/v1/objective_spec.json schemas/fixtures/valid/objective_spec.minimal.json`.
805
+ 4. Verify schema validator behavior is deterministic: `bash scripts/test-validate-protocol-json.sh`.
806
+ 5. Validate staged schema JSON before commit: `bash scripts/pre-commit-schema-json-parse.sh`.
807
+ 6. Verify pre-commit checker behavior is deterministic: `bash scripts/test-pre-commit-schema-json-parse.sh`.
808
+ 7. Verify schema changelog entry format: `bash scripts/test-schema-changelog-format.sh`.
809
+ 8. Verify README schema index coverage stays aligned: `bash scripts/test-readme-schema-index-coverage.sh`.
810
+ 9. Verify README examples coverage for non-protobuf and protobuf paths: `bash scripts/test-readme-examples-coverage.sh`.
811
+ 10. Verify README and examples/README example entries stay synchronized: `bash scripts/test-readme-examples-sync.sh`.
812
+
813
+ ## Nix packages
491
814
 
492
815
  - `packages.default`: Rust crate for protocol types
493
816
  - `packages.rs-lib`: Rust crate for protocol types (local)
@@ -10,6 +10,9 @@
10
10
  "qa",
11
11
  "reviewer",
12
12
  "security",
13
- "ops"
13
+ "ops",
14
+ "publisher",
15
+ "researcher",
16
+ "verification"
14
17
  ]
15
18
  }
@@ -72,6 +72,24 @@
72
72
  "version": {
73
73
  "default": "",
74
74
  "type": "string"
75
+ },
76
+ "provenance": {
77
+ "$ref": "provenance.json"
78
+ },
79
+ "dataset_refs": {
80
+ "type": "array",
81
+ "items": {
82
+ "$ref": "dataset_ref.json"
83
+ }
84
+ },
85
+ "eval_results": {
86
+ "type": "array",
87
+ "items": {
88
+ "$ref": "eval_result.json"
89
+ }
90
+ },
91
+ "experiment_spec": {
92
+ "$ref": "experiment_spec.json"
75
93
  }
76
94
  },
77
95
  "title": "Artifact",
@@ -4,11 +4,7 @@
4
4
  "title": "DatasetRef",
5
5
  "type": "object",
6
6
  "additionalProperties": true,
7
- "required": [
8
- "dataset_id",
9
- "sha256",
10
- "format"
11
- ],
7
+ "required": ["dataset_id", "sha256", "format"],
12
8
  "properties": {
13
9
  "dataset_id": {
14
10
  "type": "string"
@@ -25,14 +21,7 @@
25
21
  },
26
22
  "split": {
27
23
  "type": "string",
28
- "enum": [
29
- "train",
30
- "validation",
31
- "test",
32
- "holdout",
33
- "reference",
34
- "other"
35
- ]
24
+ "enum": ["train", "validation", "test", "holdout", "reference", "other"]
36
25
  },
37
26
  "size_bytes": {
38
27
  "type": "integer",
@@ -4,11 +4,7 @@
4
4
  "title": "EvalResult",
5
5
  "type": "object",
6
6
  "additionalProperties": true,
7
- "required": [
8
- "metric",
9
- "value",
10
- "passed"
11
- ],
7
+ "required": ["metric", "value", "passed"],
12
8
  "properties": {
13
9
  "metric": {
14
10
  "type": "string"