amduat-api/notes/ASL SystemRescue Overlay – Intake Schema.md

Perfect — then let’s be very concrete and **treat the overlay itself as a specification**, not just “put binaries somewhere”.

Below is a **clean, minimal, opinionated overlay schema** for an **ASL intake / rescue environment**, aligned with everything you’ve defined (ASL, STORE-INDEX, federation, ZFS optional).

No diagrams, no fluff.

---

# ASL SystemRescue Overlay – Intake Schema

This overlay defines **what exists at boot**, **where state lives**, and **what is immutable vs runtime**.

---

## 1. High-level intent

The overlay must:

* Make ASL tools **always available**
* Be **stateless by default**
* Support **local ZFS intake OR remote ASL intake**
* Keep **semantic state out of the rescue image**
* Be safe on crashed systems

So the overlay provides:

* **executables**
* **configuration defaults**
* **service wiring**
* **well-known mount points**

Nothing else.

---

## 2. Canonical overlay layout

```
overlay/
├── usr/
│   └── local/
│       ├── bin/
│       │   ├── asl-intake
│       │   ├── asl-admin
│       │   └── asl-debug
│       └── lib/
│           └── libasl.so
│
├── etc/
│   └── asl/
│       ├── asl.conf              # mode selection, endpoints
│       ├── federation.conf       # domain + peer config
│       └── logging.conf
│
├── etc/systemd/system/
│   ├── asl-intake.service
│   └── asl-preflight.service
│
├── var/
│   └── lib/
│       └── asl/
│           ├── runtime/           # ephemeral runtime state
│           ├── cache/             # optional CAS cache
│           └── locks/
│
├── run/
│   └── asl/
│       └── sockets/               # if used (optional)
│
└── mnt/
    └── asl/
        ├── local/                 # local ZFS mount target
        └── remote/                # optional remote FS
```

This is the **entire contract** between SystemRescue and ASL.

---

## 3. What each directory *means* (important)

### `/usr/local/bin`

**Immutable tools**

* `asl-intake`
  Primary recovery/intake executable
* `asl-admin`
  Inspection, snapshot listing, GC checks
* `asl-debug`
  Low-level validation, block/segment inspection

> These must never write here.

---

### `/etc/asl`

**Declarative configuration only**

Example `asl.conf`:

```
mode = auto           # auto | local | remote
local.mount = /mnt/asl/local
remote.endpoint = https://asl-backend
domain.id = rescue-domain
```

Rules:

* No secrets unless unavoidable
* No mutable state
* Safe to ship in ISO

---

### `/var/lib/asl`

**All mutable local state**

This is the *only* place your tools write to by default.

```
/var/lib/asl/runtime   # PID files, temp metadata
/var/lib/asl/cache     # optional local CAS cache
/var/lib/asl/locks     # advisory locks
```

This may live:

* in RAM (default)
* on USB persistence
* never on the broken system disk

---

### `/mnt/asl/local`

**Local ASL backend mount (ZFS)**

If local intake is possible:

```
zpool import rescuepool
zfs mount rescuepool/asl → /mnt/asl/local
```

Your tool treats this as:

```
/mnt/asl/local/
├── blocks/
├── segments/
├── snapshots/
└── logs/
```

(Exact internal layout is backend-defined, not overlay-defined.)

---

### `/mnt/asl/remote`

Optional:

* NFS
* SSHFS
* Debug mounts

Not required for normal operation.

---

## 4. systemd services (minimal and safe)

### `asl-preflight.service`

Runs once at boot.

Responsibilities:

* Detect network
* Detect ZFS availability
* Detect importable pools
* Write decision to `/run/asl/mode`

No mutations.

---

### `asl-intake.service`

Starts the tool.

Example behavior:

* Reads `/run/asl/mode`
* Chooses:

  * local ZFS backend
  * or remote ASL endpoint
* Starts intake loop or waits for operator

This keeps **policy out of the binary**.

---

## 5. Local vs remote handling (explicit contract)

### Local ZFS mode

The overlay guarantees:

```
/mnt/asl/local  exists
/var/lib/asl    writable
/usr/local/bin  contains tools
```

Your tool guarantees:

* Never mutate unsealed data
* Never auto-import pools without operator or config approval

---

### Remote ASL mode

The overlay guarantees:

* Network tools available
* TLS roots present
* Configurable endpoint

Your tool guarantees:

* Snapshot-bounded reads
* Deterministic uploads
* Idempotent retries

---

## 6. What is *explicitly forbidden* in the overlay

These rules prevent disasters:

❌ Writing to `/usr`, `/bin`, `/lib`
❌ Storing state in `/etc`
❌ Auto-mounting the crashed system root
❌ Assuming ZFS exists
❌ Assuming network exists

All assumptions must be **detected, not presumed**.

---

## 7. Why this schema works with your ASL design

This layout aligns perfectly with your specs because:

* **ASL-STORE-INDEX**
  → persistence lives outside the overlay

* **Federation**
  → domain identity is config, not state

* **PEL / TGK**
  → execution artifacts are handled like any other artifact

* **Determinism**
  → overlay never contains semantic state

The overlay is **pure capability**, not data.

---

## 8. Summary (the one-paragraph version)

> The SystemRescue overlay should contain **only tools, config, and wiring**.
> All mutable ASL state lives either in `/var/lib/asl` (ephemeral) or in a mounted backend (`/mnt/asl/local` or remote).
> The overlay never encodes semantic state, snapshots, or artifacts — only the ability to access and produce them.

If you want, next we can:

* Turn this into a **formal overlay contract doc**
* Define a **preflight decision table**
* Or map this schema directly onto your ASL backend spec

But this layout is already “correct by construction.”