docs: add broker reasoning execution binding and bundle contract#53
Merged
docs: add broker reasoning execution binding and bundle contract#53
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Member
Author
|
Repair status: I added explicit |
There was a problem hiding this comment.
Pull request overview
Adds an AgentPlane “broker reasoning execution binding” document and introduces a concrete “broker execution bundle” contract (schema + example) with CI validation to keep the contract and example in sync.
Changes:
- Add integration documentation describing AgentPlane’s execution/replay responsibilities for broker reasoning.
- Introduce
broker-execution-bundleJSON Schema v0.1 plus a worked example JSON file. - Add a Python validator script and GitHub Actions workflows to validate/compile/verify these assets in CI.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
docs/integration/broker-reasoning-execution-binding.md |
New integration guide describing AgentPlane’s role and expected inputs/outputs. |
schemas/broker-execution-bundle.schema.v0.1.json |
New JSON Schema defining the broker execution bundle contract. |
examples/broker-execution-bundle.example.json |
Example payload intended to validate against the new schema. |
scripts/validate_broker_execution_bundle.py |
Schema/example validator used by CI workflow. |
.github/workflows/broker-execution-bundle.yml |
CI workflow to run the schema/example validator on relevant changes. |
.github/workflows/lint.yml |
New lint workflow for JSON validity + Python compilation (currently misconfigured). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| example = load_json(EXAMPLE) | ||
| Draft202012Validator.check_schema(schema) | ||
| validator = Draft202012Validator(schema) | ||
| errors = sorted(validator.iter_errors(example), key=lambda error: list(error.path)) |
|
|
||
| - name: Compile Python scripts | ||
| run: | | ||
| python3 -m py_compile scripts/validate_meshrush_candidate.py |
Comment on lines
+1
to
+9
| name: broker-execution-bundle | ||
|
|
||
| on: | ||
| pull_request: | ||
| paths: | ||
| - "schemas/broker-execution-bundle.schema.v0.1.json" | ||
| - "examples/broker-execution-bundle.example.json" | ||
| - "scripts/validate_broker_execution_bundle.py" | ||
| - ".github/workflows/broker-execution-bundle.yml" |
Comment on lines
+1
to
+4
| # Broker Reasoning Execution Binding | ||
|
|
||
| ## Purpose | ||
|
|
Comment on lines
+1
to
+4
| { | ||
| "$schema": "https://json-schema.org/draft/2020-12/schema", | ||
| "title": "BrokerExecutionBundle v0.1", | ||
| "type": "object", |
| - provider adapter conformance tests | ||
| - exit-plan simulations | ||
| - continuity tests | ||
| - cost-meter validation jobs |
There was a problem hiding this comment.
Pull request overview
Adds a “broker execution bundle” contract (schema + example + validator + CI workflow) and documents AgentPlane’s role as the governed execution/replay plane for broker reasoning.
Changes:
- Introduces
BrokerExecutionBundleJSON Schema v0.1 plus a matching example and a validation script. - Adds a dedicated GitHub Actions workflow to validate the example against the schema.
- Adds a new integration guide documenting the broker reasoning execution binding (AgentPlane responsibilities, inputs, outputs).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/validate_broker_execution_bundle.py |
Validates the example bundle JSON against the new JSON Schema. |
schemas/broker-execution-bundle.schema.v0.1.json |
Defines the v0.1 BrokerExecutionBundle schema. |
examples/broker-execution-bundle.example.json |
Provides a sample bundle intended to validate against the schema. |
docs/integration/broker-reasoning-execution-binding.md |
Documents AgentPlane’s responsibilities and evidence outputs for broker-related execution. |
.github/workflows/lint.yml |
Adds a new lint workflow (currently contains a failing py_compile target). |
.github/workflows/broker-execution-bundle.yml |
Adds CI validation for the broker execution bundle schema + example. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+5
to
+8
| AgentPlane is the governed execution and replay plane for the cross-cloud services broker model. | ||
|
|
||
| It does not own broker doctrine or policy authorship. It validates, places, runs, and replays broker-related execution bundles and emits evidence artifacts. | ||
|
|
| @@ -0,0 +1,49 @@ | |||
| # Broker Reasoning Execution Binding | |||
Comment on lines
+7
to
+21
| "bundle_id": { "type": "string", "minLength": 1 }, | ||
| "purpose": { "type": "string", "minLength": 1 }, | ||
| "provider_binding_id": { "type": "string", "minLength": 1 }, | ||
| "policy_decision_id": { "type": "string", "minLength": 1 }, | ||
| "execution_type": { "type": "string", "enum": ["validation", "smoke", "continuity", "exit", "cost_meter", "evidence_completeness"] }, | ||
| "placement_constraints": { "type": "array", "items": { "type": "string" } }, | ||
| "expected_artifacts": { | ||
| "type": "array", | ||
| "items": { "type": "string", "enum": ["ValidationArtifact", "PlacementDecision", "RunArtifact", "ReplayArtifact"] }, | ||
| "minItems": 1 | ||
| }, | ||
| "evidence_refs": { "type": "array", "items": { "type": "string" } }, | ||
| "max_run_seconds": { "type": "integer", "minimum": 1 } | ||
| }, | ||
| "required": ["bundle_id", "purpose", "provider_binding_id", "policy_decision_id", "execution_type", "expected_artifacts", "max_run_seconds"] |
Comment on lines
+2
to
+20
| "bundle_id": "bundle-provider-binding-smoke-001", | ||
| "purpose": "Smoke-test approved ProviderBinding before production use.", | ||
| "provider_binding_id": "binding-standard-app-env-public-cloud-001", | ||
| "policy_decision_id": "decision-standard-app-env-001", | ||
| "execution_type": "smoke", | ||
| "placement_constraints": [ | ||
| "linux-executor", | ||
| "network-restricted" | ||
| ], | ||
| "expected_artifacts": [ | ||
| "ValidationArtifact", | ||
| "PlacementDecision", | ||
| "RunArtifact", | ||
| "ReplayArtifact" | ||
| ], | ||
| "evidence_refs": [ | ||
| "evidence.standard-environment.v1" | ||
| ], | ||
| "max_run_seconds": 600 |
Comment on lines
+1
to
+4
| { | ||
| "$schema": "https://json-schema.org/draft/2020-12/schema", | ||
| "title": "BrokerExecutionBundle v0.1", | ||
| "type": "object", |
|
|
||
| - name: Compile Python scripts | ||
| run: | | ||
| python3 -m py_compile scripts/validate_meshrush_candidate.py |
There was a problem hiding this comment.
Pull request overview
This PR introduces a first cut of a “broker execution bundle” contract (schema + example), adds CI validation for it, and documents the intended AgentPlane execution/replay binding for the broker reasoning loop.
Changes:
- Add
BrokerExecutionBundleJSON Schema v0.1 plus a corresponding example bundle JSON. - Add a Python script + GitHub Action workflow to validate the example against the schema using
jsonschema. - Add a new integration doc describing AgentPlane’s responsibilities/inputs/outputs for broker-related execution and evidence.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/validate_broker_execution_bundle.py |
Validates the example bundle JSON against the new schema in CI. |
schemas/broker-execution-bundle.schema.v0.1.json |
Defines the v0.1 JSON Schema contract for broker execution bundles. |
examples/broker-execution-bundle.example.json |
Provides a concrete example expected to validate against the schema. |
docs/integration/broker-reasoning-execution-binding.md |
Documents the AgentPlane execution binding and artifact expectations. |
.github/workflows/lint.yml |
Adds a lint workflow (currently has a broken Python compile target). |
.github/workflows/broker-execution-bundle.yml |
Adds focused CI to validate the schema+example via the new script. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+5
to
+7
| AgentPlane is the governed execution and replay plane for the cross-cloud services broker model. | ||
|
|
||
| It does not own broker doctrine or policy authorship. It validates, places, runs, and replays broker-related execution bundles and emits evidence artifacts. |
Comment on lines
+1
to
+3
| # Broker Reasoning Execution Binding | ||
|
|
||
| ## Purpose |
Comment on lines
+19
to
+21
| - cost-meter validation jobs | ||
| - policy-decision replay jobs | ||
| - evidence completeness checks |
|
|
||
| - name: Compile Python scripts | ||
| run: | | ||
| python3 -m py_compile scripts/validate_meshrush_candidate.py |
mdheller
changed the title
mdheller
force-pushed
the
docs/broker-reasoning-binding
branch
from
a92f690 to
3794ab9
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the AgentPlane execution binding for the cross-cloud services broker reasoning loop and a concrete broker execution bundle contract.
Adds
docs/integration/broker-reasoning-execution-binding.mdschemas/broker-execution-bundle.schema.v0.1.jsonexamples/broker-execution-bundle.example.jsonscripts/validate_broker_execution_bundle.pyScope
AgentPlane executes and emits evidence. It does not own broker doctrine or policy authority.