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`