amduat-api/notes/ASL-HOST v0-1.md

Here’s a clean v0.1 draft for ASL-HOST, scoped to what we discussed — minimal, environment-focused, without touching semantics or storage encoding. This is the runtime/host interface layer that bridges ASL-STORE(-INDEX) to a real system.

---

ASL-HOST v0.1 – Host/Runtime Interface for ASL Stores

1. Purpose

ASL-HOST specifies the runtime contract between an ASL store and the host environment. It defines what the host must provide for an ASL store to operate correctly, without imposing:

• Storage semantics
• Encoding
• Policy
• Security beyond minimal integrity guarantees

It supports POSIX filesystems, ZFS, object stores, or other backing layers.

---

2. Core Concepts

Concept	Definition
StoreHandle	Opaque reference to a host-provided store instance
StoreLocation	Host-defined location where a store exists (path, URI, mount point, etc.)
AppendUnit	Minimum atomic write unit for the append-only log
SnapshotID	Opaque identifier of a host-provided snapshot
HostClock	Monotonic counter or timestamp source
HostIdentity	Unique machine or user identity for signing or domain minting

---

3. Store Instantiation

3.1 Store Creation

• CreateStore(location: StoreLocation) → StoreHandle

• Must guarantee crash-consistent initialization.

• Location may be:

  • POSIX path
  • ZFS dataset
  • Object store bucket

• StoreHandle is opaque, only valid while the store exists on host.

3.2 Store Open

• OpenStore(location: StoreLocation) → StoreHandle
• Host must provide durable, consistent view.
• Opening an existing store must not corrupt previous data.

3.3 Store Close

• CloseStore(store: StoreHandle)
• Ensures all writes are persisted to durable media.
• Optional: triggers host-specific flush or checkpoint.

---

4. Atomic Append / Log Operations

• Host must provide atomic append semantics.

• Minimum guarantees:

  • Sequential ordering (logseq monotonicity)
  • Crash consistency (partial writes are not visible)

• AppendUnit:

  • Defined by host; could be page-size or object-size
  • ASL-STORE must tolerate host’s granularity

---

5. Snapshot Management

• Optional but recommended.

• Host provides:

  • CreateSnapshot(store: StoreHandle) → SnapshotID
  • MountSnapshot(store: StoreHandle, id: SnapshotID) → StoreHandle

• Guarantees:

  • Snapshot captures a consistent view of sealed blocks
  • Mounting snapshot produces read-only store handle

• Host may use:

  • ZFS snapshot
  • POSIX filesystem copy-on-write overlay
  • Object store versioning

---

6. Durability & Crash Semantics

• Host must ensure:

  • Writes are durable after append or flush
  • Crash recovery restores store to last durable state
  • Open, unsealed blocks may be lost without breaking invariants

• StoreHandle and append-only log are atomic units visible to ASL-STORE

---

7. Minimal Identity & Logging

• Host must provide:

  • HostClock() → monotonic timestamp / counter
  • HostIdentity() → machine or user ID for signing / domain minting
  • Optional log for debugging or auditing

---

8. Error Semantics

• Operations may return:

  • STORE_OK
  • STORE_EXISTS
  • STORE_NOT_FOUND
  • STORE_IO_ERROR
  • STORE_CONCURRENT_MODIFICATION

• ASL-STORE must handle errors deterministically

---

9. Security Considerations

• ASL-HOST does not enforce cryptography.

• Host may provide optional:

  • Encryption at rest
  • Access control
  • Secure snapshot mechanisms

• Certificates and trust are handled in ASL-AUTH, separate layer

---

10. Example Implementations

Backend	How ASL-HOST maps
POSIX filesystem	StoreLocation = path; append = write+fsync; snapshot = overlayfs copy
ZFS dataset	StoreLocation = dataset; append = zfs sync; snapshot = zfs snapshot
Object store	StoreLocation = bucket/namespace; append = object PUT; snapshot = versioned bucket

---

11. Versioning

• Spec version: 0.1
• Backward incompatible changes must bump major version.
• Minimal compliance: implement store creation/open/close and append guarantees.

---

12. Summary

ASL-HOST v0.1:

• Defines runtime contract between ASL store and host
• Provides store handles, atomic append, snapshots, identity
• Layered cleanly above ASL-STORE(-INDEX), below system or OS
• Keeps semantics, encoding, and trust separate

---

If you like, I can draft ASL-AUTH v0.1 next, and then show how SystemRescue could instantiate ASL-HOST with POSIX/ZFS to seed a personal domain. That would give a complete view for your rescue scenario.

Do you want me to do that next?