diff --git a/.github/workflows/broker-execution-bundle.yml b/.github/workflows/broker-execution-bundle.yml new file mode 100644 index 0000000..c5854c8 --- /dev/null +++ b/.github/workflows/broker-execution-bundle.yml @@ -0,0 +1,33 @@ +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" + push: + branches: + - main + 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" + +permissions: + contents: read + +jobs: + validate-broker-execution-bundle: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: Install validation dependency + run: python -m pip install jsonschema + - name: Validate broker execution bundle + run: python scripts/validate_broker_execution_bundle.py diff --git a/docs/integration/README.md b/docs/integration/README.md index 41927d5..01479af 100644 --- a/docs/integration/README.md +++ b/docs/integration/README.md @@ -10,6 +10,7 @@ systems in the SocioProphet stack. | Guide | System | Description | |---|---|---| | [sociosphere.md](sociosphere.md) | `sociosphere` | Running a bundle from a sociosphere workspace; passing upstream artifacts | +| [broker-reasoning-execution-binding.md](broker-reasoning-execution-binding.md) | Broker reasoning | AgentPlane execution and replay binding for broker execution bundles | --- diff --git a/docs/integration/broker-reasoning-execution-binding.md b/docs/integration/broker-reasoning-execution-binding.md new file mode 100644 index 0000000..8222a88 --- /dev/null +++ b/docs/integration/broker-reasoning-execution-binding.md @@ -0,0 +1,49 @@ +# Broker Reasoning Execution Binding + +## Purpose + +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. + +## AgentPlane responsibilities + +AgentPlane should execute: + +- provider-binding validation bundles +- service-offering smoke tests +- blueprint fulfillment tests +- provider adapter conformance tests +- exit-plan simulations +- continuity tests +- `cost_meter` validation jobs +- policy-decision replay jobs +- evidence completeness checks + +## Inputs + +AgentPlane broker execution inputs include: + +- validated broker bundle +- provider binding +- policy decision or exception record +- execution placement constraints +- smoke/continuity/exit test definitions + +## Outputs + +AgentPlane should emit: + +- `ValidationArtifact` +- `PlacementDecision` +- `RunArtifact` +- `ReplayArtifact` +- promotion or reversal evidence where applicable + +## Broker rule + +BrokerPlane coordinates lifecycle. PolicyPlane decides. AgentPlane executes and emits replayable evidence. + +## Design invariant + +AgentPlane must not invent policy authority. It executes only after policy and broker context are supplied. diff --git a/examples/broker-execution-bundle.example.json b/examples/broker-execution-bundle.example.json new file mode 100644 index 0000000..5633659 --- /dev/null +++ b/examples/broker-execution-bundle.example.json @@ -0,0 +1,21 @@ +{ + "bundleId": "bundle-provider-binding-smoke-001", + "purpose": "Smoke-test approved ProviderBinding before production use.", + "providerBindingId": "binding-standard-app-env-public-cloud-001", + "policyDecisionId": "decision-standard-app-env-001", + "executionType": "smoke", + "placementConstraints": [ + "linux-executor", + "network-restricted" + ], + "expectedArtifacts": [ + "ValidationArtifact", + "PlacementDecision", + "RunArtifact", + "ReplayArtifact" + ], + "evidenceRefs": [ + "evidence.standard-environment.v1" + ], + "maxRunSeconds": 600 +} diff --git a/schemas/README.md b/schemas/README.md index 5b15be0..09a7312 100644 --- a/schemas/README.md +++ b/schemas/README.md @@ -12,6 +12,7 @@ All schemas use [JSON Schema Draft 2020-12](https://json-schema.org/specificatio |---|---|---|---| | [`bundle.schema.v0.1.json`](bundle.schema.v0.1.json) | `Bundle` | v0.1 | Bundle manifest schema. Defines the structure of `bundle.json`. | | [`bundle.schema.patch.json`](bundle.schema.patch.json) | patch fragment | — | Staged future fields for agent-runtime bundles (not yet enforced). | +| [`broker-execution-bundle.schema.v0.1.json`](broker-execution-bundle.schema.v0.1.json) | `BrokerExecutionBundle` | v0.1 | Broker validation/smoke/continuity/exit/cost-meter execution bundle contract. | | [`run-artifact.schema.v0.1.json`](run-artifact.schema.v0.1.json) | `RunArtifact` | v0.1 | Evidence record of a completed run. | | [`replay-artifact.schema.v0.1.json`](replay-artifact.schema.v0.1.json) | `ReplayArtifact` | v0.1 | Inputs needed for deterministic replay. | | [`session-artifact.schema.v0.1.json`](session-artifact.schema.v0.1.json) | `SessionArtifact` | v0.1 | Session-level lifecycle record (status, receipt/run/replay refs). | diff --git a/schemas/broker-execution-bundle.schema.v0.1.json b/schemas/broker-execution-bundle.schema.v0.1.json new file mode 100644 index 0000000..ac21c0a --- /dev/null +++ b/schemas/broker-execution-bundle.schema.v0.1.json @@ -0,0 +1,22 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "BrokerExecutionBundle v0.1", + "type": "object", + "additionalProperties": false, + "properties": { + "bundleId": { "type": "string", "minLength": 1 }, + "purpose": { "type": "string", "minLength": 1 }, + "providerBindingId": { "type": "string", "minLength": 1 }, + "policyDecisionId": { "type": "string", "minLength": 1 }, + "executionType": { "type": "string", "enum": ["validation", "smoke", "continuity", "exit", "cost_meter", "evidence_completeness"] }, + "placementConstraints": { "type": "array", "items": { "type": "string" } }, + "expectedArtifacts": { + "type": "array", + "items": { "type": "string", "enum": ["ValidationArtifact", "PlacementDecision", "RunArtifact", "ReplayArtifact"] }, + "minItems": 1 + }, + "evidenceRefs": { "type": "array", "items": { "type": "string" } }, + "maxRunSeconds": { "type": "integer", "minimum": 1 } + }, + "required": ["bundleId", "purpose", "providerBindingId", "policyDecisionId", "executionType", "expectedArtifacts", "maxRunSeconds"] +} diff --git a/scripts/validate_broker_execution_bundle.py b/scripts/validate_broker_execution_bundle.py new file mode 100644 index 0000000..7017c3d --- /dev/null +++ b/scripts/validate_broker_execution_bundle.py @@ -0,0 +1,39 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +from pathlib import Path +import json + +from jsonschema import Draft202012Validator + +ROOT = Path(__file__).resolve().parents[1] +SCHEMA = ROOT / "schemas" / "broker-execution-bundle.schema.v0.1.json" +EXAMPLE = ROOT / "examples" / "broker-execution-bundle.example.json" + + +def load_json(path: Path): + with path.open("r", encoding="utf-8") as handle: + return json.load(handle) + + +def main() -> int: + schema = load_json(SCHEMA) + example = load_json(EXAMPLE) + Draft202012Validator.check_schema(schema) + validator = Draft202012Validator(schema) + errors = sorted( + validator.iter_errors(example), + key=lambda item: (len(item.path), tuple(str(part) for part in item.path)), + ) + if errors: + print("Broker bundle validation did not pass:") + for item in errors: + location = ".".join(str(part) for part in item.path) or "" + print(f" - {location}: {item.message}") + return 1 + print("Broker execution bundle validates against schema.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main())