# Governed Mutation and Promotion v0.1

`witnora.agent_mutation.v0.1` records how an assured agent changes without
treating a new version as an automatic continuation of the old assurance
decision. A mutation invalidates `CURRENT` before promotion begins.

## Protocol

1. The customer submits a `witnora.evolution_manifest.v0.1` containing the
   parent and candidate artifact digests, code/prompt/model/tool changes, data
   sources, build provenance, requested capabilities, and deployment target.
2. Witnora binds the parent to the currently assured scope and computes a
   `witnora.permission_inheritance_diff.v0.1`.
3. Existing capabilities may be inherited. Every new capability is denied
   unless an owner or administrator explicitly approves it.
4. Review issues a `witnora.promotion_grant.v0.1`. The grant is target-bound,
   short lived, idempotently claimable, and valid for one use.
5. A deployment runner claims the grant before changing the target.
6. An observer independent of the manifest builder reads the deployed artifact
   and compares its SHA-256 with the approved candidate.
7. Witnora writes a signed `witnora.promotion_receipt.v0.1`. A digest mismatch
   suspends assurance. A match records promotion but remains
   `REVALIDATION_REQUIRED` until a successor assurance case is independently
   reviewed.

The Hosted workspace exposes one human path: **Review changes and promote**.
Grant claim and deployed-byte verification remain machine operations so an
agent cannot approve its own mutation from the UI.

For a non-bypassable deployment boundary, exchange the grant through the
[GitHub OIDC credential broker and customer-owned admission adapters](./non-bypassable-promotion-enforcement.md).

## Signing boundaries

Hosted promotion grants and receipts use the configured Witnora Ed25519
evidence signer. The signed payload includes the project, mutation, manifest,
artifact, target, observer, outcome, and continuous-assurance result.

Witnora's own npm release is the dogfood profile. GitHub Actions records the
same mutation, single-use grant, and registry-byte receipt. GitHub OIDC artifact
attestations sign those files, while npm Trusted Publishing signs package
provenance. The registry observer downloads the public package after publish;
it does not trust the local tarball path as proof of deployment.

## API

- `POST /v1/projects/:projectId/mutations`
- `GET /v1/projects/:projectId/mutations`
- `POST /v1/projects/:projectId/mutations/:mutationId/promote`
- `POST /v1/projects/:projectId/promotion-grants/:grantId/claim`
- `POST /v1/projects/:projectId/promotion-grants/:grantId/verify-deployment`

Promotion review requires a human owner or administrator. Claim requires a
project key with `runs:write`; verification requires `evidence:write`.
Idempotency keys make retries safe, while a second distinct claim is rejected
as replay.

## What this proves

- the proposed candidate descended from the declared assured parent;
- capability expansion was visible and explicitly reviewed;
- a bounded grant authorized one candidate and one target;
- the observer saw deployed bytes matching, or not matching, that candidate;
- the result is bound to an immutable signed or attested receipt.

It does not prove that every deployment path is forced through Witnora, that a
compromised observer reported truthfully, or that the promoted version is safe.
Those claims require enforced deployment credentials, protected customer-side
keys, multiple independent observation points, and successor revalidation.