niklas/amduat-api
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat-api/tier1/asl-log-1.md
Carl Niklas Rydberg 950a601fbe Add TGK/1 spec and align TGK references
2026-01-17 07:32:14 +01:00

4.2 KiB
Raw Blame History

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 (if defined)
  • 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. 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, and federation verification.

4. Record Types (Normative)

4.1 SEGMENT_SEAL

Declares an index segment visible.

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.

Semantics:

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

4.3 TOMBSTONE_LIFT

Supersedes a previous tombstone.

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.

Semantics:

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

4.5 ARTIFACT_PUBLISH (Optional)

Marks an artifact as published.

Semantics:

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

4.6 ARTIFACT_UNPUBLISH (Optional)

Withdraws publication.

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.