# TGK/1 — Trace Graph Kernel Semantics

Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-11-30
Tags: [tgk, determinism, index, federation]

**Document ID:** `TGK/1`
**Layer:** L1 — Semantic graph layer over ASL artifacts and PERs (no encodings)

**Depends on (normative):**

* `ASL/1-CORE`
* `ASL/1-CORE-INDEX`
* `ASL/LOG/1`
* `ASL/SYSTEM/1`

**Informative references:**

* `ENC-TGK1-EDGE` (core edge encoding, if present)
* `ENC-TGK-INDEX` (index encoding draft)
* `ASL/INDEX-ACCEL/1`
* `ENC-ASL-CORE-INDEX`

---

## 0. Conventions

The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHOULD**, and **MAY** are to be interpreted as in RFC 2119.

TGK/1 defines semantic meaning only. It does not define storage formats, on-disk encodings, or execution operators.

---

## 1. Purpose & Scope

TGK/1 defines the **semantic layer** for Trace Graph Kernel (TGK) edges that relate ASL artifacts and PERs.
It keeps TGK thin and deterministic by reusing ASL index and log semantics.

Non-goals:

* New encodings for edges or indexes
* Query operators or execution plans
* Federation protocols or transport
* Re-definition of ASL or PEL semantics

---

## 2. TGK Objects

### 2.1 TGK Edge

A TGK Edge is an **immutable record** representing a directed relationship between ASL artifacts and/or PERs.
TGK edges are semantic overlays and **MUST NOT** redefine or bypass ASL identity.
TGK/1-CORE defines the EdgeBody structure with ordered `from`/`to` lists; TGK/1
does not further constrain cardinality.

### 2.2 Canonical Edge Key

Each TGK edge has a **Canonical Edge Key** that uniquely identifies it.
The Canonical Edge Key MUST be derived from the logical `EdgeBody` defined in
`TGK/1-CORE`, preserving list order and multiplicity:

* `from`: ordered list of source node identifiers (MAY be empty)
* `to`: ordered list of destination node identifiers (MAY be empty)
* `payload`: reference carried by the edge
* `type`: edge type identifier
* Projection context (for example, PER or execution identity) when not already
  captured by the edge payload or type profile

Classification attributes (edge type keys, labels) **MUST NOT** affect canonical identity.

---

## 3. Index and Visibility (Normative)

TGK edges are **indexed objects** and inherit visibility from the ASL index and log:

1. A TGK edge becomes visible only when its index record is admitted by a sealed segment and log order (ASL/LOG/1).
2. TGK traversal and lookup **MUST NOT** bypass index visibility or log ordering.
3. For a fixed `{Snapshot, LogPrefix}`, TGK edge lookup and shadowing **MUST** be deterministic (ASL/1-CORE-INDEX).
4. Tombstones and shadowing semantics follow ASL/1-CORE-INDEX and ASL/LOG/1 replay order.

Index records MUST reference TGK/1-CORE edge identities. Index encodings MUST
NOT re-encode edge structure (`from[]`, `to[]`); they reference TGK/1-CORE edges
and carry only routing/filter metadata.

---

## 4. Deterministic Traversal (Normative)

TGK traversal operates over a snapshot/log-bounded view:

* Inputs: `{Snapshot, LogPrefix}` and a seed set (nodes or edges).
* Outputs: only edges visible under the same `{Snapshot, LogPrefix}`.
* Traversal **MUST** be deterministic and replay-compatible with ASL/LOG/1.

Deterministic ordering for traversal output MUST be:

1. `logseq` ascending
2. Canonical Edge Key as tie-break

Acceleration structures MAY be used but MUST NOT change semantics.

---

## 5. Federation Alignment (Normative)

Federation does not change TGK semantics. It only propagates edges and artifacts that are already visible under index rules.

* Domain visibility and publication status are enforced via index metadata (ENC-ASL-CORE-INDEX).
* TGK edges keep canonical identity across domains.
* Cross-domain propagation MUST preserve snapshot/log determinism.

---

## 6. Non-Goals

TGK/1 does not define:

* Edge encoding or storage layout
* Index segment formats
* Query languages or execution plans
* Acceleration rules beyond ASL/INDEX-ACCEL/1

---

## 7. Normative Invariants

Conforming implementations MUST enforce:

1. TGK edges are immutable and indexed objects.
2. No TGK visibility without index admission and log ordering.
3. Traversal is snapshot/log bounded and deterministic.
4. Federation does not alter TGK semantics; it only propagates visible edges.
5. Edge classification is not part of canonical identity.