amduat-api/notes/Policy Hash Specification.md

Below is a minimal, sufficient, and future-proof specification for the Policy Hash, designed to anchor meaning without freezing evolution. It is intentionally small, deterministic, and composable, and it fits cleanly into your DAM + PER + federation model.

---

Policy Hash Specification

---

1. Purpose of the Policy Hash

The policy hash binds domain rules to snapshots and authority without embedding mutable text inside every artifact.

It answers:

“Under what rules was this snapshot, PER, or publication considered valid?”

The hash ensures:

• Deterministic interpretation
• Replay safety
• Cross-domain verification
• Explicit policy evolution

---

2. What the Policy Hash Is (and Is Not)

Is:

✔ A content hash of policy assertions ✔ Snapshot-pinned ✔ Interpreted identically across nodes

Is Not:

✘ A live configuration ✘ An ACL ✘ A rules engine ✘ A machine policy

---

3. Policy Hash Coverage (Normative)

The policy hash MUST cover only semantic constraints that affect correctness or trust.

Mandatory Sections

1. Publication Rules
2. Execution Rules
3. Federation Rules
4. Retention & GC Constraints
5. Visibility Rules

Nothing else.

---

4. Canonical Policy Document (Logical Structure)

The policy document is a pure data artifact.

DomainPolicy {
    version                  : u32
    publication_policy       : PublicationPolicy
    execution_policy         : ExecutionPolicy
    federation_policy        : FederationPolicy
    retention_policy         : RetentionPolicy
    visibility_policy        : VisibilityPolicy
}

---

5. Policy Sections (Minimal Content)

5.1 Publication Policy

PublicationPolicy {
    require_signature        : bool
    allowed_roles[]          : Role
    snapshot_required        : bool
}

Example meaning:

• Artifacts must be signed
• Only publish role may publish
• Publication must be snapshot-bound

---

5.2 Execution Policy

ExecutionPolicy {
    per_signature_required   : bool
    allowed_roles[]          : Role
    deterministic_only       : bool
}

Meaning:

• PERs must be signed
• Only execute role may emit PERs
• No nondeterministic execution accepted

---

5.3 Federation Policy

FederationPolicy {
    export_published_only    : bool
    require_snapshot         : bool
    trusted_domains[]        : DomainID
}

Meaning:

• Only published state may be federated
• Federation is snapshot-based
• Optional allowlist of domains

Empty allowlist = open federation.

---

5.4 Retention & GC Policy

RetentionPolicy {
    gc_unpublished_allowed   : bool
    min_snapshot_retention   : u32
}

Meaning:

• Whether unpublished artifacts may be GC’d
• Minimum snapshots to retain

---

5.5 Visibility Policy

VisibilityPolicy {
    internal_hidden          : bool
    published_read_only      : bool
}

Meaning:

• Internal artifacts invisible externally
• Published artifacts immutable

---

6. Canonicalization Rules (Critical)

The policy hash MUST be computed from canonical bytes:

1. Field order fixed
2. Arrays sorted lexicographically
3. No whitespace
4. No comments
5. Big-endian integers
6. Boolean encoded as 0x00 / 0x01
7. No optional fields omitted — use explicit defaults

Hash algorithm: SHA-256 (or domain-declared)

---

7. Policy Hash Computation

policy_bytes = CanonicalSerialize(DomainPolicy)
policy_hash  = HASH(policy_bytes)

The policy_hash is stored in:

• Domain Authority Manifest
• Snapshot metadata
• Federation metadata
• Optional PER metadata (reference only)

---

8. Validation Semantics

A node MUST reject any operation where:

• Policy hash does not match snapshot
• Policy version unsupported
• Required signature missing
• Required role not satisfied
• Federation rules violated

---

9. Policy Evolution (Key Design Point)

Policy changes do not mutate history.

Instead:

1. New policy document created
2. New policy hash computed
3. New DAM published
4. New snapshots reference new hash

Old snapshots remain valid forever.

---

10. Why This Is Minimal but Complete

✔ Captures all trust-affecting rules ✔ Deterministic across nodes ✔ Decouples authority from text ✔ Enables offline replay ✔ Avoids configuration drift

---

11. One-Sentence Summary

The policy hash cryptographically binds the rules of trust and visibility to every snapshot and execution without embedding mutable policy text into the data plane.

---

If you want, next we can:

• Define canonical serialization format (exact byte layout)
• Show policy hash verification during federation
• Walk through policy evolution example
• Tie policy hash into GC safety proofs

Just tell me where to continue.