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

Great, this is the right moment to freeze something *small, sharp, and survivable*.

Below is a **clean, minimal, boring-on-purpose** definition of a **Start Log Language v0.1** that:

* Matches ASL-STORE-INDEX precisely
* Keeps one authoritative log
* Avoids over-specifying future policy / federation
* Is stable enough to build against now
* Leaves room for evolution without breakage

I’ll call it **ASL-LOG v0.1**.

---

# ASL-LOG v0.1

**Append-Only Semantic Log for ASL Domains**

---

## 1. Purpose

ASL-LOG defines the **authoritative, append-only log** for an ASL domain.

The log records **semantic commits** that affect:

* Artifact visibility
* Index segment visibility
* Policy (e.g. tombstones)
* Authority state
* Snapshot anchoring

The log is the **sole source of truth** for reconstructing CURRENT state.

---

## 2. Core Properties (Normative)

An ASL log **must** be:

1. **Append-only**
2. **Strictly ordered**
3. **Deterministically replayable**
4. **Hash-chained**
5. **Snapshot-anchorable**
6. **Binary encoded**
7. **Forward-compatible**

---

## 3. Log Model

### 3.1 Log Sequence

Each record has a monotonically increasing `logseq`:

```
logseq: uint64
```

* Assigned by the domain authority
* Total order within a domain
* Never reused

---

### 3.2 Hash Chain

Each record commits to the previous record:

```
record_hash = H(prev_record_hash || record_type || payload)
```

This enables:

* Tamper detection
* Witness signing
* Federation verification

---

## 4. Record Envelope (v0.1)

All log records share a common envelope.

```c
struct asl_log_record_v1 {
    uint64_t logseq;
    uint32_t record_type;
    uint32_t payload_len;
    uint8_t  payload[payload_len];
    uint8_t  record_hash[32];  // e.g. SHA-256
};
```

Notes:

* Encoding is little-endian
* `record_hash` hashes the full record except itself
* Hash algorithm is fixed for v0.1

---

## 5. Record Types (v0.1)

### 5.1 SEGMENT_SEAL (Type = 0x01)

**The most important record in v0.1**

Declares an index segment visible.

```c
struct segment_seal_v1 {
    uint64_t segment_id;
    uint8_t  segment_hash[32];
};
```

Semantics:

> From this `logseq` onward, the referenced index segment is visible
> for lookup and replay.

Rules:

* Segment must be immutable
* All referenced blocks must already be sealed
* Segment contents are not re-logged

---

### 5.2 ARTIFACT_PUBLISH (Type = 0x02) (Optional v0.1)

Marks an artifact as published.

```c
struct artifact_publish_v1 {
    uint64_t artifact_key;
};
```

Semantics:

* Publication is domain-local
* Federation layers may interpret this

---

### 5.3 ARTIFACT_UNPUBLISH (Type = 0x03) (Optional v0.1)

Withdraws publication.

```c
struct artifact_unpublish_v1 {
    uint64_t artifact_key;
};
```

---

### 5.4 TOMBSTONE (Type = 0x10)

Declares an artifact inadmissible under domain policy.

```c
struct tombstone_v1 {
    uint64_t artifact_key;
    uint32_t scope;        // e.g. EXECUTION, INDEX, PUBLICATION
    uint32_t reason_code;  // opaque to ASL-LOG
};
```

Semantics:

* Does not delete data
* Shadows prior visibility
* Applies from this logseq onward

---

### 5.5 TOMBSTONE_LIFT (Type = 0x11)

Supersedes a previous tombstone.

```c
struct tombstone_lift_v1 {
    uint64_t artifact_key;
    uint64_t tombstone_logseq;
};
```

Rules:

* Must reference an earlier TOMBSTONE
* Does not erase history
* Only affects CURRENT ≥ this logseq

---

### 5.6 SNAPSHOT_ANCHOR (Type = 0x20)

Binds semantic state to a filesystem snapshot.

```c
struct snapshot_anchor_v1 {
    uint64_t snapshot_id;
    uint8_t  root_hash[32];  // hash of snapshot-visible state
};
```

Semantics:

* Defines a replay checkpoint
* Enables log truncation below anchor (with care)

---

### 5.7 DOMAIN_AUTH_UPDATE (Type = 0x30) (Optional v0.1)

Updates trusted domain authorities.

```c
struct domain_auth_update_v1 {
    uint8_t  cert_hash[32];
    uint32_t action; // ADD or REVOKE
};
```

---

## 6. Replay Semantics (Normative)

To reconstruct CURRENT:

1. Load latest snapshot anchor (if any)
2. Initialize visible segments from snapshot
3. Replay all log records with `logseq > snapshot.logseq`
4. Apply records in order:

   * SEGMENT_SEAL → add segment
   * TOMBSTONE → update policy state
   * TOMBSTONE_LIFT → override policy
   * PUBLISH → update visibility metadata

Replay **must be deterministic**.

---

## 7. Index Interaction

* Index segments contain index entries
* The log never records individual index entries
* Visibility is controlled solely by SEGMENT_SEAL
* Index rebuild = scan visible segments + apply policy

---

## 8. Garbage Collection Constraints

* A segment may be GC’d only if:

  * No snapshot references it
  * No log replay ≤ CURRENT requires it
* Log truncation is only safe at SNAPSHOT_ANCHOR boundaries

---

## 9. Versioning & Extensibility

* Unknown `record_type`:

  * Must be skipped
  * Must not break replay
* Payloads are opaque outside their type
* v0.1 fixes:

  * Hash algorithm
  * Endianness
  * Core record types

Future versions may:

* Add new record types
* Add optional fields (new struct versions)
* Introduce compression or batching

---

## 10. What v0.1 Deliberately Does *Not* Include

* Federation protocols
* Network replication
* Witness signatures
* Block-level events
* Hydration / eviction
* Execution receipts (PERs)

Those live *above* ASL-LOG.

---

## 11. One-sentence invariant (keep this)

> **If it affects visibility, admissibility, or authority, it goes in the log.
> If it affects layout or performance, it does not.**

---

If you want next steps, the natural continuations are:

* **ASL-LOG test vectors**
* **Minimal C writer/reader API**
* **Formal CURRENT reconstruction pseudocode**
* **Mapping ASL-LOG → federation streams**

But v0.1 as written is *enough to build real systems against* without regret.