amduat-api/notes/PER Signature Layout Specification.md

Below is a **minimal, deterministic, snapshot-safe PER Signature Layout** that fits *exactly* into your ASL / PEL / TGK / DAM model.
No PKI, no timestamps, no mutable metadata — only what is required to prove **“this execution happened, deterministically, under this authority.”**

---

# PER Signature Layout Specification

---

## 1. Purpose

The **PER signature** certifies that:

* A specific PEL execution occurred
* Against a specific snapshot
* With specific inputs
* Producing a specific output
* Under an authorized domain principal

It enables:

* Deterministic replay
* Cross-domain verification
* Non-repudiation
* Offline validation

---

## 2. What Is Signed (Authoritative Statement)

The signature covers **only immutable, deterministic identifiers**:

```
"I assert that PER X was produced from inputs Y
 under snapshot S at logseq L in domain D"
```

Nothing more. Nothing less.

---

## 3. Canonical Signing Payload

### 3.1 Canonical Payload Structure

This structure is serialized in a **canonical byte order** (defined below).

```text
PERSignaturePayload {
    domain_id            : DomainID
    snapshot_id          : SnapshotID
    per_artifact_id      : ArtifactID
    input_artifact_ids[] : ArtifactID (sorted)
    program_id           : ProgramID
    logseq               : u64
}
```

---

### 3.2 Field Semantics

| Field                  | Meaning                                                  |
| ---------------------- | -------------------------------------------------------- |
| `domain_id`            | Domain asserting the execution                           |
| `snapshot_id`          | Snapshot that bounded inputs                             |
| `per_artifact_id`      | ArtifactID of PER output                                 |
| `input_artifact_ids[]` | All direct inputs (artifacts + PERs), sorted canonically |
| `program_id`           | Stable identifier for PEL program                        |
| `logseq`               | Deterministic execution order                            |

---

## 4. Canonicalization Rules (Normative)

Determinism depends on this.

1. **Byte order:** big-endian
2. **Arrays:** sorted lexicographically by ArtifactID
3. **No optional fields**
4. **No timestamps**
5. **No environment data**
6. **No machine identifiers**

If two nodes produce the same PER under the same snapshot → **payload bytes are identical**.

---

## 5. Signature Object Layout

The signature itself is an ASL artifact.

```text
PERSignature {
    payload_hash   : Hash
    public_key     : PublicKey
    signature      : Signature
    algorithm      : SigAlgorithm
}
```

---

### 5.1 Field Semantics

| Field          | Meaning                                |
| -------------- | -------------------------------------- |
| `payload_hash` | Hash of canonical payload bytes        |
| `public_key`   | Principal key used (must exist in DAM) |
| `signature`    | Signature over payload_hash            |
| `algorithm`    | e.g. ed25519                           |

---

## 6. Relationship to TGK

The signature is linked via TGK edges:

```
PER ──[certified_by]──> PERSignature
PERSignature ──[asserted_under]──> Snapshot
PERSignature ──[asserted_by]──> Principal
```

These edges are immutable and snapshot-bound.

---

## 7. Validation Procedure (Normative)

To validate a PER:

1. Load snapshot
2. Resolve DAM
3. Locate PER artifact
4. Locate PERSignature artifact
5. Recompute canonical payload
6. Verify:

   * `hash(payload) == payload_hash`
   * `signature` valid for `public_key`
   * `public_key ∈ DAM`
   * `role ∈ {execute}`
   * `snapshot_id` visible
7. Accept PER as authoritative

No online checks required.

---

## 8. Failure Modes (Explicit)

| Condition          | Result                    |
| ------------------ | ------------------------- |
| Missing signature  | PER is informational only |
| Invalid signature  | Reject PER                |
| Key not in DAM     | Reject PER                |
| Snapshot mismatch  | Reject PER                |
| Input set mismatch | Reject PER                |
| Logseq conflict    | Reject or quarantine      |

---

## 9. Why This Layout Works

✔ Minimal
✔ Deterministic
✔ Snapshot-safe
✔ Federation-safe
✔ Replayable
✔ Offline-verifiable

And most importantly:

> **The signature certifies meaning, not mechanics.**

---

## 10. One-Sentence Summary

> **A PER signature is a signed statement that a deterministic execution occurred under a specific snapshot, producing a specific artifact, by an authorized principal.**

---

If you want, next we can:

* Define **ProgramID canonicalization**
* Specify **policy hash contents**
* Walk through a full signed PER example (bytes → hash → signature)
* Show federation verification step-by-step

Just say where to go next.