amduat/docs/spec-clarifications.md

Spec Clarifications

This document records implementation-level clarifications for draft Tier-1 specs. These notes do not change the specs; they document concrete choices for the implementation in this repository.

Glossary and Abbreviations

Term	Meaning
CURRENT	Effective index state after replaying a log position on a snapshot.
LogPosition	Inclusive logseq upper bound for replay (not a byte offset).
SnapshotID	Opaque uint64_t identifier persisted in SNAPSHOT_ANCHOR.
Segment seal	Log record admitting a segment via (segment_id, segment_hash).
Segment hash	SHA-256 over exact on-disk segment bytes, including footer.
Tombstone	Visibility policy record applied during replay.
Tombstone lift	Cancels a specific tombstone record for the same artifact.
Exec plan	Serialized plan format; executor out of scope for core library.

Snapshot and Log Identity (ASL/STORE-INDEX + ASL/LOG)

Decision:

• LogPosition is the log sequence number (logseq), not a byte offset.
• SnapshotID is an opaque store-assigned uint64_t, persisted in the SNAPSHOT_ANCHOR payload.

Implications:

• IndexState = (SnapshotID, LogPosition) uses an inclusive logseq upper bound when replaying log[0:LogPosition].
• The log's record envelope already carries logseq, so snapshot anchors use the anchor record's logseq as the snapshot log position.
• If no snapshot exists, treat SnapshotID as 0 and LogPosition as 0.

Rationale:

• ASL/LOG/1 defines replay and visibility in terms of logseq ordering.
• ASL/TGK-EXEC-PLAN/1 orders results by logseq and uses log_prefix bounds.
• ASL/STORE-INDEX/1 defines LogPosition as a monotonic integer position and replay as log[0:LogPosition], which maps directly to logseq.

References:

• tier1/asl-log-1.md
• tier1/enc-asl-log-1.md
• tier1/asl-store-index-1.md
• tier1/asl-tgk-execution-plan-1.md
• tier1/enc-asl-tgk-exec-plan-1.md

Index Segment Identity and Seals (ASL/STORE-INDEX + ASL/LOG)

Decision:

• segment_id is a store-local, monotonic uint64_t assigned when a segment is created (before writing records), and persisted by naming/metadata outside the segment file.
• segment_hash is SHA-256 over the exact segment file bytes as stored on disk, including header, records, digest bytes, extents, and footer.

Implications:

• The seal record (SEGMENT_SEAL) binds a specific persisted segment file to the log via (segment_id, segment_hash). Hashing occurs after the footer is written so the hash commits to seal metadata (CRC, seal snapshot, timestamp).
• Replay uses segment_id to locate the segment file and verifies segment_hash before admitting it as visible.

Rationale:

• ENC/ASL-LOG/1 defines the seal payload as a segment ID plus a hash of the segment bytes; the log is the visibility gate, so the hash must cover the complete on-disk segment.
• ENC/ASL-CORE-INDEX/1 does not embed a segment ID, so the ID must be an external, store-managed handle (filename or catalog entry).

References:

• tier1/asl-log-1.md
• tier1/enc-asl-log-1.md
• tier1/asl-store-index-1.md
• tier1/enc-asl-core-index-1.md

Tombstone Semantics (ASL/LOG + ASL/STORE-INDEX)

Decision:

• scope and reason_code are opaque metadata and do not affect shadowing.
• A TOMBSTONE_LIFT cancels only the referenced tombstone record for the same artifact; other tombstones for that artifact remain effective.

Across snapshots:

• Snapshots capture the effective tombstone state as of the snapshot's logseq.
• Lifts recorded after a snapshot become effective only when replay reaches their logseq.

References:

• tier1/asl-log-1.md
• tier1/asl-store-index-1.md

Federation Fields (ENC/ASL-CORE-INDEX)

Decision:

• Version 3 encoders must always emit federation fields in both headers and records. They are required, not optional, in v3.
• Decoders accept legacy versions that omit federation fields and apply default local/internal values as defined in the encoding spec.

References:

• tier1/enc-asl-core-index-1.md

Execution Plan Scope (ASL/TGK-EXEC-PLAN + ENC/ASL-TGK-EXEC-PLAN)

Decision:

• The implementation treats execution plans as a serialized/transport artifact and semantic contract only. A plan executor is out of scope for the core library.

References:

• tier1/asl-tgk-execution-plan-1.md
• tier1/enc-asl-tgk-exec-plan-1.md