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