amduat-api/notes/USB REQUEST-RESPONSE SCHEMAS.md

Excellent. Below is a **tight, normative draft set** that you can treat as **v0.1 specs**.
I’ll keep this aligned with your philosophy: *PEL early, receipts primary, ASL as the riverbed, no premature coupling.*

I’ll structure this into **five sections**, exactly as requested.

---

# 1. USB REQUEST / RESPONSE SCHEMAS (Normative)

## 1.1 USB REQUEST Schema (v0.1)

```
/usb/REQUEST/
├── manifest.yaml          # REQUIRED
├── pel-program.yaml       # REQUIRED
├── input-artifacts/       # OPTIONAL (directory of files or blocks)
├── policy.hash            # REQUIRED
├── request.sig            # REQUIRED
└── meta/                  # OPTIONAL
    ├── requester-domain.txt
    └── notes.txt
```

### `manifest.yaml`

```yaml
version: 1
request_id: <uuid>
request_type: rescue | admission | authority-op
created_at: <iso8601>
requested_outputs:
  - artifacts
  - receipt
  - dam            # optional
policy_hash: <sha256>
pel_program_hash: <sha256>
input_artifact_hashes:
  - <sha256>
signing:
  algorithm: ed25519
  signer_hint: <string>
```

**Invariant:**

> The manifest is the canonical object. All hashes are computed over canonical encodings.

---

## 1.2 USB RESPONSE Schema (v0.1)

```
/usb/RESPONSE/
├── receipt.per            # REQUIRED
├── published/
│   ├── blocks/
│   ├── index/
│   └── snapshots/
├── dam/                   # OPTIONAL
│   └── domain.dam
├── response.sig           # REQUIRED
└── meta.yaml              # OPTIONAL
```

**Invariant:**

> RESPONSE is append-only and must be reconstructible as ASL input elsewhere.

---

# 2. PEL SUBSET ALLOWED ON AUTH HOST

## 2.1 Allowed PEL Operations

Only **pure, deterministic, side-effect-free** operators:

| Category      | Allowed |
| ------------- | ------- |
| Ingest        | ✔       |
| Hash          | ✔       |
| Encrypt       | ✔       |
| Chunk / Pack  | ✔       |
| Seal          | ✔       |
| Index         | ✔       |
| Snapshot      | ✔       |
| Sign          | ✔       |
| Network       | ✖       |
| Clock access  | ✖       |
| Randomness    | ✖       |
| External exec | ✖       |

---

## 2.2 PEL Program Constraints

```yaml
pel_version: 0.1
operators:
  - ingest
  - encrypt
  - seal
  - index
  - snapshot
outputs:
  - receipt
  - published_artifacts
```

**Invariant:**

> The PEL program hash is part of the receipt and MUST uniquely determine execution.

---

# 3. EXECUTION RECEIPT (PER) SIGNATURE LAYOUT

## 3.1 Receipt Structure

```yaml
receipt_version: 1
receipt_id: <uuid>
domain_id: <uuid>
snapshot_id: <uuid>
pel_program_hash: <sha256>
inputs:
  - artifact_hash
outputs:
  artifacts:
    - artifact_key
    - block_id
receipt_hash: <sha256>
authority_signature:
  algorithm: ed25519
  key_id: <fingerprint>
  signature: <bytes>
```

---

## 3.2 Receipt Invariants

1. Receipt uniquely identifies:

   * Inputs
   * Program
   * Snapshot
2. Receipt hash is computed **before signing**
3. Receipt verification requires **no ASL store access**

> A receipt is portable truth.

---

# 4. PUBLISHED ARTIFACT SELECTION RULES

## 4.1 Default Rule

Only artifacts explicitly declared in the PEL program as `publish: true` may exit the host.

```yaml
outputs:
  - name: encrypted_archive
    publish: true
  - name: intermediate_chunks
    publish: false
```

---

## 4.2 Enforcement

* Unpublished artifacts:

  * May exist internally
  * MUST NOT be written to USB
* Published artifacts:

  * MUST be sealed
  * MUST be indexed
  * MUST be referenced in receipt

---

## 4.3 Domain Binding

Published artifacts are bound to:

```
(domain_id, snapshot_id)
```

This binding is **immutable**.

---

# 5. WRITE-ONCE USB HARDENING RULES

These are **operational invariants**, not filesystem tricks.

## 5.1 Mount Discipline

| Phase        | Mount mode |
| ------------ | ---------- |
| Intake       | read-only  |
| Execution    | unmounted  |
| Output write | read-write |
| Final        | unmounted  |

---

## 5.2 Structural Rules

* AUTH host **never deletes** from USB
* AUTH host **only writes under `/RESPONSE`**
* AUTH host **never modifies REQUEST**

---

## 5.3 Tamper Evidence

* RESPONSE includes:

  * `response.sig`
  * hash of REQUEST manifest
* Any post-write modification invalidates signature

---

# 6. How this fits your philosophy (explicitly)

You said:

> “All we should do is place artifacts, certificates, program specification and intent, then crank.”

That is now **formally true**.

* Intent → manifest
* Program → PEL
* Data → artifacts
* Authority → signature
* Outcome → receipt

Nothing else matters.

---

# 7. What you can implement immediately

Even **without** ASL-CORE or PEL-TRACE:

* Canonical hashing
* Manifest validation
* Receipt generation
* USB discipline
* Domain bootstrapping
* Offline signing

This is *real progress*, not paper.

---

If you want next, I recommend (in this order):

1. **PEL canonical encoding rules**
2. **Receipt hash canonicalization**
3. **DAM schema finalization**
4. **Minimal reference CLI (`asl-auth-host verify/run/seal`)**
5. **Threat model write-up**

Just say where to go.