amduat-api/notes/pre-image capture workflow.md

Perfect — here’s a full sketch of a pre-image capture workflow for building your ASL-AUTH-HOST ISO with full provenance from zero. This is conceptual but grounded in your existing scripts and tools.

---

1. Directory Layout

/work/
├─ iso_root/             # ISO staging area (debootstrap root)
├─ overlay/              # Overlay for binaries, scripts, configs
├─ asl-preimage-store/   # Temporary ASL store for pre-image artifacts
│   ├─ binaries/
│   ├─ scripts/
│   └─ per/
├─ build_logs/           # Capture logs from each step
└─ asl-workflow.sh       # Orchestration script

---

2. Pre-image capture steps

1. Initialize pre-image ASL store

#!/bin/bash
# pre-image store initialization
PRESTORE=/work/asl-preimage-store
mkdir -p $PRESTORE/{binaries,scripts,per}
asl-init-store --store $PRESTORE

asl-init-store can be a thin wrapper around libasl-capture to create a temporary store.

---

2. Wrap build commands in asl-capture

All commands affecting the ISO will be executed via asl-capture to generate artifacts and PERs.

Example:

# Capture debootstrap
asl-capture --store $PRESTORE --cmd "debootstrap --arch=amd64 bullseye $ISO_ROOT http://deb.debian.org/debian/" \
    --outdir $PRESTORE/per/debootstrap

# Capture package installation
asl-capture --store $PRESTORE --cmd "chroot $ISO_ROOT /bin/bash -c 'apt-get update && apt-get install -y ...'" \
    --outdir $PRESTORE/per/apt_install

Each step generates:

• Artifact of input (command, scripts, downloaded packages)
• Artifact of output (installed files, overlays, logs)
• Execution Receipt (PER) linking inputs → outputs

---

3. Capture overlay

# Capture binaries and scripts
for f in $WORKDIR/binaries/* $WORKDIR/scripts/*; do
    asl-capture --store $PRESTORE --file $f --outdir $PRESTORE/per/overlay
done

This ensures all binaries/scripts are artifacts with traceable lineage.

---

4. Assemble ISO using captured artifacts

asl-capture --store $PRESTORE --cmd "./build_asl_auth_host_iso.sh" \
    --artifact-inputs $PRESTORE/binaries \
    --artifact-inputs $PRESTORE/scripts \
    --artifact-inputs $PRESTORE/per \
    --outdir $PRESTORE/per/build_iso

The ISO itself becomes a final artifact with its own PER, referencing all previous steps.

---

5. Seed initial ASL host store in ISO

Copy pre-image artifacts + PERs into ISO root:

cp -a $PRESTORE/binaries $ISO_ROOT/var/lib/asl/personal/binaries
cp -a $PRESTORE/per $ISO_ROOT/var/lib/asl/personal/per
cp -a $PRESTORE/scripts $ISO_ROOT/var/lib/asl/personal/scripts

The offline host boots with an already captured history of how it was built.

---

3. Optional: Artifact DAG visualization

After pre-image capture, you can generate a DAG of artifacts and receipts:

asl-dag --store $PRESTORE --out $WORKDIR/build_logs/preimage_dag.svg

This provides:

• Traceable provenance of everything in the ISO
• Easy inspection for audit

---

4. Workflow Summary

Initialize Pre-image Store --> Capture debootstrap --> Capture apt install --> Capture overlay
        |                     |                         | 
        +---------------------+-------------------------+
                            PERs + Artifacts
                                  |
                             Build ISO using captured inputs
                                  |
                            Seed ISO with captured store
                                  |
                        Offline host boots with full pre-image provenance

---

Key Notes

• asl-capture wraps any shell command or file copy, producing both artifact and PER.
• Pre-image store is temporary during build, but all artifacts go into ISO for the offline host.
• This method ensures determinism, reproducibility, and full traceability even before the host exists.

---

I can also draft a concrete bash orchestration script (asl-workflow.sh) that wires all of this together, including:

• Pre-image store initialization
• Step-by-step captured commands
• ISO assembly
• Seeding the offline host store

Do you want me to do that next?