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

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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

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