feat(base): implement shared simulator-adapter plumbing over published RAES contracts

Objective

Implement the small, reusable mechanics needed by simulator adapters while keeping raes_adapters.base non-authoritative.

Scope

Add typed helpers for runtime-target construction, deterministic logical clocks, seed application/reporting, lifecycle cleanup, projection composition, bounded redaction, and conformance-probe composition.
Consume the published owners in raes_contracts, raes_backend_protocols, raes_conformance, and raes_runtime; do not restate or wrap their models into competing DTOs.
Return RAES diagnostics/results at portable boundaries and keep native exceptions, rejected payloads, tracebacks, argv/environment data, and raw simulator values private.
Provide extension seams for driver-local action, observation, and evaluation projectors without defining simulator concepts.
Test the plumbing with a non-cyber toy driver so CybORG terminology cannot become the shared model.

Acceptance criteria

The public base API is typed, documented for adapter implementers, and usable without any simulator extra.
Seed/clock/lifecycle helpers have deterministic unit tests and explicit limitation reporting.
Redaction tests cover native exceptions, object reprs, rejected inputs, tracebacks, paths, environment values, and tokens.
Conformance helpers call the published RAES runner/profile/fixtures rather than introducing a second authority.
A non-cyber driver test passes through the same plumbing.
The base package defines no semantic model, schema/profile/fixture registry, backend protocol, diagnostic envelope, store, or policy gate.

References

REP-004 — CybORG simulation-backend conformant adapter rae#638 (REP-004)
RAES ADR-069 §4
Repository ADR-002

🛠️ Picked up by /implement - driver codex, branch 14-issue-implementation, 2026-07-30T03:56:39.833Z.

gc workflow phase recorded: preflight (issue #14). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

gc workflow phase recorded: plan (issue #14). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

Implementation plan

Add focused tests first for each acceptance criterion: direct construction of a published RuntimeTarget; explicit deterministic ReferenceTimeRuntime transitions; ordered seed application with applied/unbound/unsupported/failed RAES diagnostics; cleanup admission, dependency ordering, failure hygiene, receipt validation, and limitation preservation; direction-specific generic projection with a neutral queueing toy driver; default-deny redaction against hostile exceptions/reprs, rejected inputs, traceback/path/environment/token material; and a conformance wrapper that delegates to the published runner and returns its exact BackendConformanceReport.
Implement small modules under src/raes_adapters/base/ that compose the public owners in raes_backend_protocols, raes_contracts, raes_runtime, and raes_conformance. Export only typed adapter-facing helpers from raes_adapters.base; define no Pydantic models, schemas, protocols, registries, stores, diagnostic/result envelopes, profile tables, fixtures, simulator discovery, or native dependency.
Keep boundary behavior fail-closed: target and cleanup validation remain RAES-owned; seed controls stay explicitly ordered and report every disposition without implying replay; clock transitions require the caller’s exact event mapping; projection never falls back to native values; cleanup catches native failures without rendering them and validates the published receipt; redaction accepts only exact safe scalar types/grammar and never calls arbitrary str/repr.
Document the public API for adapter implementers in module docstrings and README, retain the architecture-preflight guardrail note and MkDocs navigation, and prove raes_adapters.base remains importable without simulator extras. Documentation coverage classification did not require an additional target, but the issue’s public-API criterion does.
Run focused base tests during TDD, then the canonical verification graph uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verify. This issue has no formal Requirements section, so requirement governance is legitimately requirement-free; the workflow will use its requirement-free gate path.

Whole-repository design check

Security: no env/argv/filesystem/plugin/subprocess/HTTP surface is added. Native exceptions, rejected values, object renderers, paths, environment values, tokens, logs, and tracebacks never enter diagnostics or portable results; RAES closed models remain every portable shape gate.
Maintainability: reuse RuntimeTarget, ReferenceTimeRuntime, Diagnostic, cleanup contracts/admission/receipt validation, and run_target_conformance; no duplicate validator or abstraction hierarchy.
Extensibility: ordered driver-local seed and cleanup callables, explicit clock-event dispatch, and typed action/observation/evaluation projector callables let a future simulator vary native mechanics without changing the shared boundary.
Whole-repo surfaces: preserve the single distribution/lock, base and isolated-extra verification environments, strict mypy/ruff/pytest, clean-install distribution proof, policy graph, MkDocs strict build, and Release Please ownership of version/changelog.

gc_codex_review — cycle 1 of 1 (pre-push) on issue #14 (branch 14-issue-implementation)
Diff mode: inline — the complete diff was supplied in one prompt

Core review

Verdict: ship-with-fixes

The change is shaped correctly around the repository boundary: it composes published RAES models, validators, diagnostics, and runners while keeping simulator-native behavior behind typed driver callables. The principal cross-cutting seam is bounded failure handling, and the helpers avoid creating a competing semantic model, protocol family, or conformance authority. This leaves room for additional simulator adapters without speculative abstraction, but the cleanup executor has one production-reliability defect against its stated attempt-all contract.

Blocking findings (1):

[one-off] Malformed callback results abandon remaining cleanup obligations — src/raes_adapters/base/lifecycle.py:151
The operation invocation is protected, but _checked_result runs afterward and raises immediately when a callback returns the wrong type or an obligation ID that does not match. That prevents later independent eligible obligations from running, contrary to the cleanup contract that every eligible triggered obligation should be attempted. Treat a malformed callback result as that obligation's bounded failure through failure_result, record it, and continue dependency-aware execution; dependent obligations may then be skipped while independent cleanup still runs. Add a behavioral test with a malformed result followed by an independent obligation to pin this failure mode.

Security review

Verdict: ship

This change is shaped correctly: it adds an in-process, simulator-neutral composition layer over published RAES contracts, with validation delegated to RAES at the target, cleanup, projection, diagnostic, and conformance seams. The cross-cutting security concern is containment of native values and exceptions, and the new helpers consistently replace those with bounded, input-free failures or default-deny redaction. It introduces no external request boundary, authentication surface, persistence, subprocess execution, dynamic import, or secret handling, and it preserves the obvious next variation through caller-supplied typed operations and validators without weakening an existing security control.

No blocking findings.

gc_codex_review pre-push cycle 1 of 1 complete for issue #14 on branch '14-issue-implementation'. Posted by the MCP server to enforce the pre-push hard-cap-1 contract (issues #796, #804, #906). Do not edit or delete — used by the next gc_codex_review (uncommitted) invocation to count cycles.

Review decision record — codex cycle 1 (issue #14)

Reviewer: codex
Cycle: 1

Architectural read:

Core reviewer: The change is shaped correctly around the repository boundary: it composes published RAES models, validators, diagnostics, and runners while keeping simulator-native behavior behind typed driver callables. The principal cross-cutting seam is bounded failure handling, and the helpers avoid creating a competing semantic model, protocol family, or conformance authority. This leaves room for additional simulator adapters without speculative abstraction, but the cleanup executor has one production-reliability defect against its stated attempt-all contract.

Security reviewer: This change is shaped correctly: it adds an in-process, simulator-neutral composition layer over published RAES contracts, with validation delegated to RAES at the target, cleanup, projection, diagnostic, and conformance seams. The cross-cutting security concern is containment of native values and exceptions, and the new helpers consistently replace those with bounded, input-free failures or default-deny redaction. It introduces no external request boundary, authentication surface, persistence, subprocess execution, dynamic import, or secret handling, and it preserves the obvious next variation through caller-supplied typed operations and validators without weakening an existing security control.

Blocking findings: 1

Finding 1 — `one-off`

ID: F1
Title: [core] Malformed callback results abandon remaining cleanup obligations
Location: src/raes_adapters/base/lifecycle.py:151
Decision: fix
Rationale: The operation invocation is protected, but _checked_result runs afterward and raises immediately when a callback returns the wrong type or an obligation ID that does not match. That prevents later independent eligible obligations from ru…

gc_test_quality_review cycle 1 of 1 — issue #14

Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch: 14-issue-implementation
Cycle: 1 / 1
Findings: 2

Finding 1 — [critical] `tests/test_base_plumbing.py:662`

Problem: In test_conformance_helper_delegates_to_published_runner, the expected-value dict compares execution_basis against itself: "execution_basis": captured["execution_basis"]. The expected value is derived from the actual captured value, so this key of the assert captured == {...} comparison is a tautology that passes no matter what execution_basis actually was.
Why it matters: If run_conformance_probe stopped forwarding execution_basis correctly (dropped the ExecutionBasis.HERMETIC_LIVE default, passed None, or forwarded the wrong enum member), this test would still pass. conformance.py's docstring explicitly frames this helper as pure wiring that must not silently change RAES's bounded claim, and this is the one place the execution_basis pass-through is supposedly pinned.
Fix: Assert the real expected value instead, e.g. import ExecutionBasis from raes_conformance.realization and write "execution_basis": ExecutionBasis.HERMETIC_LIVE.

Finding 2 — [warning] `tests/test_base_plumbing.py::test_cleanup_uses_capability_admission_dependency_order_and_raes_receipt`

Problem: None of the execute_cleanup tests drive the blocking_dependency -> status="skipped" branch in lifecycle.py (the obligation whose only dependency, prepare, is used across the suite always succeeds via the succeed callback).
Why it matters: Deleting or breaking the dependency-failure-blocks-dependent logic in execute_cleanup (e.g. always running dependents regardless of upstream status) would not fail any current test, despite being the core safety property of dependency-ordered cleanup (don't run "verify" after a failed "reset").
Fix: Add a case where the prepare operation fails/returns a non-succeeded result and assert finish (depends_on ["prepare"]) ends up with status == "skipped" in the receipt.

gc_test_quality_review cycle 1 of 1 complete for issue #14 on branch '14-issue-implementation'. Posted by the MCP server to enforce the gc_test_quality_review hard-cap-1 contract (issue #884 follow-up, default lowered in #906). Do not edit or delete — used by the next gc_test_quality_review invocation to count cycles.

Review decision record — test-quality cycle 1 (issue #14)

Reviewer: test-quality
Cycle: 1

Architectural read:

This is a behavioral test suite for a thin "base plumbing" layer that intentionally owns almost no logic itself — it delegates target construction, clock transitions, cleanup sequencing, and conformance probing to published RAES contracts and an external runtime. The suite's shape matches that: it exercises real collaborators (ReferenceTimeRuntime, DiagnosticModel validators, actual ValueError delegation from RuntimeTarget) rather than mocking framework internals, and it correctly treats the module's two genuinely sensitive behaviors — default-deny redaction and suppression of native exception context/tracebacks on cleanup/projection failure — as first-class test subjects with adversarial "hostile" fixtures. test_base_smoke.py is appropriately minimal for what it claims to be (an import/__all__ smoke check). The one seam that's under-verified is the conformance-probe wrapper: monkeypatching the external run_target_conformance call to check parameter wiring is the right technique for a pure pass-through, but one of its own assertions was accidentally written as a tautology, and the cleanup dependency-order tests never actually exercise the "skip a dependent obligation whose dependency failed" branch. Neither is a shape problem with the change; both are fixable within the existing tests.

Blocking findings: 2

Finding 1 — `one-off`

ID: F1
Title: (no title)
Decision: fix
Rationale: Addressed by next cycle

Finding 2 — `one-off`

ID: F2
Title: (no title)
Decision: fix
Rationale: Addressed by next cycle

Pre-PR base synchronization

Source: refs/remotes/origin/dev at b3a9a5a47715188b792697e4cbff9c27f79a9638
Outcome: already_current
Published feature head: 503a74431f021d572f376889e0d6df639a59916e
Verified tree: 85a36efd6f7d320a9a29f419e2aedf3c461e411c

Pre-PR base synchronization

Source: refs/remotes/origin/dev at b3a9a5a47715188b792697e4cbff9c27f79a9638
Outcome: already_current
Published feature head: c08606001ecd250d0abe1410fcae97bc4703adab
Verified tree: 903f7df85bda30c7da47cbc6e3f3fe4a0b94b175

Pre-PR base synchronization

Source: refs/remotes/origin/dev at b3a9a5a47715188b792697e4cbff9c27f79a9638
Outcome: already_current
Published feature head: c048ee3ada9475963e27e1085558eedccc55c69f
Verified tree: 905b85c6e66d9eb191fea04e5d489d5d17ae43d5

Execution obligation OB-14-SONAR-MONITOR — Opened

Category: workflow
Observed state: SONAR_TOKEN is not set on the Ground Control MCP host.
Impact: The canonical Ground Control monitor cannot produce its successful terminal envelope, so pre-merge readiness cannot be recorded even though the published analysis is clean.
Current obligation: Restore authenticated SonarCloud monitoring for the Ground Control MCP host and rerun the canonical monitor.

Evidence

Ground Control monitor job job-ms71vpv1-e returned sonar_watch_token_missing after CI completed successfully.
Public SonarCloud PR 58 status is OK with zero open issues and zero open hotspots.

Execution obligation OB-14-SONAR-MONITOR — Escalated

Category: workflow
Observed state: SONAR_TOKEN is not set on the Ground Control MCP host.
Impact: The canonical Ground Control monitor cannot produce its successful terminal envelope, so pre-merge readiness cannot be recorded even though the published analysis is clean.
Current obligation: Restore authenticated SonarCloud monitoring for the Ground Control MCP host and rerun the canonical monitor.

Evidence

Ground Control monitor job job-ms71vpv1-e returned sonar_watch_token_missing after CI completed successfully.
Public SonarCloud PR 58 status is OK with zero open issues and zero open hotspots.

Pause class: hard_external_dependency
Decision request: Make SONAR_TOKEN available to the Ground Control MCP host, then ask me to resume issue 14 so I can rerun the canonical monitor and record readiness.

This obligation remains open while the decision is pending.

gc workflow phase recorded: traceability_reconciled (issue #14). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

no in-scope requirements; touched-files audit clean.

Execution obligation OB-14-SONAR-MONITOR — Resolved

Category: workflow
Observed state: The PR is merged and the Phase D monitor does not apply to Phase E.
Impact: The missing MCP-host token affected only the ended pre-merge monitor; Phase E uses the already-published CI and Sonar results.
Current obligation: Restore authenticated SonarCloud monitoring for the Ground Control MCP host and rerun the canonical monitor.

Evidence

PR 58 merged into dev at 2026-07-30T05:17:09Z.
SonarCloud reports quality gate OK, zero open issues, and zero open hotspots for PR 58.
The user explicitly directed that the pre-merge monitor not be rerun after merge.

Disposition: not-applicable
Corrective action: The condition does not apply to Phase E: PR 58 is already merged, while the obligation is specifically to rerun the Phase D pre-merge monitor. The published SonarCloud analysis was independently verified clean.

Verification

GitHub reports PR 58 state MERGED with merge commit 671a303.
SonarCloud PR 58 quality gate is OK with new_violations=0 and new_security_hotspots_reviewed=100.0.

gc workflow phase recorded: traceability_reconciled (issue #14). Posted by the MCP server to enforce ordering between workflow steps (issue #794 MVP-2). Do not edit or delete — used by downstream tools to gate phase prerequisites.

no in-scope requirements; touched-files audit clean.

Final report — issue #14 complete

PR: #58
Plan: #14 (comment)

Outcome

Simulator adapter authors can now reuse typed target, clock, seed, cleanup, projection, redaction, and conformance mechanics without importing a simulator extra or defining competing RAES contracts. Native values and failures remain private at portable boundaries.

Implemented shared simulator-adapter plumbing over published RAES contracts, with neutral tests, architecture guardrails, and documentation. Canonical verification, CI, and the final SonarCloud quality gate passed.

Files changed

Added:

docs/decisions/base-plumbing-guardrails.md
src/raes_adapters/base/clock.py
src/raes_adapters/base/conformance.py
src/raes_adapters/base/lifecycle.py
src/raes_adapters/base/projection.py
src/raes_adapters/base/redaction.py
src/raes_adapters/base/seeding.py
src/raes_adapters/base/targets.py
tests/test_base_plumbing.py

Modified:

README.md
mkdocs.yml
src/raes_adapters/base/__init__.py
tests/test_base_smoke.py

Reviews

codex: The full staged diff was reviewed; malformed cleanup-result handling was fixed and verified. The run proceeded at the configured review cap without an over-cap rerun, as directed.
test-quality: Test gaps in conformance execution-basis forwarding and failed-dependency cleanup skipping were fixed and verified. The run proceeded at the configured review cap without an over-cap rerun, as directed.

Traceability reconciliation

IMPLEMENTS / TESTS / DOCUMENTS added: 0
Links updated: 0
Stale links removed: 0

Requirement-free issue; touched-artifact and orphan-link reconciliation found no links requiring changes.

Status

CI: ✅ green
SonarCloud: ✅ passed
PR ready for user review and merge.

feat(base): implement shared simulator-adapter plumbing over published RAES contracts #14

Description

Objective

Scope

Acceptance criteria

References

Activity

Brad-Edwards commented on Jul 30, 2026

Brad-Edwards commented on Jul 30, 2026

Brad-Edwards commented on Jul 30, 2026

Implementation plan

Whole-repository design check

Brad-Edwards commented on Jul 30, 2026

Core review

Security review

Brad-Edwards commented on Jul 30, 2026

Brad-Edwards commented on Jul 30, 2026

Review decision record — codex cycle 1 (issue #14)

Finding 1 — one-off

Brad-Edwards commented on Jul 30, 2026

gc_test_quality_review cycle 1 of 1 — issue #14

Finding 1 — [critical] tests/test_base_plumbing.py:662

Finding 2 — [warning] tests/test_base_plumbing.py::test_cleanup_uses_capability_admission_dependency_order_and_raes_receipt

Brad-Edwards commented on Jul 30, 2026

Brad-Edwards commented on Jul 30, 2026

Review decision record — test-quality cycle 1 (issue #14)

Finding 1 — one-off

Finding 2 — one-off

Brad-Edwards commented on Jul 30, 2026

Pre-PR base synchronization

Brad-Edwards commented on Jul 30, 2026

Pre-PR base synchronization

Brad-Edwards commented on Jul 30, 2026

Pre-PR base synchronization

Brad-Edwards commented on Jul 30, 2026

Execution obligation OB-14-SONAR-MONITOR — Opened

Evidence

Brad-Edwards commented on Jul 30, 2026

Execution obligation OB-14-SONAR-MONITOR — Escalated

Evidence

Brad-Edwards commented on Jul 30, 2026

Brad-Edwards commented on Jul 30, 2026

Execution obligation OB-14-SONAR-MONITOR — Resolved

Evidence

Verification

Brad-Edwards commented on Jul 30, 2026

Brad-Edwards commented on Jul 30, 2026

Final report — issue #14 complete

Outcome

Files changed

Reviews

Traceability reconciliation

Status

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Finding 1 — `one-off`

Finding 1 — [critical] `tests/test_base_plumbing.py:662`

Finding 2 — [warning] `tests/test_base_plumbing.py::test_cleanup_uses_capability_admission_dependency_order_and_raes_receipt`

Finding 1 — `one-off`

Finding 2 — `one-off`