web/docs/policy-hash-versioning.md

Policy Hash and Versioning Spec (v1)

Purpose

Ensure each quote, purchase, and entitlement is provably bound to an exact policy snapshot.

Canonical Policy Snapshot

1. Serialize policy object with stable key ordering.
2. Normalize numeric representations.
3. Remove non-policy metadata fields.

Hashing

1. Compute policy_hash = SHA-256(canonical_policy_json).
2. Store hex-encoded 64-char hash.
3. Include policy_hash in quote response, receipt, and entitlement record.

Versioning

1. policy_version is semantic (v1, v1.1, etc.) for human readability.
2. policy_hash is authoritative for machine verification.
3. Breaking changes require new policy_version and migration note.

Enforcement

1. Checkout confirm rejects if tx-linked quote policy hash differs from current quote policy hash.
2. Entitlement activation uses stored policy_hash; no retroactive mutation.
3. Historical purchases remain tied to their original policy hash.