# Backend Handoff Checklist: Governance Install and Activation

This checklist maps launcher-governance install behavior to backend requirements.

## Required Endpoints

1. `POST /governance/install/token`
2. `POST /governance/install/confirm`
3. `GET /governance/install/status`
4. `POST /governance/lease/heartbeat`
5. `POST /governance/lease/offline-renew`

## Contract Source

1. `docs/api/governance-installer.openapi.yaml`
2. `docs/api/examples/governance-installer.examples.md`
3. Runtime implementation target: `web/backend/secretapi`

## Required Gate Behavior

1. Install token issuance requires active membership.
2. Install token issuance requires active governance entitlement.
3. Confirm path must validate package hash and runtime version against issued token.
4. Status must fail closed when entitlement state is unknown.
5. Install token issuance must fail closed on org boundary mismatch.
6. `availability_state=parked` must block token issuance and activation.
7. Install/update control actions require principal role `org_root_owner`.

## Persistence Requirements

1. Install token issuance record with expiry.
2. Package metadata snapshot bound to install token.
3. Confirm event record with wallet, device_id, entitlement_id, package hash.
4. Activation state record and immutable evidence receipt hash.

## Security Requirements

1. Install token TTL enforcement.
2. Wallet/session matching on all requests.
3. Idempotent confirm by install token + device + package hash.
4. Reject stale or replayed install confirmations.

## Observability Requirements

1. Metrics for token issuance success/fail.
2. Metrics for confirm success/fail.
3. Metrics for activation blocked by membership/entitlement.
4. Metrics for activation blocked by boundary mismatch or parked availability.
5. Correlation IDs for all state transitions.

## Done Criteria

1. Launcher can install governance only when entitlement is active.
2. Runtime cannot activate if package signature/hash checks fail.
3. `governance_active` status is deterministic and auditable.
4. API implementation matches OpenAPI contract.
5. Non-owner (`workspace_member`) install-token requests are rejected deterministically.