docs: add broker reasoning execution binding and bundle contract

.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

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 |
 
 ---
 

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.

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
+}

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). |

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"]
+}

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 "<root>"
+            print(f" - {location}: {item.message}")
+        return 1
+    print("Broker execution bundle validates against schema.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())