135 lines
4.1 KiB
Markdown
135 lines
4.1 KiB
Markdown
|
# 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.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 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.
|