aios/docs/gitops/SILENT_RELEASE_EXECUTION_READINESS.md

AIOS Silent Release Execution Readiness

Scope and stop point

This change makes the controller execution-ready while deploying only a localhost-bound Shadow control plane. Both production gates remain false:

AIOS_GITOPS_WRITES_ENABLED=false
AIOS_SILENT_RELEASE_EXECUTION_ENABLED=false

Shadow completion is evidence preparation, not a production release. It cannot write a production tag, switch a business runtime, or mutate Baseline/Registry.

Recovery state machine

Every expired or FAILED_RECOVERABLE capability requires fresh, operation-bound probe evidence before another adapter may run:

NOT_APPLIED       -> one new exclusive claim may retry
APPLIED_VERIFIED  -> mark COMPLETED without adapter replay
INDETERMINATE     -> RECONCILIATION_REQUIRED; no automatic writes
CONFLICT          -> MANUAL_OWNER_REVIEW_REQUIRED; no automatic writes

Probe evidence binds the immutable operation digest, is freshness checked, and is appended to a separate SHA-256 hash-chained journal. Completion still requires the active claim ID. File locks and leases ensure that concurrent recovery workers cannot execute the same adapter.

TAG_PENDING uses independent remote ref, annotated object, peeled target, Gitea API, Gitea listing, and repository identity evidence. Exact absence may roll back a switched runtime. Exact publication continues to finalization. Unavailable/divergent evidence stops at reconciliation; a different OID or target stops for Owner review. No branch can force, delete, or rewrite a tag.

Trusted build and approval

Callers submit only an event ID and exact source commit. Test, canary, artifact, manifest, rollback, secret scan, Git and Gitea evidence are generated by the trusted builder. The builder emits an Ed25519 attestation binding:

• builder attestation/key IDs;
• source commit and tree OID;
• artifact, manifest and package-closure SHA-256;
• test and canary evidence SHA-256;
• issuance time and signature.

The controller contains only trusted public keys. Production signing is exposed through a KMS/HSM/secret-manager adapter; a local private-key adapter is marked test-only and is used only for ephemeral Shadow acceptance.

Owner approvals are immutable, time-bounded, revocable, trust-domain bound, and single-use per capability ledger. If the production approval backend reference is absent, production execution is unavailable while Shadow remains available. Caller-supplied owner_id is never a fallback.

Persistent controller and API

aios-silent-release-controller.service runs independently from the business GitOps API. It uses a single leader lock, durable intents/candidates/Sagas, startup journal verification, idempotent main events, one notification record, and recovery reporting. The final deployed service is report-only Shadow mode.

The Action contract exposes:

• createReleaseIntent
• getReleaseCandidate
• getReleasePlan
• getReleaseAcceptance
• submitSignedApproval
• getReleaseSaga
• getCapabilityStatus
• startDeployment
• getRecoveryStatus

Every Shadow response declares execution_enabled=false, shadow_mode=true and side_effects_executed=false. startDeployment returns a simulated SHADOW_COMPLETED result and never claims production capabilities.

Migration and rollback

1. Merge through a governed pull request.
2. Build from a clean detached worktree at the exact merge commit.
3. Verify artifact, manifest, package closure, tests, live fixture, no-.git canary, rollback archive and secret scan.
4. Install a versioned Shadow release without changing the business runtime.
5. Start the separate localhost-only controller with both gates false.
6. Run Shadow candidates and freeze production PID/tag/Baseline/Registry hashes.
7. Remove ephemeral test keys and temporary repositories.

Rollback stops and disables only the Shadow controller and restores/removes its versioned current link. The existing production API, tag set, Baseline and Registry are not involved.

Future activation envelope

Activation requires a new one-time Owner approval binding the exact controller commit, artifact/manifest/policy/unit hashes, trusted key IDs, KMS/secret references, release and rollback roots, authoritative Git/repository identity, Shadow candidate/evidence IDs, test results, activation plan and rollback plan. That approval may only flip AIOS_SILENT_RELEASE_EXECUTION_ENABLED=false to true; each real release still requires its own signed ReleasePlan. This change does not request or consume that activation approval.