web/docs/governance-install-spec.md

Governance Install Specification (First Paid License)

This spec defines deterministic installation of the governance runtime after membership and governance entitlement purchase.

Preconditions

1. Launcher is installed and wallet is initialized locally.
2. Membership is active for ownership wallet.
3. Governance entitlement is active for ownership wallet.
4. Workspace target boundary matches active suite entitlement org_root_id.
5. Availability state for acting principal is not PARKED.
6. Acting principal role for install/update control is ORG_ROOT_OWNER.

Install Flow

1. Launcher requests governance install token from backend.
2. Backend verifies membership, governance entitlement, org boundary, and availability state.
3. Backend returns signed install bundle metadata:

• package url
• package hash
• signer key id
• policy hash
• expiry

4. Launcher downloads package.
5. Launcher verifies package hash.
6. Launcher verifies package signature against trusted signer set.
7. Launcher writes immutable install receipt locally.
8. Launcher hands off to governance runtime bootstrap.
9. Governance runtime re-verifies entitlement receipt and policy hash.
10. Runtime activation state transitions to ACTIVE.

Activation State Machine

NOT_INSTALLED -> DOWNLOADED -> VERIFIED -> BOOTSTRAPPED -> ACTIVE

Failure states:

• VERIFY_FAILED
• RECEIPT_INVALID
• ENTITLEMENT_INACTIVE
• POLICY_MISMATCH

Deterministic Rules

1. Any missing signature/hash mismatch blocks install.
2. Any inactive/unknown entitlement blocks activation.
3. Any policy hash mismatch blocks activation.
4. Activation requires both launcher and runtime verification passes.
5. Reinstall with same package hash must be idempotent.
6. Boundary mismatch or PARKED availability state blocks install token issuance.
7. Non-owner principal role blocks install/update control paths.

Ownership vs Payment Wallet

1. Entitlement ownership wallet controls activation rights.
2. Payment wallet may differ from ownership wallet.
3. Activation checks only ownership wallet + entitlement state.

Evidence Requirements

Each successful install must persist evidence containing:

1. ownership wallet
2. entitlement id
3. package hash
4. signer key id
5. policy hash
6. activation timestamp
7. launcher version
8. runtime version

Non-Goals

1. Running governance runtime before entitlement verification.
2. Trusting unsigned packages.
3. Allowing active runtime on revoked entitlement.