amduat-api/notes/ASL-COMMON-WITNESS-ROTATION.md

Great — let’s formalize it cleanly and minimally, in the same style as your other specs.

Below is a **normative artifact specification**. I’ll keep it tight, auditable, and compatible with ASL / PEL thinking.

---

# **ASL-COMMON-WITNESS-ROTATION v0.1**

## 1. Purpose

The **Witness Rotation Artifact (WRA)** authorizes a change of the active **Common Witness Emitter** while preserving:

* single linear Common history
* offline operation
* auditability
* fork prevention

The WRA is the **only mechanism** by which witness authority may change.

---

## 2. Scope and guarantees

This artifact:

* does **not** modify artifacts, blocks, or snapshots directly
* authorizes **who may emit the next Common snapshot**
* is snapshot-bound and immutable
* is evaluated **only by ASL-HOST instances handling the Common domain**

---

## 3. Definitions

| Term                  | Meaning                                                |
| --------------------- | ------------------------------------------------------ |
| **Witness Emitter**   | The domain authorized to emit the next `common@N+1`    |
| **Witness Authority** | A domain whose key may endorse witness changes         |
| **Quorum**            | A threshold of valid endorsements                      |
| **Rotation Snapshot** | The first snapshot emitted under new witness authority |

---

## 4. Artifact identity

**Artifact type:** `asl.common.witness-rotation`
**Artifact key:** content-addressed (CAS)
**Visibility:** published (Common domain only)

---

## 5. Canonical structure (logical)

```yaml
artifact_type: asl.common.witness-rotation
version: 0.1

common_domain_id: <domain-id>

previous_snapshot:
  snapshot_id: common@N
  snapshot_hash: <hash>

rotation:
  old_witness:
    domain_id: <domain-id>
    pubkey_id: <key-id>

  new_witness:
    domain_id: <domain-id>
    pubkey_id: <key-id>

policy_ref:
  artifact_key: <common-policy-artifact>

reason: <utf8-string, optional>

endorsements:
  threshold: <uint>
  endorsements:
    - domain_id: <domain-id>
      pubkey_id: <key-id>
      signature: <bytes>
    - ...

created_at_logseq: <uint64>
```

---

## 6. Cryptographic requirements

### 6.1 Endorsement signature

Each endorsement signs **exactly**:

```
H(
  artifact_type
  || version
  || common_domain_id
  || previous_snapshot.snapshot_id
  || previous_snapshot.snapshot_hash
  || new_witness.domain_id
  || new_witness.pubkey_id
  || policy_ref.artifact_key
)
```

* Hash function: same as ASL block hash
* Signature scheme: per ASL-AUTH (e.g. Ed25519)

---

## 7. Validation rules (normative)

An ASL-HOST **MUST accept** a witness rotation artifact if and only if:

1. `previous_snapshot` matches the current trusted Common snapshot
2. All endorsement signatures are valid
3. Endorsing keys are authorized by the referenced policy
4. Endorsement count ≥ policy quorum threshold
5. `new_witness` is not revoked in policy
6. Artifact hash matches CAS key

Otherwise the artifact **MUST be rejected**.

---

## 8. Application semantics

### 8.1 When applied

The WRA does **not** immediately advance Common.

It becomes effective **only when a snapshot is emitted** by `new_witness`.

---

### 8.2 Rotation snapshot

The first snapshot emitted by the new witness:

```
common@N+1
```

MUST include:

```yaml
witness:
  domain_id: <new_witness.domain_id>
  pubkey_id: <new_witness.pubkey_id>
  rotation_artifact: <artifact_key>
```

This snapshot:

* seals the rotation
* permanently records authority transfer
* invalidates emissions by the old witness

---

## 9. Failure and recovery semantics

### 9.1 Old witness emits after rotation

Such snapshots:

* MUST be rejected
* MUST NOT be indexed
* MAY be retained as foreign artifacts for audit

---

### 9.2 New witness fails before emitting

Rotation remains **pending**.

Quorum may:

* re-endorse another WRA
* or extend grace period (policy-defined)

No fork occurs.

---

## 10. Interaction with snapshots and CURRENT

* CURRENT resolution **MUST consider only the active witness**
* Snapshot ordering remains strictly monotonic
* Rotation artifacts do **not** affect artifact visibility

---

## 11. Minimal policy requirements

The referenced Common policy artifact MUST define:

```yaml
witness_policy:
  authorities:
    - domain_id
    - pubkey_id
  quorum_threshold: uint
  rotation_allowed: true
```

---

## 12. Security properties

This design guarantees:

* **No split-brain:** only one valid witness at a time
* **Offline survivability:** endorsements are asynchronous
* **Auditability:** every rotation is permanently recorded
* **Revocability:** compromised witnesses can be replaced

---

## 13. Why this fits ASL cleanly

* Rotation is an **artifact**
* Authority is **data**, not code
* History is **explicit**, not inferred
* No special network protocol required

---

## 14. One-sentence invariant (the one to remember)

> **A Common snapshot is valid if and only if its witness authority is provable from the previous snapshot.**

---

If you want next, we can:

* formalize the **Common Policy Artifact**
* define the **recovery-from-silence** artifact
* specify how ASL-HOST enforces witness authority at boot
* or walk through a concrete rotation with real keys and USB transfers

This piece is now solid.