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.

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.

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.

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.

struct artifact_unpublish_v1 {
    uint64_t artifact_key;
};

---

5.4 TOMBSTONE (Type = 0x10)

Declares an artifact inadmissible under domain policy.

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.

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.

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.

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.