# 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:

```text
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:

```text
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.