feat: add framework-neutral execution contract v1

README.md

@@ -2,7 +2,7 @@
 
 **Agent Control Plane (ACP)** is an experimental control-plane kernel for coordinating, constraining, and observing AI-agent/workflow execution.
 
-> **Epistemic status:** Experimental engineering. The repository contains an executable deterministic kernel with policy hooks, cooperative task budgets, and run-scoped provenance. It is not a complete autonomous control plane, security boundary, or production-ready orchestration platform.
+> **Epistemic status:** Experimental engineering. The repository contains an executable deterministic kernel with policy hooks, cooperative task budgets, run-scoped provenance, and an additive versioned framework-neutral execution/trace contract. It is not a complete autonomous control plane, security boundary, proven cross-runtime portability layer, or production-ready orchestration platform.
 
 ## Current implementation
 
@@ -20,9 +20,15 @@ The kernel currently provides:
 - run-scoped provenance events carrying both task ID and run ID;
 - terminal provenance containing reported resource usage;
 - a portable `agent-control-plane.provenance.v1` manifest for the current in-memory run;
-- tests covering successful dispatch, handler failure, cancellation, policy decisions, adversarial/invariant cases, duplicate registration, unknown-capability evidence, provenance binding, exact-limit budget use, atomic overrun handling, and suppressed-exception fail-closure;
+- additive `agent-control-plane.execution.v1` contract types for execution, trace/span, component/runtime/adapter, artifact, and event identity;
+- strict fail-closed validation of required identities, schema version, trace parentage, SHA-256 references, monotonic values, and UTC timestamps;
+- deterministic execution-event serialization with canonical UTC `Z` timestamps and validated round-trip reconstruction;
+- an explicit mapper from legacy `ProvenanceEvent` records into the new execution contract when the caller supplies context absent from legacy provenance;
+- tests covering successful dispatch, handler failure, cancellation, policy decisions, adversarial/invariant cases, duplicate registration, unknown-capability evidence, provenance binding, exact-limit budget use, atomic overrun handling, suppressed-exception fail-closure, execution-contract validation/serialization, round-trip reconstruction, and provenance mapping;
 - GitHub Actions CI for the Python suite.
 
+The legacy provenance manifest and the execution contract are distinct representations. `agent-control-plane.provenance.v1` remains unchanged and process-local. Mapping a legacy event into `agent-control-plane.execution.v1` requires caller-supplied execution/trace/component/monotonic context; ACP does not fabricate missing historical trace or identity data.
+
 The provenance manifest is **an in-memory/exportable execution record**, not durable storage, tamper-evident attestation, or an external audit log. Resource accounting is **cooperative**: handlers or runtime/tool adapters must report usage with `Task.consume(...)`; the kernel does not infer provider token counts, tool usage, elapsed time, or cost automatically.
 
 ## Example
@@ -51,6 +57,38 @@ manifest = plane.provenance_manifest()
 assert manifest["run_id"] == "example-run"
 ```
 
+The versioned execution contract is available from the additive subpackage:
+
+```python
+from agent_control_plane.contract import (
+    ComponentIdentity,
+    ExecutionEvent,
+    ExecutionIdentity,
+    TraceContext,
+)
+
+identity = ExecutionIdentity(execution_id="exec-1", run_id="run-1")
+trace = TraceContext(trace_id="trace-1", span_id="span-1")
+component = ComponentIdentity(
+    component_id="kernel",
+    component_type="kernel",
+    runtime_id="python",
+    adapter_id="native-acp",
+)
+
+event = ExecutionEvent(
+    event_type="task.completed",
+    identity=identity,
+    trace=trace,
+    component=component,
+    task_id="task-1",
+    status="completed",
+    utc_timestamp="2026-09-14T23:00:00Z",
+    monotonic_ns=1,
+)
+assert ExecutionEvent.from_dict(event.to_dict()) == event
+```
+
 Run verification with:
 
 ```bash
@@ -60,25 +98,35 @@ python -m pytest
 
 ## Fail-closed boundaries
 
-The current kernel deliberately rejects or records several ambiguous states:
+The current kernel and contract deliberately reject or record several ambiguous states:
 
 - an empty capability cannot be registered;
 - an already registered capability cannot be silently replaced;
 - a terminal task cannot be redispatched;
 - an unknown capability produces a provenance rejection event and raises `KeyError`;
 - a handler exception becomes a recorded `FAILED` task state;
 - a policy denial is recorded rather than treated as successful execution;
-- an attempted cooperative resource-budget overrun becomes `BUDGET_EXHAUSTED` and cannot be converted into successful completion by catching the budget exception inside the handler.
-
-These properties are local software invariants. They do not establish distributed reliability or system security.
+- an attempted cooperative resource-budget overrun becomes `BUDGET_EXHAUSTED` and cannot be converted into successful completion by catching the budget exception inside the handler;
+- blank required execution/trace/component/artifact identity is rejected;
+- unsupported execution-contract schema versions are rejected;
+- trace span self-parenting is rejected;
+- malformed optional SHA-256 references are rejected;
+- negative or non-integer monotonic values are rejected;
+- naive or non-UTC event timestamps are rejected;
+- legacy provenance cannot be mapped across a mismatched run identity;
+- absent legacy state maps to explicit `unspecified`, never inferred success.
+
+These properties are local software invariants under the tested conditions. They do not establish distributed reliability, system security, governance efficacy, or cross-runtime portability.
 
 ## Not yet implemented / established
 
 Unless added and independently verified later, ACP does **not** currently provide:
 
+- materially different external runtime adapters conforming to `agent-control-plane.execution.v1`;
+- two-runtime portability evidence without core-schema fork;
 - model/provider integrations;
 - automatic provider token/cost/tool-call metering;
-- durable event or budget persistence;
+- durable event, trace, or budget persistence;
 - cryptographic/tamper-evident provenance;
 - distributed execution;
 - authentication or authorization infrastructure;
@@ -96,15 +144,17 @@ Claims in this repository should distinguish:
 
 `DEFINED → IMPLEMENTED → COMPUTED → VERIFIED → ATTESTED → HISTORICAL → HYPOTHESIS → METAPHOR → UNSUPPORTED → DEPRECATED`
 
-A passing unit test establishes only the tested property under that test environment. An exported provenance manifest is not an attestation. Cooperative resource accounting is not proof of externally measured consumption. Cross-repository use does not transfer validation.
+A passing unit test establishes only the tested property under that test environment. An exported provenance manifest is not an attestation. Cooperative resource accounting is not proof of externally measured consumption. ACP-native execution-contract conformance is not proof of cross-runtime portability. Cross-repository use does not transfer validation.
 
 ## Ecosystem relationship
 
-ACP may provide reusable primitives to other `ndrorchestration` projects. `DGAF-Framework`, PDMAL, Orbit-Driftwatch, Sentinel, and other repositories maintain separate evidence and governance boundaries. Integration should be demonstrated through explicit interfaces and tests.
+ACP is the preferred experimental implementation host for a framework-neutral execution contract. DGAF retains governance, authorization, provenance/evidence-discipline, and evidence-state authority. PDMAL is a governed empirical workload/research consumer rather than a prerequisite parent of ACP. Other `ndrorchestration` repositories maintain separate evidence boundaries.
+
+A framework/runtime adapter may populate the ACP execution contract, but adapter readiness, CI success, deployment health, or successful execution cannot self-promote DGAF authorization, PDMAL scientific validity, empirical efficacy, or general portability.
 
 ## Current status
 
-**Experimental / development track — executable kernel with run-scoped provenance, fail-closed dispatch invariants, and cooperative task-budget accounting.**
+**Experimental / development track — executable kernel with run-scoped provenance, fail-closed dispatch invariants, cooperative task-budget accounting, and an ACP-native versioned execution/trace contract with deterministic serialization and validation. Cross-runtime portability remains NOT ESTABLISHED.**
 
 ## Provenance
 

docs/CONTROL_PLANE_KERNEL_SPEC.md

@@ -53,32 +53,79 @@ This is local deterministic routing. It is **not** distributed scheduling, load
 
 Policy evaluation is represented as an explicit allow/deny decision with an optional reason. Policy is intentionally separated from execution so higher-level governance systems can supply policies without coupling them to the kernel.
 
+The current kernel policy hook is a **pre-execution** allow/deny mechanism. The cross-runtime execution contract described below can carry an optional `policy_decision_ref`, but that field only associates an identified decision with an execution event. It does not add in-execution or post-execution policy engines and does not itself establish authorization.
+
 ## Provenance
 
-Each execution transition emits a structured `ProvenanceEvent` containing:
+Each kernel execution transition emits a structured `ProvenanceEvent` containing:
 
 - event type;
 - task identifier;
+- run identifier;
 - capability when applicable;
 - resulting state when applicable;
 - optional failure or usage detail;
 - UTC timestamp.
 
-The event list is currently process-local and non-durable.
+`ControlPlane.provenance_manifest()` continues to export the existing `agent-control-plane.provenance.v1` representation. That manifest remains process-local and non-durable.
+
+## Cross-runtime execution contract
+
+ACP additionally defines a versioned framework-neutral execution/trace contract with schema identity:
+
+`agent-control-plane.execution.v1`
+
+The contract is additive to the existing kernel provenance representation. It currently provides immutable typed records for:
+
+- `ExecutionIdentity` — explicit execution ID, run ID, and schema version;
+- `TraceContext` — trace ID, span ID, and optional parent span ID;
+- `ComponentIdentity` — component, component type, runtime, adapter, and optional source/version identity;
+- `ArtifactRef` — artifact identity/type plus optional URI, version, and SHA-256 reference;
+- `ExecutionEvent` — event type, execution/trace/component context, task/status, UTC timestamp, monotonic ordering value, optional capability/policy reference/artifacts/detail.
+
+Required identity fields fail closed when blank. Unsupported schema versions, span self-parenting, malformed SHA-256 values, negative/non-integer monotonic values, and naive or non-UTC event timestamps are rejected with `ContractValidationError`.
+
+Event timestamps serialize canonically in UTC with a trailing `Z`. Contract serialization is deterministic and `ExecutionEvent.from_dict()` reconstructs serialized events through the same validation paths, so malformed nested data does not bypass validation.
+
+### Legacy provenance mapping
+
+`map_provenance_event(...)` converts an existing `ProvenanceEvent` into an `ExecutionEvent` only when the caller supplies execution, trace, component, and monotonic context that the legacy event does not contain.
+
+The mapper:
+
+- preserves the legacy event type, task ID, capability, state, detail, and UTC timestamp;
+- requires the legacy `run_id` to equal the supplied contract `run_id` and fails closed on mismatch;
+- maps an absent legacy state to the explicit non-success placeholder `unspecified`;
+- does not fabricate trace IDs, component IDs, artifacts, policy decisions, or successful status.
+
+This mapper does not change `agent-control-plane.provenance.v1` and does not imply that historical events contained trace/span data they did not record.
+
+### Current conformance boundary
+
+The present contract tests establish ACP-native schema construction, validation, deterministic serialization, round-trip reconstruction, and legacy-provenance mapping under the tested Python environments.
+
+They do **not** establish cross-runtime portability. No materially different external runtime adapter is implemented in this slice, and there is not yet a two-runtime conformance result using the same core schema without fork.
 
 ## Evidence boundary
 
-The kernel and tests demonstrate local deterministic behavior only. The budget tests establish the cooperative count/cost accounting and fail-closed exhaustion properties exercised by those tests. They do not establish:
+The kernel and tests demonstrate local deterministic behavior only. The budget tests establish the cooperative count/cost accounting and fail-closed exhaustion properties exercised by those tests. The execution-contract tests establish only the ACP-native contract properties exercised by those tests.
+
+They do not establish:
 
+- general cross-runtime portability;
 - production reliability;
 - distributed correctness;
 - security authorization;
+- DGAF authorization or governance effectiveness;
+- PDMAL scientific validity or efficacy;
 - persistence guarantees;
+- durable or tamper-evident provenance;
+- cryptographic attestation or custody independence;
 - hard execution-time enforcement;
 - provider-accurate token/cost metering;
 - retry/checkpoint/delegation correctness;
 - model quality;
 - multi-agent coordination quality;
-- governance effectiveness.
+- superiority to existing orchestration standards or frameworks.
 
-Those claims require separate implementation and empirical validation.
+Those claims require separate implementation and evidence.