159 lines
5 KiB
Markdown
159 lines
5 KiB
Markdown
# 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.
|