amduat-api/tier1/asl-log-1.md

# ASL/LOG/1 — Append-Only Semantic Log

Status: Draft
Owner: Niklas Rydberg
Version: 0.1.0
SoT: No
Last Updated: 2025-11-16
Tags: [deterministic, log, snapshot]

**Document ID:** `ASL/LOG/1`
**Layer:** L1 — Domain log semantics (no transport)

**Depends on (normative):**

* `ASL-STORE-INDEX`

**Informative references:**

* `ASL/1-CORE-INDEX` — index semantics
* `TGK/1` — TGK edge visibility and traversal alignment
* `ENC-ASL-LOG` — bytes-on-disk encoding profile (`tier1/enc-asl-log.md`)
* `ENC-ASL-CORE-INDEX` — index segment encoding (`tier1/enc-asl-core-index.md`)
* `ASL/SYSTEM/1` — unified system view (PEL/TGK/federation alignment)

---

## 0. Conventions

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.

ASL/LOG/1 defines **semantic log behavior**. It does not define transport, replication protocols, or storage layout.

---

## 1. Purpose

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

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

* Index segment visibility
* Tombstone policy
* Snapshot anchoring
* Optional publication metadata

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 per `ENC-ASL-LOG`
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 || logseq || record_type || payload_len || payload)
```

This enables tamper detection, witness signing, and federation verification.

### 3.3 Record Envelope

All log records share a common envelope whose **exact byte layout** is defined
in `ENC-ASL-LOG`. The envelope MUST include:

* `logseq` (monotonic sequence number)
* `record_type` (type tag)
* `payload_len` (bytes)
* `payload` (type-specific bytes)
* `record_hash` (hash-chained integrity)

---

## 4. Record Types (Normative)

## 4.0 Common Payload Encoding (Informative)

The byte-level payload schemas are defined in `ENC-ASL-LOG`. The shared
artifact reference encoding is:

```c
typedef struct {
    uint32_t hash_id;
    uint16_t digest_len;
    uint16_t reserved0; // must be 0
    uint8_t  digest[digest_len];
} ArtifactRef;
```

### 4.1 SEGMENT_SEAL

Declares an index segment visible.

Payload (encoding):

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

Semantics:

* From this `logseq` onward, the referenced segment is visible for lookup and replay.
* Segment MUST be immutable.
* All referenced blocks MUST already be sealed.
* Segment contents are not re-logged.

### 4.2 TOMBSTONE

Declares an artifact inadmissible under domain policy.

Payload (encoding):

```c
typedef struct {
    ArtifactRef artifact;
    uint32_t scope;
    uint32_t reason_code;
} TombstonePayload;
```

Semantics:

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

### 4.3 TOMBSTONE_LIFT

Supersedes a previous tombstone.

Payload (encoding):

```c
typedef struct {
    ArtifactRef artifact;
    uint64_t tombstone_logseq;
} TombstoneLiftPayload;
```

Semantics:

* References an earlier TOMBSTONE.
* Does not erase history.
* Only affects CURRENT at or above this logseq.

### 4.4 SNAPSHOT_ANCHOR

Binds semantic state to a snapshot.

Payload (encoding):

```c
typedef struct {
    uint64_t snapshot_id;
    uint8_t  root_hash[32];
} SnapshotAnchorPayload;
```

Semantics:

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

### 4.5 ARTIFACT_PUBLISH (Optional)

Marks an artifact as published.

Payload (encoding):

```c
typedef struct {
    ArtifactRef artifact;
} ArtifactPublishPayload;
```

Semantics:

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

### 4.6 ARTIFACT_UNPUBLISH (Optional)

Withdraws publication.

Payload (encoding):

```c
typedef struct {
    ArtifactRef artifact;
} ArtifactUnpublishPayload;
```

---

## 5. Replay Semantics (Normative)

To reconstruct CURRENT:

1. Load latest snapshot anchor (if any).
2. Initialize visible segments from that 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/UNPUBLISH -> update visibility metadata

Replay MUST be deterministic.

---

## 6. 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.

---

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

---

## 8. Versioning & Extensibility

* Unknown record types MUST be skipped and MUST NOT break replay.
* Payloads are opaque outside their type.
* New record types may be added in later versions.

---

## 9. Non-Goals

ASL/LOG/1 does not define:

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

---

## 10. Summary

ASL/LOG/1 defines the minimal semantic log needed to reconstruct CURRENT.

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