Repository navigation
feat(cyborg): implement the Provisioner and evidence-backed backend manifest #15
Description
Activity
🛠️ Picked up by /implement - driver codex, branch
15-cyborg-provisioner-manifest, 2026-07-30T23:44:33.168Z.gc workflow phase recorded:
preflight(issue #15). 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.Execution obligation ISSUE-15-CYBORG-ADMISSION-PREREQUISITES — Opened
Category: quality
Observed state: The checked-in CybORG qualification decision is not-admissible, the cyborg optional extra is empty, the required packaging-only patch has no governed published artifact, and the repository has no authoritative admitted CAGE-2 SDL/provisioning-plan fixture.
Impact: The implementation cannot truthfully satisfy issue #15's production acceptance criteria or publish evidence-backed provisioning capabilities. Proceeding with a fake or injected driver alone would create unsupported manifest claims and weaken the repository's fail-closed qualification boundary.
Current obligation: Publish and bind an approved immutable CybORG artifact containing the qualified packaging fix, requalify the selected runtime closure, and provide an issue-approved RAES-valid admitted CAGE-2 plan fixture before implementing and evidencing the Provisioner target.Evidence
- src/raes_adapters/cyborg/qualification.json records admissibility.decision as not-admissible and packaging.patched_wheel.published as false.
- pyproject.toml deliberately defines cyborg = [] pending a governed public artifact.
- docs/decisions/cyborg-cage2-provisioner-manifest-guardrails.md records the architecture preflight disposition and forbids fake-driver evidence from justifying published capabilities.
- Issue feat(cyborg): implement the Provisioner and evidence-backed backend manifest #15 acceptance requires a valid admitted CAGE-2 plan to construct the pinned simulator target and manifest claims to have executable evidence.
Execution obligation ISSUE-15-CYBORG-ADMISSION-PREREQUISITES — Escalated
Category: quality
Observed state: The checked-in CybORG qualification decision is not-admissible, the cyborg optional extra is empty, the required packaging-only patch has no governed published artifact, and the repository has no authoritative admitted CAGE-2 SDL/provisioning-plan fixture.
Impact: The implementation cannot truthfully satisfy issue #15's production acceptance criteria or publish evidence-backed provisioning capabilities. Proceeding with a fake or injected driver alone would create unsupported manifest claims and weaken the repository's fail-closed qualification boundary.
Current obligation: Publish and bind an approved immutable CybORG artifact containing the qualified packaging fix, requalify the selected runtime closure, and provide an issue-approved RAES-valid admitted CAGE-2 plan fixture before implementing and evidencing the Provisioner target.Evidence
- src/raes_adapters/cyborg/qualification.json records admissibility.decision as not-admissible and packaging.patched_wheel.published as false.
- pyproject.toml deliberately defines cyborg = [] pending a governed public artifact.
- docs/decisions/cyborg-cage2-provisioner-manifest-guardrails.md records the architecture preflight disposition and forbids fake-driver evidence from justifying published capabilities.
- Issue feat(cyborg): implement the Provisioner and evidence-backed backend manifest #15 acceptance requires a valid admitted CAGE-2 plan to construct the pinned simulator target and manifest claims to have executable evidence.
Pause class: hard_external_dependency
Decision request: Choose one: provide/authorize the governed artifact publication and approved admitted-plan fixture so issue #15 can resume unchanged, or explicitly narrow issue #15 to a fail-closed mechanical Provisioner seam that does not claim production acceptance or backend capabilities.This obligation remains open while the decision is pending.
gc workflow phase recorded:
plan(issue #15). 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.Corrected implementation plan
Maintainer selection admits the pinned CybORG/CAGE-2 backend. The existing
not-admissiblepackaging decision is not an adapter veto: it records thatraes-adapters[cyborg]cannot currently install the patched backend artifact by itself. Issue #15 will support the documented source-installed CybORG backend and disclose that installation limitation without blocking target construction.-
Correct the authority and documentation
- Amend the preflight guardrail, qualification wording/tests, mapping prose, README, and package comments so they distinguish backend admission from automatic extra installation and strong reproducibility/equivalence claims.
- Keep the selected source commit, Scenario2 bytes, packaging patch, source ledger, and known losses pinned; do not invent RAES schemas, profiles, or backend-specific SDL.
-
Add the CybORG backend target and conservative manifest
- Add backend-local
driver.py,provisioner.py,manifest.py, andtarget.pyunderraes_adapters.cyborg. - Construct a published RAES
RuntimeTargetwhose only component in this issue is the Provisioner; issues feat(cyborg): implement logical step control and action translation #16–18 retain step/action, participant, and evaluation behavior. - Build and validate one published
BackendRealizationEnvelopeModel, deriveProvisionerCapabilitiesfrom it, and render/validatebackend-manifest-v2through RAES APIs. Claims will describe the pinned Scenario2 construction and explicitly disclose descriptor substitution/loss rather than imply arbitrary topology, observation, replay, scoring, or equivalence.
- Add backend-local
-
Implement the backend construction boundary
- Validate closed target configuration, qualification profile, source commit, simulator version, source-ledger selection, realization-envelope identity, plan type/diagnostics, supported plan resources, baseline identity, and bounded seed before native effects.
- Lazily import a user-installed CybORG backend, verify the installed version and selected runtime-file digests, construct pinned Scenario2 in-process, seed it when requested, and keep every native object private.
- Reconcile the admitted RAES provisioning plan into
RuntimeSnapshotentries so users retain the portable scenario descriptor and realization-envelope provenance. The backend-local construction descriptor receives copied admitted plan facts without mutating authored SDL or plan payloads. - Make replacement and deletion atomic under a lock; compensate failed candidates, retain failed cleanup ownership privately, retry cleanup, and make repeated cleanup harmless.
-
TDD and acceptance evidence
- First add failing tests for valid plan construction, manifest-v2 validation, conservative capability claims, invalid config/pins/ledger/version/seed/envelope inputs, failed construction, failed replacement cleanup, partial/repeated cleanup, duplicate/UNCHANGED apply, immutable plan payloads, and hostile native values that must never reach snapshots/results/diagnostics.
- Add a source-installed CybORG smoke through the existing qualification reproducer so the default driver—not only an injected fake—constructs and cleans the pinned backend.
- Map all six issue acceptance criteria to production and test lines before verification.
-
Whole-repository checks
- Security: no new endpoint, subprocess, environment forwarding, dynamic import path, secret lookup, raw native logging, exception rendering, or native persistence; only a fixed lazy
CybORGimport and fixed package resources are used. - Maintainability: reuse
load_qualification,CAGE2_SOURCE_26CE1C1,validate_all,build_runtime_target, RAES plan/snapshot/diagnostic/result/manifest models, and the established libvirt/reference Provisioner patterns. - Extensibility: one backend-local profile/configuration and injected driver seam allows another scenario/source selection later without changing RAES or
raes_adapters.base. - Repository scope: preserve one distribution and one lock; keep the optional extra independent; update public docs and package exports; do not edit
CHANGELOG.md. - Run focused CybORG tests during red/green work, then the canonical
uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verifygraph at completion. Ground Control supplies the issue-bound requirement-free governance context.
- Security: no new endpoint, subprocess, environment forwarding, dynamic import path, secret lookup, raw native logging, exception rendering, or native persistence; only a fixed lazy
-
Execution obligation ISSUE-15-CYBORG-ADMISSION-PREREQUISITES — Resolved
Category: quality
Observed state: The earlier preflight treated automatic package installation and an authored fixture as prerequisites for backend admission, but issue #12 explicitly states that the maintainer-selected simulator/profile are admitted inputs and that packaging gaps weaken claims rather than deciding whether the adapter may exist.
Impact: The false prerequisite paused implementation and inverted the repository's actual authority model. Correcting it allows issue #15 to implement the Provisioner while honestly disclosing weaker installation and equivalence claims.
Current obligation: Proceed with the maintainer-admitted source-installed CybORG backend, retain packaging and equivalence limitations as disclosures, and require executable evidence only for the capabilities actually published.Evidence
- Issue build(cyborg): qualify and pin the supported CAGE-2 runtime profile #12 Qualification semantics: the maintainer-selected simulator and CAGE-2 profile are admitted inputs; packaging gaps and incomplete determinism weaken claims but do not decide whether a CybORG adapter may exist.
- src/raes_adapters/cyborg/qualification.json now records the selected backend as admitted while separately retaining automatic-installation limitations.
- The source-installed qualification reproducer cloned commit 26ce1c1253fa9e2e73f25e6a7f2da32860c11257, applied the recorded packaging patch, built and installed CybORG, and successfully constructed/cleaned it through the RAES adapter.
Disposition: fix
Corrective action: Rewrote the issue #15 guardrails and corrected qualification/mapping documentation to separate backend admission from optional-extra installability; implemented the provisioning-only CybORG target, conservative manifest, source-installed driver, portable snapshot record, and idempotent lifecycle.Verification
- uv run python -m pytest -q: 123 tests passed.
- uv run python tools/verify_cyborg_qualification.py: CybORG qualification OK, including real adapter construction and cleanup.
- uv run ruff check on changed source/tests/tooling passed.
- uv run mypy src passed.
gc_codex_review — cycle 1 of 1 (pre-push) on issue #15 (branch
15-cyborg-provisioner-manifest)
Diff mode: inline — the complete diff was supplied in one promptCore review
Verdict:
ship-with-fixesThe change has the right overall seam: CybORG remains backend-local, native handles stay behind a driver boundary, and the target publishes RAES-owned manifest and snapshot types. The provisioning-only scope is deliberately conservative and does not prematurely claim action or evaluation support. However, the manifest's advertised provisioner constraints are not enforced at the plan-to-driver seam, so the portable record can claim successful application of inputs the selected Scenario2 backend cannot support.
Blocking findings (1):
- [one-off] Reject node capabilities outside the manifest before constructing Scenario2 —
src/raes_adapters/cyborg/provisioner.py:264
_resource_diagnosticsverifies only that a constructing plan containsnetworkandnoderesources. It never checks a node payload'snode_typeandos_familyagainst the manifest capabilities (vm,linux, andwindows). A plan containing, for example, an unsupported node type or OS therefore constructs the fixed Scenario2 backend and returns a successful snapshot with that unsupported descriptor recorded as applied. This contradicts the constrained realization declaration and makes the portability record misleading. Validate the relevant resource payload capabilities against the configured provisioner capabilities before native construction, with a regression test for an incompatible node.
Security review
Verdict:
shipThis change adds a narrowly scoped CybORG provisioning seam: target configuration is closed and validated, the native constructor uses a fixed package surface and fixed Scenario2 path, selected runtime files are integrity-checked before construction, and native handles/errors are kept out of portable RAES results. It touches supply-chain admission and portable-state boundaries, but does not introduce externally supplied paths, commands, deserialization, credentials, or authorization-bearing endpoints. The shape supports the obvious next additions—actions, observations, and evaluation—without exposing native state early.
No blocking findings.
- [one-off] Reject node capabilities outside the manifest before constructing Scenario2 —
7 remaining items
gc_codex_review pre-push cycle 3 (USER-AUTHORIZED OVERRIDE past cap 1) complete for issue #15 on branch '15-cyborg-provisioner-manifest'. 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.
Override reason: user said: "overcap authorized"gc_test_quality_review cycle 1 of 1 — issue #15
Reviewer: test-quality (claude-sonnet-5 via gc_test_quality_review)
Branch:15-cyborg-provisioner-manifest
Cycle: 1 / 1
Findings: 1Finding 1 — [critical]
tests/test_cyborg_provisioner.py::test_driver_uses_generated_document_deletes_it_and_preserves_global_rngProblem: The test seeds Python's global random module to a known baseline (random.seed(1234)) before calling SourceInstalledCyborgDriver.construct(..., seed=19), then only asserts random.getstate() == before afterward. It never observes the global RNG state during construction, so it cannot tell the difference between 'seed 19 was applied to the global random module and then correctly restored' and 'the global random module was never touched at all'.
Why it matters: Deleting theif seed is not None: random.seed(seed)line in SourceInstalledCyborgDriver.construct (driver.py) would leave this test green: with nothing touching the global RNG, getstate() trivially equalsbeforeboth immediately and at the end. That line is what makes CybORG's internal use of Python's global random module reproducible for a given seed — the qualification record explicitly tracks 'cyborg-python-random' as one of only four stochastic sources it controls, and lists 'evaluation-seed-not-bound' as a known upstream defect, so this is exactly the property the adapter exists to guarantee, and it currently has no test coverage of the 'was actually applied' half.
Fix: Inside FakeNative.init (which runs while construct() is still inside the seeded window, before the finally-block restore), capture a value that depends on the current global RNG state, e.g. observed['seeded_sample'] = random.random(). Compare it against an independently computed baseline (random.seed(19); random.random()) to assert the global RNG was actually seeded with 19 before construction, in addition to the existing restoration check.gc_test_quality_review cycle 1 of 1 complete for issue #15 on branch '15-cyborg-provisioner-manifest'. 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_reviewinvocation to count cycles.Review decision record — codex cycle 3 (issue #15)
Reviewer: codex
Cycle: 3
Verdict:ship-with-fixesArchitectural read:
The adapter remains backend-local and projects complete RAES-owned provisioning plans into configurable CybORG scenario documents. Both blocking implementation defects reported in cycle 3 have been corrected without weakening RAES semantics or source admission.
Blocking findings: 2
Finding 1 —
one-off- ID:
cyborg-lifecycle-uncertain-active - Title: Failed replacement cleanup leaves uncertain backend marked healthy
- Location:
src/raes_adapters/cyborg/provisioner.py - Decision: fix
- Rationale: Fixed and verified: failed cleanup marks the active handle unavailable; unchanged apply retries cleanup and reconstructs the complete desired realization before reporting success. Regression coverage verifies reconstruction and conclusive cleanup.
- Comment: feat(cyborg): implement the Provisioner and evidence-backed backend manifest #15 (comment)
Finding 2 —
one-off- ID:
cyborg-source-bytecode-bypass - Title: Verified source can be bypassed with unverified Python bytecode
- Location:
src/raes_adapters/cyborg/driver.py - Decision: fix
- Rationale: Fixed and verified: the driver copies qualified source into a private workspace excluding bytecode/native artifacts, re-verifies it, and imports only that snapshot. A malicious valid cached-bytecode regression proves the verified source executes.
- Comment: feat(cyborg): implement the Provisioner and evidence-backed backend manifest #15 (comment)
Notes (non-blocking, no decisions):
- All listed fixes are present. Canonical verification passed afterward: 137 tests in both lanes, detached real-CybORG qualification, 88% coverage, type/policy/package identity checks, and strict docs.
- ID:
Review decision record — test-quality cycle 1 (issue #15)
Reviewer: test-quality
Cycle: 1
Verdict:ship-with-fixesArchitectural read:
The reproducibility test now observes random state inside native construction, covering both seed application and restoration.
Blocking findings: 1
Finding 1 —
one-off- ID:
cyborg-seed-application-observation - Title: Seed test verifies restoration but not application
- Location:
tests/test_cyborg_provisioner.py - Decision: fix
- Rationale: Fixed and verified: FakeNative samples the global generator during construction and the test compares it with random.Random(19).random(), while retaining restoration verification. Removing seed application now fails.
- Comment: feat(cyborg): implement the Provisioner and evidence-backed backend manifest #15 (comment)
Notes (non-blocking, no decisions):
- The focused provisioner suite and canonical verification graph pass with this regression.
- ID:
Pre-PR base synchronization
- Source:
refs/remotes/origin/devat671a303945998fc284f0af26d7cffdc97546a127 - Outcome:
already_current - Published feature head:
5f769c0f394b475ea57d896cef928566ff3c9493 - Verified tree:
1db7b395c84c9d7811b8b846f43c3c3d28907bd5
- Source:
Pre-PR base synchronization
- Source:
refs/remotes/origin/devat671a303945998fc284f0af26d7cffdc97546a127 - Outcome:
already_current - Published feature head:
0b0041de5efac194e7d97757b3a7c91bc1c3b5c0 - Verified tree:
49370ac282bbb7fecb62d69b071c543f16a09e37
- Source:
Pre-PR base synchronization
- Source:
refs/remotes/origin/devat671a303945998fc284f0af26d7cffdc97546a127 - Outcome:
already_current - Published feature head:
794df48efcc5eb1156b49603fb0bbec2631dd300 - Verified tree:
b291e236cf6e56f6caaf442aa4ce713806893e4a
- Source:
Review decision record — sonarcloud cycle 1 (issue #15)
Reviewer: sonarcloud
Cycle: 1
Verdict:ship-with-fixesArchitectural read:
The strict zero-new-issues profile exposed maintainability debt across the new adapter surface. The implementation was refactored at its natural seams without suppressions or changes to RAES semantics.
Blocking findings: 1
Finding 1 —
class(6 instances)- ID:
sonarcloud-new-code-maintainability - Title: Strict new-code maintainability violations
- Location:
src/raes_adapters/cyborg - Decision: fix
- Rationale: All 53 initial findings and the four residual complexity findings were fixed in code. The final SonarCloud PR analysis reports zero open issues, 86.2% new-code coverage, zero duplication, A ratings for reliability/security/maintainability, and 100% reviewed security hotspots.
- Instances:
document private adapter callablesreplace redundant re-export suppressionsnarrow native-boundary typesuse meaningful published protocols and immutable value carrierssplit lifecycle and exact-shape validation control flowdeduplicate stable diagnostics
Notes (non-blocking, no decisions):
- Final SonarCloud quality gate: passed on PR feat(cyborg): implement RAES scenario projection #59 head 794df48.
- ID:
Ready for review — issue #15
PR: #59
Plan: #15 (comment)Outcome
RAES can now compile and apply supported network and VM desired state through the selected CybORG backend, producing a generated native scenario plus portable realization evidence instead of pinning execution to a fixed CAGE-2 scenario.
Implemented the issue #15 CybORG Provisioner, evidence-bounded backend manifest, target factory, source-verified construction driver, complete-state scenario projection, portable snapshot/diagnostic boundary, and detached real-backend qualification.
In-scope requirements
REP-004(CybORG simulation-backend conformant adapter) — DRAFT — Issue feat(cyborg): implement the Provisioner and evidence-backed backend manifest #15 implements and verifies the provisioning component named by the requirement.
Files changed
Added:
docs/decisions/cyborg-cage2-provisioner-manifest-guardrails.mdsrc/raes_adapters/cyborg/driver.pysrc/raes_adapters/cyborg/manifest.pysrc/raes_adapters/cyborg/provisioner.pysrc/raes_adapters/cyborg/qualification.pysrc/raes_adapters/cyborg/scenario.pysrc/raes_adapters/cyborg/target.pytests/test_cyborg_provisioner.pytools/__init__.py
Modified:
README.mddocs/decisions/cyborg-cage2-runtime-qualification-guardrails.mddocs/decisions/cyborg-cage2-source-ledger-guardrails.mddocs/index.mdmkdocs.ymlpyproject.tomlsrc/raes_adapters/cyborg/__init__.pysrc/raes_adapters/cyborg/mapping/README.mdsrc/raes_adapters/cyborg/mapping/cage2-loss-disclosures.mdsrc/raes_adapters/cyborg/qualification.jsonsrc/raes_adapters/cyborg/source_ledger.pytests/test_cyborg_qualification.pytests/test_cyborg_qualification_driver.pytests/test_cyborg_smoke.pytools/verify_cyborg_qualification.py
Reviews
- codex: Production/security review found uncertain-handle lifecycle recovery and verified-source bytecode bypass defects; both were fixed and covered by regressions before publication.
- test-quality: Review found that seed restoration was tested without observing seed application; the native-construction test now proves both application and restoration.
- sonarcloud: All new-code findings were fixed without suppressions; final gate passed with zero violations, 86.2% new-code coverage, zero duplication, A ratings, and 100% reviewed hotspots.
Traceability reconciliation
- Pending — requirement status transition and IMPLEMENTS/TESTS reconciliation run in Phase E once the PR merges.
Status
- CI: ✅ green
- SonarCloud: ✅ passed
- PR ready for user review and merge. Ground Control reconciliation (requirement status + traceability) runs on merge (Phase E).
Documentation
Updated: see diff.
Phase E requirement classification: REP-004 remains DRAFT. Its statement is conjunctive across Provisioner, Orchestrator, Evaluator, and ParticipantRuntime; merged PR #59 materially delivers and verifies the Provisioner clause but does not satisfy the complete requirement statement. The issue, merged PR, and Provisioner guardrail document are therefore reconciled to REP-004 with DOCUMENTS links rather than an inaccurate IMPLEMENTS claim.
gc workflow phase recorded:
traceability_reconciled(issue #15). 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.- REP-004: status=DRAFT, IMPLEMENTS=0, TESTS=0
Final report — issue #15 complete
PR: #59
Plan: #15 (comment)Outcome
RAES can now compile and apply supported network and VM desired state through the selected CybORG backend, producing a generated native scenario plus portable realization evidence instead of pinning execution to a fixed CAGE-2 scenario.
Merged the issue #15 CybORG Provisioner, evidence-bounded backend manifest, source-verified construction driver, complete-state scenario projection, portable snapshot boundary, and detached real-backend qualification.
In-scope requirements
REP-004(CybORG simulation-backend conformant adapter) — DRAFT — PR feat(cyborg): implement RAES scenario projection #59 materially delivers and verifies the Provisioner clause; the complete conjunctive requirement statement is not materially satisfied.
Files changed
Added:
docs/decisions/cyborg-cage2-provisioner-manifest-guardrails.mdsrc/raes_adapters/cyborg/driver.pysrc/raes_adapters/cyborg/manifest.pysrc/raes_adapters/cyborg/provisioner.pysrc/raes_adapters/cyborg/qualification.pysrc/raes_adapters/cyborg/scenario.pysrc/raes_adapters/cyborg/target.pytests/test_cyborg_provisioner.pytools/__init__.py
Modified:
README.mddocs/decisions/cyborg-cage2-runtime-qualification-guardrails.mddocs/decisions/cyborg-cage2-source-ledger-guardrails.mddocs/index.mdmkdocs.ymlpyproject.tomlsrc/raes_adapters/cyborg/__init__.pysrc/raes_adapters/cyborg/mapping/README.mdsrc/raes_adapters/cyborg/mapping/cage2-loss-disclosures.mdsrc/raes_adapters/cyborg/qualification.jsonsrc/raes_adapters/cyborg/source_ledger.pytests/test_cyborg_qualification.pytests/test_cyborg_qualification_driver.pytests/test_cyborg_smoke.pytools/verify_cyborg_qualification.py
Reviews
- codex: Production/security review found uncertain-handle lifecycle recovery and verified-source bytecode bypass defects; both were fixed and covered by regressions before publication.
- test-quality: Review found that seed restoration was tested without observing seed application; the native-construction test now proves both application and restoration.
- sonarcloud: All new-code findings were fixed without suppressions; final gate passed with zero violations, 86.2% new-code coverage, zero duplication, A ratings, and 100% reviewed hotspots.
Traceability reconciliation
- IMPLEMENTS / TESTS / DOCUMENTS added: 3
- Links updated: 0
- Stale links removed: 0
REP-004 remains DRAFT because its complete conjunctive statement is not materially satisfied by PR #59.
Status
- CI: ✅ green
- SonarCloud: ✅ passed
- PR ready for user review and merge.
Objective
Construct a CybORG RuntimeTarget from admitted RAES plans and publish only capabilities the implementation can prove.
Scope
backend-manifest-v2through the RAES manifest API.Acceptance criteria
Requirements
References