web/docs/handoff/governance-backend-checklist.md

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

Contract Source

1. docs/api/governance-installer.openapi.yaml
2. docs/api/examples/governance-installer.examples.md

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.

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