# ADR: Qualification authorization envelopes and machine intents

Status: accepted
Type: adr
Updated: 2026-08-04
Next Action: apply this standard to new qualification envelopes and monitor the first bounded matrix
Parent: work/maps/map-smi-firmware-stabilization-and-qualification.md
Supersedes:
Superseded By:

## Context

The owner approved bounded qualification campaigns, but the Pi coordinator
models HPT2 human approval as a separate short-lived record for each Start and
Stop, while the full-address scrub stores only a free-form authorization
reference. Chat-level interpretation has therefore been deciding whether safe
continuation, pre-target infrastructure recovery, and read-only reconciliation
need another human response. This creates unnecessary stops and can turn a
recoverable read-only transport interruption into `INTERRUPTED_UNKNOWN`.

Exact controller, firmware, sample, CID, operation UUID, sequence, and no-replay
protections remain mandatory. Powered SD removal/insertion remains prohibited.

## Decision

Human approval is an immutable, scope-bound authorization envelope. The Pi
coordinator derives a unique machine intent for every state-changing operation
inside that envelope.

- One envelope may authorize a named campaign slice or bounded matrix.
- Conditional descendant steps become executable when their recorded gates
  pass; they do not require another human confirmation.
- Read-only observation, preflight, polling, evidence capture, cleanup, and
  reconciliation are normal continuation within the envelope.
- A verified pre-target failure does not consume a destructive allowance.
- Bounded reconnect is allowed only when the transcript proves that no target
  command was reached, or when the attempted session is read-only.
- After a state-changing command is published, that command is never replayed.
  Read-only reconciliation continues automatically against the same durable
  operation.
- New approval is required only for changed identity or scope, an unlisted
  destructive action, destructive replay, physical intervention, a safety
  decision, expired/revoked authority, or credentials.
- Human envelopes and derived machine intents are independently auditable.

## Consequences

Positive:

- Operators approve risk once at the correct level instead of relaying each
  machine command.
- Existing exact-intent, expiry, sequence, identity, and no-replay safeguards
  remain enforceable.
- Read-only recovery becomes deterministic and does not depend on chat wording.
- Authorization consumption has a testable state-change boundary.

Negative:

- The Pi application needs a migration, envelope UI, service changes, and
  compatibility handling for legacy per-command authorizations.
- Envelope scope must be reviewed carefully because it can cover several
  conditional operations.

## Alternatives Considered

- Keep per-command human approval: rejected because it confuses human risk
  acceptance with machine idempotency and produces avoidable workflow stops.
- Treat every error as consuming authority: rejected because failures proven to
  occur before target access have no destructive effect.
- Allow retries after an ambiguous write: rejected because it violates the
  established no-replay boundary.

## Supersession Notes

This decision refines, rather than supersedes,
`work/decisions/decision-remaining-qualification-authorization.md`. That
matrix remains the approved scope; this ADR defines how the Pi represents and
executes it.

## Implementation

Deployed 2026-08-04 on `srv-rpi00.local`:

- Pi migration/base commit `16d7d04fb416872192711f9766e20c1d42db3c08`
- Pi final matrix-scope commit `1e62f33`
- release `authorization-envelopes-1e62f33`
- migration `qualification.0015_authorizationenvelope`
- deployment evidence:
  `work/evidence/pi-authorization-envelope-migration-deployment-manifest-20260804.md`
