monarchic-agent-protocol 0.1.14 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54be265210cbcab65e37b2d8647897b7db52655b5263e7d22b8ed7798970405a
-  data.tar.gz: b90c0ca0c139e0d5a96fc3651ab768a868733a93edaeba6f4e2bf3f4a0b04742
+  metadata.gz: e7b63bb50073c69581ec50c46f45c5c8baee323dc3e4c7141bfec77d3e9fb19a
+  data.tar.gz: 9e711e198686fd9e8f36210918b187150af4b06080d259ebb1ce4addb4bbdc43
 SHA512:
-  metadata.gz: 16c6b5fb4c656bb7442c677b39b8c7b291431b6fcd66dfec76ab79d5bdb7b26a21e55e89c2173f54f66dab624bd040bbeff147ea511b3a2e2bd083fc7e212b98
-  data.tar.gz: 6521691c52cc23e60c2a55a318a04c2cb773b771dde5fcdc8da60a943bfd40f7309d9527e3bbdf494fa8d221a182f054c12a93bd2c188d21abacd8f3df7e4447
+  metadata.gz: 5063ed88f2e4159f01801f12301723b6614d5d22ddf22198e56838c551253d47a735175e6e6fa2f4610e85cc2b59f3e481a450bd05a9164a42018ee35bbdc38b
+  data.tar.gz: 75a5b45df12e375dd2a0ca9b3a911f6239582901e097398ee4ff44c40567785cea72505c00623eb8f87959d48d7c4f233c1888acbf4bd514f2dcc3f1397c69e9

data/README.md

@@ -32,6 +32,7 @@ Install the published package for your language, then use the generated bindings
 
 - Rust: `examples/rust/task.rs`
 - TypeScript: `examples/ts/task.ts`
+- JSON (non-protobuf): `examples/json/objective_spec.minimal.json`
 - Protobuf C++: `examples/proto/cpp/task.cpp`
 - Protobuf Java: `examples/proto/java/TaskExample.java`
 - Protobuf Kotlin: `examples/proto/kotlin/TaskExample.kt`
@@ -42,12 +43,56 @@ Install the published package for your language, then use the generated bindings
 - Protobuf Dart: `examples/proto/dart/task.dart`
 - Protobuf Rust: `examples/proto/rust/task.rs`
 
+### Non-protobuf language support
+
+For languages that do not use protobuf bindings, exchange protocol objects as JSON and validate payloads against the versioned schemas before handoff.
+
+- Canonical JSON example for non-protobuf consumers: `examples/json/objective_spec.minimal.json`
+- 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`
+- Validate the canonical non-protobuf JSON example: `bash scripts/validate-protocol-json.sh schemas/v1/objective_spec.json examples/json/objective_spec.minimal.json`
+
+Project-state contract fixtures used by the shell verification suite live under `fixtures/project-state/`, not the repo root.
+
 ### Versioning
 
 - Protocol versions live under `schemas/v1/`.
 - Each v1 object requires `version: "v1"`.
 - New versions must be added under a new directory (e.g. `schemas/v2/`) without changing existing v1 files.
 
+### Client boundary contracts
+
+The Rust crate also exposes a frozen client-boundary surface under `monarchic_agent_protocol::client_boundary`.
+
+Frozen v1 client-boundary types:
+
+- `Intent`
+- `Plan`
+- `PlanStep`
+- `ExecutionReceipt`
+- `VerificationReceipt`
+- `ReviewDecision`
+- `RerunScope`
+- `BlockedOutcome`
+- `ArtifactDescriptor`
+
+Canonical JSON fixtures for these contracts live under `fixtures/client_boundary/v1/`.
+Legacy runtime compatibility fixtures live under `fixtures/client_boundary/v0/`.
+
+### Durable authority contracts
+
+The Rust crate also exposes a frozen durable-authority surface under `monarchic_agent_protocol::durable_authority`.
+
+Frozen v1 durable-authority types:
+
+- `FencingToken`
+- `Lease`
+- `RunLifecycleState`
+- `StepLifecycleState`
+- `LeaseRejectionReason`
+- `RecoveryEvent`
+
+Canonical JSON fixtures for these contracts live under `fixtures/durable_authority/v1/`.
+
 ### Schema summary
 
 JSON Schema files are generated from the protobuf definitions. Do not edit them by hand.
@@ -58,7 +103,16 @@ Schema files live under `schemas/v1/`:
 - `schemas/v1/artifact.json`
 - `schemas/v1/event.json`
 - `schemas/v1/gate_result.json`
+- `schemas/v1/failure_class.json`
+- `schemas/v1/plan_status.json`
+- `schemas/v1/failure_detail.json`
+- `schemas/v1/role_provenance.json`
+- `schemas/v1/plan_provenance.json`
+- `schemas/v1/plan_step.json`
+- `schemas/v1/plan.json`
+- `schemas/v1/execution_receipt.json`
 - `schemas/v1/run_context.json`
+- `schemas/v1/run_outcome.json`
 - `schemas/v1/delivery_contract.json`
 - `schemas/v1/agent_role.json`
 - `schemas/v1/dataset_ref.json`
@@ -79,6 +133,14 @@ All schemas allow additional properties for forward compatibility.
 - `schemas/v1/artifact.json`
 - `schemas/v1/event.json`
 - `schemas/v1/gate_result.json`
+- `schemas/v1/failure_class.json`
+- `schemas/v1/plan_status.json`
+- `schemas/v1/failure_detail.json`
+- `schemas/v1/role_provenance.json`
+- `schemas/v1/plan_provenance.json`
+- `schemas/v1/plan_step.json`
+- `schemas/v1/plan.json`
+- `schemas/v1/execution_receipt.json`
 - `schemas/v1/run_context.json`
 - `schemas/v1/dataset_ref.json`
 - `schemas/v1/experiment_spec.json`
@@ -87,6 +149,53 @@ All schemas allow additional properties for forward compatibility.
 - `schemas/v1/provenance.json`
 
 `schemas/v1/agent_role.json` is a shared schema used by `task.json`.
+`schemas/v1/failure_class.json` is a shared schema used by `event.json` and `gate_result.json`.
+
+### TaskMessage and TaskMessageAck
+
+These types define the shared contract for orchestrator-mediated runner
+communication.
+
+They are intended for:
+
+- durable handoff messages between active tasks
+- clarification requests and responses
+- blocker notices
+- artifact-ready notifications
+- explicit acknowledgement state
+
+They are not intended to imply direct peer-to-peer runner transport. The
+protocol defines the message shape, but routing, persistence, and delivery are
+owned by the orchestrator.
+
+`TaskMessage` carries:
+
+- sender and recipient task ids
+- message kind
+- optional subject/body
+- referenced artifact ids
+- optional reply chaining
+- acknowledgement requirement
+
+`TaskMessageAck` records recipient acknowledgement state separately so mailbox
+delivery can remain append-only and auditable.
+
+Recommended acknowledgement semantics:
+
+- `received`: the recipient has seen the message in its inbox
+- `accepted`: the recipient accepts the request and plans to act on it
+- `rejected`: the recipient explicitly declines or cannot act on it
+- `resolved`: the recipient completed the requested follow-up or supplied the
+  final response
+
+Recommended routing semantics:
+
+- message ids should be unique within one run
+- sender and recipient should be tasks from the same run
+- `reply_to`, when present, should reference an earlier message id from the
+  same run log
+- `requires_ack=true` should imply at least one corresponding
+  `TaskMessageAck` record from the recipient
 
 ### AgentRole
 
@@ -99,6 +208,7 @@ Enum values:
 - `reviewer`
 - `security`
 - `ops`
+- `publisher`
 
 Example:
 
@@ -108,6 +218,78 @@ Example:
 }
 ```
 
+### PipelineSpec
+
+Represents a planned pipeline before execution.
+
+Required fields:
+
+- `version`: `"v1"`
+- `pipeline_id`: stable identifier
+- `objective`: human-readable campaign or pipeline objective
+- `project_key`: member/project scope identifier
+- `tasks`: ordered `PipelineTask[]`
+
+This is the shared planning shape that bootstrap generation, orchestration
+validation, and UI preview should converge on.
+
+Current shared planning fields now include:
+
+- `PipelineSpec`
+- `PipelineTask`
+- `TaskDependency`
+- `SkillRef`
+- `RoleDefinition`
+- `ResolvedRoleBundle`
+
+These are available in the protobuf and language bindings even where the checked-in
+JSON Schema index has not yet been expanded to cover each planning helper type.
+
+### RoleDefinition and ResolvedRoleBundle
+
+These types provide the shared contract between:
+
+- role catalogs in `monarchic-agent-roles`
+- orchestration-time validation
+- runner-time execution bundles
+
+`RoleDefinition` describes a canonical role, its capabilities, and its declared
+skill requirements. `ResolvedRoleBundle` is the runtime handoff shape that can
+pair a concrete role definition with the resolved skills and rendered template
+path used for one task execution.
+
+### Canonical Pipeline Layout
+
+`PipelineSpec` and `PipelineTask` are now the canonical role-aware planning
+layout across the stack.
+
+For compatibility, older minimal pipeline files may still only carry:
+
+- `pipeline_id`
+- `tasks[].id`
+- `tasks[].task`
+
+But once a pipeline opts into the role-aware contract by declaring any of:
+
+- `objective`
+- `project_key`
+- `tasks[].role`
+- `tasks[].goal`
+- `tasks[].required_skills`
+
+the intended canonical shape is:
+
+- `PipelineSpec.objective`: required, non-empty
+- `PipelineSpec.project_key`: required, non-empty
+- `PipelineTask.role`: required, non-empty
+- `PipelineTask.goal`: required, non-empty
+- `PipelineTask.required_skills`: optional list of `SkillRef`, but when present it
+  must be internally well-formed and deduplicated
+
+This is the contract `monarch` should generate, `monarchic-orchestrator` should
+validate, and `monarchic-runner` should ultimately execute through resolved role
+bundles.
+
 ### Task
 
 Represents work assigned to an agent.
@@ -125,7 +307,6 @@ Optional fields:
 - `constraints`: free-form object
 - `gates_required`: list of gate names to run (ex: `["qa", "security"]`)
 - `run_context`: `RunContext`
-- `delivery_contract`: typed acceptance and risk contract for autonomous delivery loops
 - `objective_spec`: objective scoring contract for deterministic outcome evaluation
 - `experiment_spec`: typed experiment design contract for deterministic in silico runs
 
@@ -244,6 +425,7 @@ Optional fields:
 - `message`: human-readable details
 - `provenance`: typed runtime/source hashes for event attribution
 - `eval_results`: optional metric snapshot payloads
+- `failure_class`: typed failure taxonomy payload for machine-actionable triage
 
 Example:
 
@@ -271,6 +453,7 @@ Required fields:
 Optional fields:
 
 - `reason`: short explanation
+- `failure_class`: typed failure taxonomy payload for deterministic failure routing
 - `evidence`: free-form object with supporting data
 
 Example:
@@ -288,6 +471,126 @@ Example:
 }
 ```
 
+### FailureClass
+
+Typed taxonomy payload for classifying protocol failures.
+
+Required fields:
+
+- `category`: `validation`, `dependency`, `environment`, `timeout`, `conflict`, `permission`, `resource`, `internal`, or `unknown`
+- `code`: stable machine-readable failure code
+- `retryable`: whether automated retry is expected to be useful
+
+Optional fields include `detail`, `scope`, `source`, and `next_action`.
+
+### PlanStatus
+
+Plan lifecycle status used for typed execution plans and receipts.
+
+Allowed values:
+
+- `unspecified`
+- `draft`
+- `planned`
+- `executing`
+- `complete`
+- `bounded`
+- `failed`
+- `cancelled`
+- `unknown`
+
+### FailureDetail
+
+Failure detail attached to a plan or receipt.
+
+Required fields:
+
+- `class`: one of `validation`, `execution`, `agent`, `infra`, `policy`, or `unknown`
+- `code`: machine-readable failure code
+- `message`: operator-readable failure message
+
+Optional fields:
+
+- `details`: bounded extension object with implementation diagnostics
+
+### RoleProvenance
+
+Role metadata for deterministic role-template binding.
+
+Required fields:
+
+- `role_name`
+- `template_hash`
+- `render_hash`
+
+### PlanProvenance
+
+Generation metadata for a plan and policy context.
+
+Required fields:
+
+- `generated_by`
+- `generated_at_ms`
+
+Optional fields:
+
+- `policy_profile`
+- `role`
+
+### PlanStep
+
+Execution step in a plan, with dependency and template fields.
+
+Required fields:
+
+- `step_id`
+- `description`
+- `task_template`
+
+Optional fields:
+
+- `depends_on`
+- `failure`
+
+### Plan
+
+Canonical plan contract.
+
+Required fields:
+
+- `contract_version`: required contract tag (for now `"v1"`)
+- `plan_id`
+- `objective`
+- `status`
+- `created_at_ms`
+- `updated_at_ms`
+- `provenance`
+- `steps`
+
+Optional fields:
+
+- `run_id`
+
+### ExecutionReceipt
+
+Deterministic execution contract for a run.
+
+Required fields:
+
+- `contract_version`: required contract tag (for now `"v1"`)
+- `run_id`
+- `plan_id`
+- `plan_hash`
+- `task_hashes`
+- `artifact_hashes`
+- `outcome_hash`
+- `status`
+- `generated_at_ms`
+
+Optional fields:
+
+- `failure`
+
 ### DatasetRef
 
 Reference to a dataset used by an experiment or output artifact.
@@ -352,10 +655,7 @@ Required fields:
 
 Optional fields include dataset hashes/references and command/task/pipeline hashes.
 
-
-### Language bindings
-
-#### Rust
+## Rust
 
 The crate lives at the repo root with sources under `src/rust/lib.rs`.
 
@@ -366,6 +666,7 @@ let task = Task {
     version: PROTOCOL_VERSION.to_string(),
     task_id: "task-123".to_string(),
     role: AgentRole::Dev as i32,
+    role_id: "dev".to_string(),
     goal: "Implement protocol".to_string(),
     inputs: None,
     constraints: None,
@@ -400,7 +701,11 @@ github.com/monarchic-ai/monarchic-agent-protocol/src/go
 
 #### Protobuf
 
-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.
+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.
+
+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.
+
+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`.
 
 Language packages are published per registry. Use the registry package for your language instead of generating local outputs.
 
@@ -439,11 +744,15 @@ Dart sources live under `src/dart`.
 - `nix develop` provides Rust, Node, jq, Python `jsonschema`, and `protoc`.
 - `nix flake check` validates JSON schemas, protobuf codegen, and package imports (PyPI + Rust + npm + Go).
 - JSON Schema test: `scripts/test-json-schema.sh`.
+- Language-agnostic schema validation helper: `scripts/validate-protocol-json.sh`.
+- Language-agnostic schema validator regression test: `scripts/test-validate-protocol-json.sh`.
 - Pre-commit schema JSON parse check: `scripts/pre-commit-schema-json-parse.sh`.
 - Pre-commit schema parse smoke test: `scripts/test-pre-commit-schema-json-parse.sh`.
 - Schema edit changelog: `schemas/SCHEMA_CHANGELOG.md`.
 - Schema changelog format test: `scripts/test-schema-changelog-format.sh`.
 - README schema index coverage test: `scripts/test-readme-schema-index-coverage.sh`.
+- README examples coverage test: `scripts/test-readme-examples-coverage.sh`.
+- README/examples examples synchronization test: `scripts/test-readme-examples-sync.sh`.
 - Protobuf codegen test (all languages): `scripts/test-proto.sh`.
 - Protobuf availability smoke test: `scripts/test-proto-availability-smoke.sh`.
 - Protobuf codegen (write to `src/<lang>`): `scripts/generate-proto.sh`.
@@ -451,28 +760,20 @@ Dart sources live under `src/dart`.
 - JSON Schema regeneration only: `scripts/generate-json-schema.sh`.
 - JSON Schema generation requires `protoc-gen-jsonschema` (install with `go install github.com/chrusty/protoc-gen-jsonschema/cmd/protoc-gen-jsonschema@latest`).
 
-Use the Nix apps (preferred) or the scripts directly:
-
-- `nix run .#generate-proto` (`scripts/generate-proto.sh`): regenerate protobuf outputs into `src/<lang>`.
-- `nix run .#generate-json-schema` (`scripts/generate-json-schema.sh`): regenerate JSON Schemas from the protobuf source.
-- `nix run .#update-local-hashes` (`scripts/update-local-hashes.sh`): refresh hashes for local build inputs.
-- `nix run .#update-version -- <version>` (`scripts/update-version.sh`): bump version across manifests and tags (expects `vX.Y.Z` input).
-- `nix run .#update-registry-hashes` (`scripts/update-registry-hashes.sh`): refresh hashes for published registries (npm, crates, PyPI, RubyGems, NuGet, JitPack, GitHub source).
-
-For every schema change, generate protobuf outputs and update local hashes.
-
-For every release, tag the commit, update versions, push, and update registry hashes *after pushing*.
-
 ### Schema validation workflow
 
 1. Run full schema lint and semantic checks: `bash scripts/lint-schemas.sh`.
 2. Run direct schema fixture checks: `bash scripts/test-json-schema.sh`.
-3. Validate staged schema JSON before commit: `bash scripts/pre-commit-schema-json-parse.sh`.
-4. Verify pre-commit checker behavior is deterministic: `bash scripts/test-pre-commit-schema-json-parse.sh`.
-5. Verify schema changelog entry format: `bash scripts/test-schema-changelog-format.sh`.
-6. Verify README schema index coverage stays aligned: `bash scripts/test-readme-schema-index-coverage.sh`.
-
-### Nix packages
+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`.
+4. Verify schema validator behavior is deterministic: `bash scripts/test-validate-protocol-json.sh`.
+5. Validate staged schema JSON before commit: `bash scripts/pre-commit-schema-json-parse.sh`.
+6. Verify pre-commit checker behavior is deterministic: `bash scripts/test-pre-commit-schema-json-parse.sh`.
+7. Verify schema changelog entry format: `bash scripts/test-schema-changelog-format.sh`.
+8. Verify README schema index coverage stays aligned: `bash scripts/test-readme-schema-index-coverage.sh`.
+9. Verify README examples coverage for non-protobuf and protobuf paths: `bash scripts/test-readme-examples-coverage.sh`.
+10. Verify README and examples/README example entries stay synchronized: `bash scripts/test-readme-examples-sync.sh`.
+
+## Nix packages
 
 - `packages.default`: Rust crate for protocol types
 - `packages.rs-lib`: Rust crate for protocol types (local)

data/schemas/v1/agent_role.json

@@ -10,6 +10,9 @@
     "qa",
     "reviewer",
     "security",
-    "ops"
+    "ops",
+    "publisher",
+    "researcher",
+    "verification"
   ]
 }

data/schemas/v1/artifact.json

@@ -72,6 +72,24 @@
     "version": {
       "default": "",
       "type": "string"
+    },
+    "provenance": {
+      "$ref": "provenance.json"
+    },
+    "dataset_refs": {
+      "type": "array",
+      "items": {
+        "$ref": "dataset_ref.json"
+      }
+    },
+    "eval_results": {
+      "type": "array",
+      "items": {
+        "$ref": "eval_result.json"
+      }
+    },
+    "experiment_spec": {
+      "$ref": "experiment_spec.json"
     }
   },
   "title": "Artifact",

data/schemas/v1/dataset_ref.json

@@ -4,11 +4,7 @@
   "title": "DatasetRef",
   "type": "object",
   "additionalProperties": true,
-  "required": [
-    "dataset_id",
-    "sha256",
-    "format"
-  ],
+  "required": ["dataset_id", "sha256", "format"],
   "properties": {
     "dataset_id": {
       "type": "string"
@@ -25,14 +21,7 @@
     },
     "split": {
       "type": "string",
-      "enum": [
-        "train",
-        "validation",
-        "test",
-        "holdout",
-        "reference",
-        "other"
-      ]
+      "enum": ["train", "validation", "test", "holdout", "reference", "other"]
     },
     "size_bytes": {
       "type": "integer",

data/schemas/v1/eval_result.json

@@ -4,11 +4,7 @@
   "title": "EvalResult",
   "type": "object",
   "additionalProperties": true,
-  "required": [
-    "metric",
-    "value",
-    "passed"
-  ],
+  "required": ["metric", "value", "passed"],
   "properties": {
     "metric": {
       "type": "string"

data/schemas/v1/event.json

@@ -1,60 +1,33 @@
 {
-  "$id": "monarchic.agent_protocol.v1.Event.schema.json",
+  "$id": "https://monarchic.ai/schema/v1/event.json",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Event",
+  "type": "object",
   "additionalProperties": true,
-  "patternProperties": {
-    "^(evalResults)$": {
-      "items": {
-        "$ref": "monarchic.agent_protocol.v1.EvalResult.schema.json"
-      },
-      "type": "array"
-    },
-    "^(eventType)$": {
-      "default": "",
-      "type": "string"
-    },
-    "^(taskId)$": {
-      "default": "",
-      "type": "string"
-    }
-  },
+  "required": ["version", "event_type", "timestamp", "task_id", "status"],
   "properties": {
-    "eval_results": {
-      "items": {
-        "$ref": "monarchic.agent_protocol.v1.EvalResult.schema.json"
-      },
-      "type": "array"
+    "version": {
+      "type": "string",
+      "const": "v1"
     },
     "event_type": {
-      "default": "",
       "type": "string"
     },
-    "extensions": {
-      "$ref": "google.protobuf.Struct.schema.json"
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
     },
-    "message": {
+    "task_id": {
       "type": "string"
     },
-    "provenance": {
-      "$ref": "monarchic.agent_protocol.v1.Provenance.schema.json"
-    },
     "status": {
-      "default": "",
       "type": "string"
     },
-    "task_id": {
-      "default": "",
-      "type": "string"
-    },
-    "timestamp": {
-      "default": "",
+    "message": {
       "type": "string"
     },
-    "version": {
-      "default": "",
-      "type": "string"
+    "failure_class": {
+      "$ref": "failure_class.json"
     }
-  },
-  "title": "Event",
-  "type": "object"
+  }
 }