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