Dev

.github/workflows/ci.yml

@@ -75,6 +75,32 @@ jobs:
       - name: Run fuzz session
         run: uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s fuzz
 
+  # Opt-in, non-blocking, runtime-gated container integration tests (RUN-314).
+  # Kept out of the hermetic `verify` graph; the `docker` marker tests self-skip
+  # when no runtime is present, and this whole job never fails the build.
+  integration-docker:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+      - name: Probe for a container runtime
+        id: runtime
+        run: |
+          if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then
+            echo "available=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "available=false" >> "$GITHUB_OUTPUT"
+            echo "No container runtime available; skipping docker integration session."
+          fi
+      - name: Run docker integration session
+        if: steps.runtime.outputs.available == 'true'
+        run: uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s integration_docker
+
   sonar:
     runs-on: ubuntu-latest
     needs: [verify]

.ground-control.yaml

@@ -16,6 +16,11 @@ requirements:
     - GOV-918
     - RUN-311
     - ADR-012
+routing:
+  enabled: true
+  default_provider: claude
+  default_fallback: parent
+  stages: {}
 sonarcloud:
   project_key: Brad-Edwards_aces
   organization: brad-edwards

README.md

@@ -19,6 +19,11 @@ The repository is not a managed cyber range and does not include a production
 backend. Backend contracts, stubs, conformance checks, and examples are present;
 real deployment backends remain separate implementations.
 
+A worked example of ACES SDL driving a concrete range is
+[APTL (Advanced Purple Team Lab)](https://github.com/Brad-Edwards/aptl), a
+separate project that specifies its scenarios as ACES SDL documents and
+realizes the selected topology on a Docker Compose backend.
+
 ## Contents
 
 - [What ACES SDL Describes](#what-aces-sdl-describes)

changelog.d/+readme-aptl-example.added.md

@@ -0,0 +1 @@
+Noted in the README that APTL (Advanced Purple Team Lab) is a worked example of a separate project specifying its scenarios as ACES SDL documents and realizing the selected topology on a concrete Docker Compose backend.

changelog.d/13.security.md

@@ -0,0 +1 @@
+Harden OCI module bundle extraction to fail closed on every supported Python runtime. The resolver now validates the entire tar archive before writing — rejecting path traversal, symlinks, hard links, and special files, and stripping setuid/setgid/sticky bits — instead of relying on `tarfile`'s `filter="data"`, which is unavailable on Python 3.11.0–3.11.3 (the PEP 706 backport landed in 3.11.4) and previously allowed an unsafe extraction path on those supported runtimes.

changelog.d/143.security.md

@@ -0,0 +1 @@
+Port runtime control-plane and SDL module-registry security hardening onto the current package layout.

changelog.d/194.added.md

@@ -0,0 +1,3 @@
+### Added
+- Added first-class RUN-307 shared operational state records/history to runtime snapshots with revision-aware validation.
+- Added semantic diagnostics for malformed shared-state records, access markers, and append-only history violations.

changelog.d/195.added.md

@@ -0,0 +1 @@
+Added RUN-308 participant-runtime contract surfaces for joint action records, time-management contexts, runtime snapshot concurrency validation, and coverage for the concurrency guardrails.

changelog.d/196.added.md

@@ -0,0 +1 @@
+Add a repository-owned reference processor (`aces_processor.reference.run_reference_processor` / `ReferenceProcessor`) that realizes the normative processing model: it carries SDL authoring input through instantiation, compilation, and planning to a portable execution plan and exposes the published processor manifest. Per ADR-008 the processor stops at the execution plan; backend realization stays in the runtime. The backend-conformance live probe now consumes the reference processor instead of inlining the compile/plan chain, and new tests drive its plan through the reference runtime to prove every contract version the processor manifest declares is exercised end to end. (RUN-313)

changelog.d/197.added.md

@@ -0,0 +1 @@
+Add a repository-owned reference emulation backend (`aces_reference_backend`) that implements the four backend protocol roles (Provisioner, Orchestrator, Evaluator, ParticipantRuntime) over a pluggable deployment driver. The default in-process driver is hermetic; an opt-in OCI driver realizes plans against a real container runtime (docker/podman) through fixed-argv subprocess calls with bounded timeouts and no secret/native-id leakage into any portable artifact. The backend publishes identity/capability through the standard `BackendManifest`, registers on the existing `BackendRegistry` descriptor seam as `reference-emulation`, and passes `run_target_conformance` at the `FULL_REMOTE_CONTROL_PLANE` profile. Provenance flows through the SEM-218 apply gate; only portable ACES facts reach snapshots, diagnostics, and conformance reports. A `docker`-marked, runtime-gated integration test and a non-blocking `integration_docker` nox session / CI job exercise real-container realization without touching the hermetic `verify` graph. (RUN-314, ADR-063)

changelog.d/200.added.md

@@ -0,0 +1,5 @@
+### Added
+
+- Made the API-406 participant lifecycle-event, observation-envelope, and
+  shared-state record contracts required by the full remote control-plane
+  backend profile and registered their conformance model validators.

changelog.d/201.added.md

@@ -0,0 +1 @@
+Expose API-407 participant feature-support declarations through backend manifest capability helpers and preserve them in rendered backend-manifest v2 payloads.

changelog.d/202.added.md

@@ -0,0 +1 @@
+Expose API-408 participant status, history, and reference/provenance context retrieval views through the runtime control plane and HTTP API.

changelog.d/203.changed.md

@@ -0,0 +1 @@
+Require API-411 participant outcome reports to carry at least one explicit state relationship in the published contract model and generated schema.

changelog.d/204.changed.md

@@ -0,0 +1 @@
+Added a runtime-snapshot conformance gate requiring participant behavior history to be tied to a compiled participant behavior binding before history is accepted.

changelog.d/233.added.md

@@ -0,0 +1 @@
+Add negative conformance coverage and an invalid fixture for the EXP-707 experiment-capture-spec-v1 contract: a dedicated rejection test exercising the capture-requirement key-equality, window-reference resolution, capture-window time-ordering, and under-specified-window invariants, plus a schema-and-model invalid fixture for a window that declares no start, end, or trigger.

changelog.d/234.added.md

@@ -0,0 +1 @@
+Add negative conformance coverage and invalid fixtures for the EXP-708 experiment-evidence-record-v1 contract: a dedicated rejection test exercising the content-uri-requires-checksum, non-empty source-refs, RFC 3339 captured-at, and redaction-requires-loss-disclosure invariants, plus schema-and-model invalid fixtures for a content URI without a checksum, an empty source-refs list, and a malformed captured-at timestamp. The model and published schema shipped under #88; this change adds the conformance tests of record without changing them.

changelog.d/235.added.md

@@ -0,0 +1 @@
+Add negative conformance coverage and invalid fixtures for the EXP-709 experiment-derived-measure-v1 contract: a dedicated rejection test exercising the reported-requires-value, non-reported-must-not-carry-value, and RFC 3339 generated-at invariants, plus schema-and-model invalid fixtures for a reported measure without a value, a withheld measure carrying a value, and a malformed generated-at timestamp. The model and published schema shipped under #88; this change adds the conformance tests of record without changing them.

changelog.d/238.added.md

@@ -0,0 +1 @@
+Add negative conformance coverage and invalid fixtures for the EXP-720 experiment-run-v1 canonical run provenance contract: a dedicated rejection test exercising the run-traceability claim-grounding and duplicate-reference invariants, the realized-form-disclosure substantive and processor/backend authority invariants, and the required traceability capture-spec surface, plus schema-and-model invalid fixtures for a realized-form disclosure missing a realized target, a backend-realized disclosure carrying a processor realization authority, and a run whose traceability omits capture-spec references. The model and published schema shipped under #89; this change adds the conformance tests of record without changing them.

changelog.d/239.added.md

@@ -0,0 +1 @@
+Add negative conformance coverage and an invalid fixture for the EXP-722 experiment-run-v1 realized-form disclosure contract: a dedicated rejection test exercising the realized-form substantive invariants (a disclosure must name a realized reference or value summary and use the matching processor/backend realization authority) and the run-level invariant that disclosure evidence refs must be listed in the run traceability evidence refs and must be duplicate-free, plus a schema-and-model invalid fixture for a processor-realized disclosure carrying a backend realization authority. The model and published schema shipped under #89; this change adds the conformance tests of record without changing them.

changelog.d/247.added.md

@@ -0,0 +1,3 @@
+### Added
+
+- Published SEM-214 meaning and comparability semantics for API-408 participant context views.

changelog.d/248.added.md

@@ -0,0 +1,3 @@
+### Added
+
+- Published SEM-216 boundary semantics distinguishing runtime-observable state, captured evidence, derived evaluations, analysis outputs, and audience-specific views over the existing contract families. Participant-visible context views drawing on archival `evidence_record` or `derived_measure` source layers must now declare a governed view rule and redaction policy and mediate the source through the transformation, and redacted or withheld evidence records must disclose redaction/loss at the schema boundary.

changelog.d/249.added.md

@@ -0,0 +1 @@
+Added SEM-217 external knowledge binding effect semantics, including a typed classifier for annotation, alignment, refinement, and constraint effects over existing concept-authority and semantic-profile artifacts.

changelog.d/334.added.md

@@ -0,0 +1,3 @@
+### Added
+
+- Published SEM-224 observability plane separation semantics: a carrier-oriented plane classifier (`aces_sdl.observability_plane_semantics`) that assigns each claim-bearing observability/evidence artifact exactly one of the five named planes — scenario-native observability, authored evidence requirement, processor/backend operational observability, captured evidence, and derived analysis — by carrier role rather than by free-form strings such as `log`, `trace`, or `evidence`. The three claim-bearing experiment-core contracts (`experiment-capture-spec-v1`, `experiment-evidence-record-v1`, `experiment-derived-measure-v1`) now publish their plane as a portable `x-aces-plane` schema annotation sourced from that classifier.

changelog.d/335.added.md

@@ -0,0 +1,2 @@
+Added SEM-225 run-level augmentation disclosures to `experiment-run-v1`, with validation for processor/backend authority, environment-visible carriers, participant-visible markings, comparability observer effects, and run-traced evidence provenance.
+Refactored the SEM-225 disclosure validator into focused helper checks so the published contract validation stays maintainable.

changelog.d/336.changed.md

@@ -0,0 +1 @@
+Documented and test-backed DSL-123 scenario-native observability reference coverage.

changelog.d/353.changed.md

@@ -0,0 +1,2 @@
+Document the ACES asset-inventory issue-template fragment and reconcile the
+methodology closeout notes for ACES #353.

changelog.d/77.added.md

@@ -0,0 +1,2 @@
+Added the participant behavior model ADR and formal spec covering ACT-602,
+ACT-603, ACT-606, ACT-607, and ACT-608.

changelog.d/88.added.md

@@ -0,0 +1,2 @@
+Add the experiment evidence and measure contract boundary for EXP-707, EXP-708, EXP-709, and EXP-715. The experiment-core schema family now publishes `experiment-capture-spec-v1`, `experiment-evidence-record-v1`, and `experiment-derived-measure-v1`, with valid/invalid fixtures, semantic invariant annotations, and conformance validators that keep declarative capture intent, raw evidence, and derived measures separate. Backend manifests now support an optional `capabilities.observation` block with governed capture-kind, channel-kind, and sealing-mode vocabularies, and conformance rejects observation claims that lack the published evidence contracts. ADR-064 and the formal experiment-core spec record the boundary; runtime capture, storage, APIs, schedulers, and statistical engines remain out of scope for this contract-only change.
+Refactor the reported-value invariant helper and observation capability gap reporting so SonarCloud quality gates remain clean for the published contract surface.

changelog.d/89.added.md

@@ -0,0 +1 @@
+Extend `experiment-run-v1` as the canonical run provenance record for EXP-710, EXP-720, and EXP-722. Run records now include required traceability links from capture specs to raw evidence, derived measures, and claims, plus realized-form disclosures for processor/backend/operator choices that were not fully authored in the scenario or task. ADR-065 and the formal experiment-core spec document the boundary; generated schemas, fixtures, and contract tests enforce the new provenance surface. Reference de-duplication now also tolerates constrained experiment reference models that omit optional digest, path, or subject fields.

contracts/README.md

@@ -54,11 +54,23 @@ It includes:
 - live runtime/control-plane contracts
 - experiment, evidence, and provenance artifact boundaries
 
-The first published experiment-core contract family includes task, run,
-apparatus-context, and study/collection schemas under
-`contracts/schemas/experiment-core/`. These contracts are archival design
-artifacts for scientific experiment records; they do not add runtime execution,
-storage, or API behavior by themselves.
+The control-plane `participant-context-view-v1` contract includes the SEM-214
+meaning and comparability envelope for derived operational context views:
+participant-local scope, audience scope, observation point, governed source
+layers, transformation rule, evidence/provenance basis, semantic limitations,
+and explicit comparability disclosure.
+
+The published experiment-core contract family includes task, run,
+apparatus-context, study/collection, capture specification, raw evidence record,
+and derived measure schemas under `contracts/schemas/experiment-core/`. These
+contracts are archival design artifacts for scientific experiment records; they
+do not add runtime execution, capture, storage, scheduling, statistical engines,
+or API behavior by themselves.
+
+`experiment-run-v1` is the canonical run provenance record. It carries the
+task/run/apparatus context, result and evidence pointers, traceability links to
+capture specs, evidence records, derived measures, and claims, plus
+realized-form disclosures for underspecified concerns resolved during a run.
 
 Within experiment-core contracts, identifier-bearing collections that require
 uniqueness are object maps keyed by that identifier. This keeps uniqueness

contracts/concept-authority/controlled-vocabularies-v1.json

@@ -609,6 +609,106 @@
         }
       }
     },
+    "observation-capture-kinds": {
+      "title": "Observation Capture Kinds",
+      "description": "Backend-supported evidence capture categories for experiment observation capability declarations.",
+      "kind": "vocabulary",
+      "governed_scopes": [
+        "capabilities.observation.supported_capture_kinds"
+      ],
+      "extension_policy": "governed-extension",
+      "extension_pattern": "^x-[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "terms": {
+        "artifact": {
+          "title": "Artifact",
+          "description": "Backend can collect named artifact references as experiment evidence."
+        },
+        "log": {
+          "title": "Log",
+          "description": "Backend can collect log records as experiment evidence."
+        },
+        "observation": {
+          "title": "Observation",
+          "description": "Backend can collect direct observed facts or annotations as experiment evidence."
+        },
+        "packet-capture": {
+          "title": "Packet Capture",
+          "description": "Backend can collect packet-capture outputs as experiment evidence."
+        },
+        "telemetry": {
+          "title": "Telemetry",
+          "description": "Backend can collect telemetry streams or snapshots as experiment evidence."
+        },
+        "trace": {
+          "title": "Trace",
+          "description": "Backend can collect execution traces as experiment evidence."
+        }
+      }
+    },
+    "observation-channel-kinds": {
+      "title": "Observation Channel Kinds",
+      "description": "Backend-supported source channel categories for experiment observation capability declarations.",
+      "kind": "vocabulary",
+      "governed_scopes": [
+        "capabilities.observation.supported_channel_kinds"
+      ],
+      "extension_policy": "governed-extension",
+      "extension_pattern": "^x-[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "terms": {
+        "backend-log": {
+          "title": "Backend Log",
+          "description": "Backend can capture evidence from backend-owned logs."
+        },
+        "evaluation-history": {
+          "title": "Evaluation History",
+          "description": "Backend can capture evidence from evaluation history surfaces."
+        },
+        "file-artifact": {
+          "title": "File Artifact",
+          "description": "Backend can capture evidence from file-backed artifacts."
+        },
+        "packet-capture": {
+          "title": "Packet Capture",
+          "description": "Backend can capture evidence from packet-capture channels."
+        },
+        "participant-observation": {
+          "title": "Participant Observation",
+          "description": "Backend can capture evidence from participant observation surfaces."
+        },
+        "runtime-snapshot": {
+          "title": "Runtime Snapshot",
+          "description": "Backend can capture evidence from runtime snapshot surfaces."
+        },
+        "workflow-history": {
+          "title": "Workflow History",
+          "description": "Backend can capture evidence from workflow history surfaces."
+        }
+      }
+    },
+    "observation-sealing-modes": {
+      "title": "Observation Sealing Modes",
+      "description": "Backend-supported integrity sealing modes for experiment observation evidence.",
+      "kind": "vocabulary",
+      "governed_scopes": [
+        "capabilities.observation.supported_sealing_modes"
+      ],
+      "extension_policy": "governed-extension",
+      "extension_pattern": "^x-[a-z0-9]+(?:-[a-z0-9]+)*:[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "terms": {
+        "digest": {
+          "title": "Digest",
+          "description": "Backend can bind evidence to a checksum or digest."
+        },
+        "immutable-store": {
+          "title": "Immutable Store",
+          "description": "Backend can store evidence in an append-only or immutable store."
+        },
+        "signed-attestation": {
+          "title": "Signed Attestation",
+          "description": "Backend can attach a signed attestation to evidence collection."
+        }
+      }
+    },
     "participant-runtime-feature-support-levels": {
       "title": "Participant Runtime Feature Support Levels",
       "description": "Closed ADR-054 guarantee-strength scale for per-feature participant runtime support declarations.",

contracts/fixtures/backend-manifest/backend-manifest-v2/invalid/feature-support-duplicate-feature.json

@@ -22,6 +22,8 @@
     "participant-lifecycle-event-v1",
     "participant-observation-envelope-v1",
     "participant-shared-state-record-v1",
+    "participant-joint-action-record-v1",
+    "participant-time-management-context-v1",
     "participant-outcome-report-v1"
   ],
   "compatibility": {

contracts/fixtures/backend-manifest/backend-manifest-v2/invalid/feature-support-missing-disclosure.json

@@ -22,6 +22,8 @@
     "participant-lifecycle-event-v1",
     "participant-observation-envelope-v1",
     "participant-shared-state-record-v1",
+    "participant-joint-action-record-v1",
+    "participant-time-management-context-v1",
     "participant-outcome-report-v1"
   ],
   "compatibility": {

contracts/fixtures/backend-manifest/backend-manifest-v2/invalid/feature-support-unguarded-feature-term.json

@@ -22,6 +22,8 @@
     "participant-lifecycle-event-v1",
     "participant-observation-envelope-v1",
     "participant-shared-state-record-v1",
+    "participant-joint-action-record-v1",
+    "participant-time-management-context-v1",
     "participant-outcome-report-v1"
   ],
   "compatibility": {