amduat/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 Linked Phase Pack: N/A Tags: [deterministic, log, snapshot]

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

Depends on (normative):

• ASL/STORE-INDEX/1 — store lifecycle and replay contracts (pending spec)

Informative references:

• ASL/1-CORE-INDEX — index semantics
• TGK/1 — TGK edge visibility and traversal alignment
• ENC/ASL-LOG/1 — bytes-on-disk encoding profile
• ENC/ASL-CORE-INDEX/1 — index segment encoding
• ASL/SYSTEM/1 — unified system view (PEL/TGK/federation alignment)

© 2025 Niklas Rydberg.

License

Except where otherwise noted, this document (text and diagrams) is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

The identifier registries and mapping tables (e.g. TypeTag IDs, HashId assignments, EdgeTypeId tables) are additionally made available under CC0 1.0 Universal (CC0) to enable unrestricted reuse in implementations and derivative specifications.

Code examples in this document are provided under the Apache License 2.0 unless explicitly stated otherwise. Test vectors, where present, are dedicated to the public domain under CC0 1.0.

---

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.