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:

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):

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):

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):

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):

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):

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):

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. Invariant (Informative)

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

---

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.