amduat/tier1/tgk-1.md

# TGK/1 — Trace Graph Kernel Semantics

Status: Draft
Owner: Architecture
Version: 0.1.0
SoT: No
Last Updated: 2025-11-30
Linked Phase Pack: N/A
Tags: [tgk, determinism, index, federation]

<!-- Source: /amduat-api/tier1/tgk-1.md | Canonical: /amduat/tier1/tgk-1.md -->

**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`
* `TGK/1-CORE`

**Informative references:**

* `ENC/TGK1-EDGE/1` — core edge encoding
* `ENC/TGK-INDEX/1` — index encoding draft
* `ASL/INDEX-ACCEL/1`
* `ENC/ASL-CORE-INDEX/1`

© 2025 Niklas Rydberg.

## License

Except where otherwise noted, this document (text and diagrams) is licensed under
the Creative Commons Attribution 4.0 International License (CC BY 4.0).

The identifier registries and mapping tables (e.g. TypeTag IDs, HashId
assignments, EdgeTypeId tables) are additionally made available under CC0 1.0
Universal (CC0) to enable unrestricted reuse in implementations and derivative
specifications.

Code examples in this document are provided under the Apache License 2.0 unless
explicitly stated otherwise. Test vectors, where present, are dedicated to the
public domain under CC0 1.0.

---

## 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.