NOTE: Superseded by `tier1/tgk-1.md` (TGK/1). Kept for historical context.

Below is a **formal draft of TGK-INDEX**, written to **exactly mirror the ASL-INDEX-ACCEL framework** and to cleanly integrate TGK into the overall model without inventing new semantics.

---

# TGK-INDEX

### Trace Graph Kernel Index Semantics and Acceleration

---

## 1. Purpose

TGK-INDEX defines the **indexing semantics for Trace Graph Kernel (TGK) edges**, which represent stored projections derived from:

* PEL execution
* Execution receipts
* Provenance and trace material

This document specifies:

* Canonical identity of TGK edges
* Snapshot-relative visibility
* Index lookup semantics
* Interaction with acceleration mechanisms defined in ASL-INDEX-ACCEL

> TGK-INDEX defines **what edges exist and how they are observed**, not how they are accelerated.

---

## 2. Scope

This specification applies to:

* All TGK edge storage
* Edge lookup and traversal
* Stored projections over ASL artifacts and PEL executions

It does **not** define:

* PEL execution semantics
* Provenance interpretation
* Federation policies
* Storage encoding (see ENC-* documents)
* Acceleration mechanisms (see ASL-INDEX-ACCEL)

---

## 3. TGK Edge Model

### 3.1 TGK Edge

A TGK Edge represents a **directed, immutable relationship** between two nodes.

Nodes MAY represent:

* Artifacts
* PEL executions
* Receipts
* Abstract graph nodes defined by higher layers

Edges are created only by deterministic projection.

---

### 3.2 Canonical Edge Key

Each TGK edge has a **Canonical Edge Key**, which uniquely identifies the edge.

The Canonical Edge Key MUST include:

* Source node identifier
* Destination node identifier
* Projection context (e.g. PEL execution or receipt identity)
* Edge direction (if not implied)

Properties:

* Defines semantic identity
* Used for equality, shadowing, and tombstones
* Immutable once created
* Fully compared on lookup match

---

## 4. Edge Type Key

### 4.1 Definition

Each TGK edge MAY carry an **Edge Type Key**, which classifies the edge.

Properties:

* Immutable once edge is created
* Optional, but strongly encouraged
* Does NOT participate in canonical identity
* Used for routing, filtering, and query acceleration

Formal rule:

> Edge Type Key is a classification attribute, not an identity attribute.

---

### 4.2 Absence Encoding

If an edge has no Edge Type Key, this absence MUST be explicitly encoded and observable to the index.

---

## 5. Snapshot Semantics

### 5.1 Snapshot-Relative Visibility

TGK edges are **snapshot-relative**.

An edge is visible in snapshot `S` if and only if:

* The edge creation log entry has `LogSeq ≤ S`
* The edge is not shadowed by a later tombstone with `LogSeq ≤ S`

---

### 5.2 Determinism

Given the same snapshot and input state:

* The visible TGK edge set MUST be identical
* Lookup and traversal MUST be deterministic

---

## 6. TGK Index Semantics

### 6.1 Logical Index Definition

The TGK logical index maps:

```
(snapshot, CanonicalEdgeKey) → EdgeRecord | ⊥
```

Rules:

* Newer entries shadow older ones
* Tombstones shadow edges
* Ordering is defined by log sequence

---

### 6.2 Lookup by Attributes

Lookup MAY constrain:

* Source node
* Destination node
* Edge Type Key
* Projection context

Such constraints are **advisory** and MAY be accelerated but MUST be validated by full edge record comparison.

---

## 7. Acceleration and Routing

### 7.1 Canonical vs Routing Keys

TGK indexing follows ASL-INDEX-ACCEL.

* Canonical identity is defined solely by Canonical Edge Key
* Routing Keys are derived and advisory

Routing Keys MAY incorporate:

* Hash of Canonical Edge Key
* Edge Type Key
* Direction or role

---

### 7.2 Filters

Filters:

* Are built over Routing Keys
* May include Edge Type Key
* MUST NOT introduce false negatives
* MUST be verified by full edge comparison

---

### 7.3 Sharding

Sharding:

* Is observationally invisible
* MAY be based on Routing Keys
* MUST preserve logical index equivalence

---

### 7.4 SIMD Execution

SIMD MAY be used to accelerate:

* Filter evaluation
* Routing key comparison
* Edge scanning

SIMD MUST NOT affect semantics.

---

## 8. Relationship to ASL Index

TGK indexing:

* Reuses ASL snapshot and log ordering semantics
* May share physical storage and segments with ASL artifacts
* Is governed by the same checkpoint and recovery model

TGK edges MAY reference ASL artifacts across snapshots, subject to provenance constraints.

---

## 9. Garbage Collection and Retention

* TGK edges MUST NOT be collected while referenced by any retained snapshot
* Tombstoned edges MAY be reclaimed once unreachable
* Provenance requirements MAY pin edges beyond snapshot reachability

GC policies are store-defined but MUST preserve snapshot safety.

---

## 10. Federation Considerations (Non-Normative)

In federated environments:

* Edge visibility MAY differ by domain
* Edge Type Keys MAY be namespaced
* Canonical Edge Keys MUST remain globally stable

Federation rules are defined outside this document.

---

## 11. Normative Invariants

1. Canonical Edge Key defines identity
2. Edge Type Key is not part of identity
3. Snapshot visibility is log-sequence based
4. Acceleration is advisory only
5. Filters must not produce false negatives
6. Sharding is observationally invisible
7. Determinism is required per snapshot

---

## 12. Summary

TGK-INDEX defines a **snapshot-safe, deterministic graph index** that:

* Treats edges as immutable, indexed entities
* Separates identity from classification
* Scales to billions of edges
* Integrates cleanly with ASL indexing and acceleration

By strictly reusing the Canonical vs Routing framework, TGK avoids semantic drift and ensures that **graph queries remain correct regardless of acceleration strategy**.

---

If you want, the next logical step would be to:

* Draft **ENC-TGK-INDEX** (exact on-disk encoding)
* Or write a **unified query model** spanning ASL + TGK lookups