51 lines
2.1 KiB
Markdown
51 lines
2.1 KiB
Markdown
|
# ADR-031 — ASL + TGK Index Separation
|
||
|
|
|
||
|
|
Status: Accepted
|
||
|
|
Date: 2026-02-21
|
||
|
|
Decision Owner: Architecture
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
ASL index/log provide artifact visibility, replay, and tombstone semantics.
|
||
|
|
TGK store provides graph query semantics over TGK edge artifacts. We must decide
|
||
|
|
whether to **merge** ASL and TGK indexes into one unified index structure, or
|
||
|
|
keep them separated with explicit cross-layer invariants.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
We **reject** a merged ASL+TGK index.
|
||
|
|
|
||
|
|
ASL index/log and TGK index remain **separate layers** with strict invariants
|
||
|
|
that keep them consistent.
|
||
|
|
|
||
|
|
## Rationale
|
||
|
|
|
||
|
|
* ASL index is about **artifact visibility and replay**; TGK index is about
|
||
|
|
**graph query acceleration**. Their update streams and invariants differ.
|
||
|
|
* Keeping them separate preserves clean layering and deterministic replay.
|
||
|
|
* TGK indexes can be rebuilt or swapped without changing ASL semantics.
|
||
|
|
* A merged index risks coupling graph query policies with storage visibility,
|
||
|
|
complicating federation and policy enforcement.
|
||
|
|
|
||
|
|
## Invariants (Normative)
|
||
|
|
|
||
|
|
1. **Visibility alignment:** TGK indexes MUST only index artifacts visible under
|
||
|
|
ASL log replay at the same `(snapshot_id, log_position)`.
|
||
|
|
2. **Tombstone enforcement:** TGK indexes MUST respect ASL tombstones and
|
||
|
|
tombstone lifts at their `logseq`.
|
||
|
|
3. **No new identity:** TGK nodes/edges MUST use ASL `Reference` identities;
|
||
|
|
TGK MUST NOT introduce a distinct object identity scheme.
|
||
|
|
4. **Deterministic derivation:** TGK index updates MUST be deterministically
|
||
|
|
derived from ASL-admitted records (segments/log). No side-channel writes.
|
||
|
|
5. **Replay equivalence:** Replaying ASL log + sealed segments MUST yield the
|
||
|
|
same TGK index state (up to encoding) as an online build.
|
||
|
|
6. **Snapshot consistency:** TGK queries at a snapshot MUST be consistent with
|
||
|
|
ASL `IndexState` for that snapshot.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
* ASL and TGK index encodings remain separate specs.
|
||
|
|
* Conformance tests for ASL and TGK can evolve independently, with explicit
|
||
|
|
cross-layer checks for the invariants above.
|
||
|
|
* TGK index rebuilds remain possible without touching ASL log/segment formats.
|