niklas/amduat
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat/tier1/tgk-1-core.md
Carl Niklas Rydberg 47e3ccc382 Adding TGK specifications.
2025-12-20 11:32:17 +01:00

672 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# TGK/1-CORE — Trace Graph Kernel (Core)
Status: Approved
Owner: Niklas Rydberg
Version: 0.7.0
SoT: Yes
Last Updated: 2025-11-16
Linked Phase Pack: N/A
Tags: [traceability, execution]
<!-- Source: /amduat/docs/new/tgk.md | Canonical: /amduat/tier1/tgk-1-core.md -->
**Document ID:** `TGK/1-CORE`
**Layer:** L1.5 — Logical graph kernel over ASL/1 (above ASL/1, orthogonal to PEL/1)
**Depends on (normative):**
* `ASL/1-CORE v0.3.x` — value substrate: `Artifact`, `Reference`, `TypeTag`, identity model
**Informative references:**
* `ENC/ASL1-CORE v1.0.x` — canonical encodings for ASL/1 values (`ArtifactBytes`, `ReferenceBytes`)
* `HASH/ASL1 v0.2.x` — ASL1 hash family
* `ASL/1-STORE v0.3.x` — content-addressable store semantics
* `PEL/1` — execution substrate
* `CIL/1`, `FCT/1`, `FER/1`, `OI/1` — higher-layer profiles built on top of TGK/1
* (future) `ENC/TGK1-EDGE` — canonical edge-encoding profile
* (future) `TGK/STORE/1` — graph store and query semantics
* (future) `TGK/PROV/1` — provenance and trace semantics
> **Versioning note**
> TGK/1-CORE is agnostic to minor revisions of these informative documents, provided they preserve:
>
> * the ASL/1-CORE definitions of `Artifact`, `Reference`, and `TypeTag`, and
> * the existence of canonical encodings and hash families consistent with that model.
© 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
### 0.1 RFC 2119 terminology
The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**,
**SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** are to be
interpreted as described in RFC 2119.
### 0.2 Terms from ASL/1
This specification reuses the following terms from `ASL/1-CORE`:
* **Artifact** — immutable logical value:
```text
Artifact {
bytes: OctetString
type_tag: optional TypeTag
}
```
* **Reference** — content address (logical identity handle) for an Artifact:
```text
Reference {
hash_id: HashId
digest: OctetString
}
```
* **TypeTag** — opaque `uint32` identifying intended interpretation of an Artifact.
* **HashId** — `uint16` identifying a hash algorithm (e.g. from `HASH/ASL1`).
Where this document says **ArtifactRef**, it means an ASL/1 `Reference` that (logically) points to an `Artifact`. TGK/1-CORE does **not** assume the corresponding Artifact is present or retrievable in any particular store.
### 0.3 Additional terminology
* **Node** — synonym for an ASL/1 `Reference` when used as a graph vertex.
* **EdgeBody** — the logical structure of a TGK edge (see §2.2).
* **EdgeArtifact** — an ASL/1 `Artifact` whose payload logically encodes an `EdgeBody` (see §3).
* **EdgeRef** — the ASL/1 `Reference` to an `EdgeArtifact`.
* **EdgeTypeId** — `uint32` identifying the semantic type of an edge (see §2.3).
* **ProvenanceGraph** — the logical graph derived from a set of Artifacts and TGK/1 edge semantics (see §4).
* **ExecutionEnvironment** — a concrete deployment context characterized by:
* a **logical snapshot**: a finite set of Artifacts visible at that point in time; and
* a fixed configuration of TGK-related profiles (edge encodings, type catalogs, provenance policies, etc.) “in effect” at that snapshot.
All invariants and uniqueness claims are evaluated with respect to such a finite snapshot.
> **Source-agnostic note (informative)**
> The `Artifacts` set for a snapshot may be aggregated from any combination of ASL/1-STORE instances, archives, exports, or other sources. TGK/1-CORE is indifferent to where Artifacts come from or how they are stored; it operates purely on their logical values and `Reference`s.
TGK/1-CORE defines only **logical structures** and their equality / identity semantics. Physical storage, indexes, query APIs, and provenance algorithms are defined by separate profiles.
---
## 1. Purpose, Scope & Non-Goals
### 1.1 Purpose
`TGK/1-CORE` defines the **minimal logical graph kernel over ASL/1 Artifacts**.
It provides:
* A definition of:
* **Nodes** as ASL/1 `Reference` values (ArtifactRefs); and
* **Edges** as EdgeArtifacts whose payloads decode to `EdgeBody` values.
* A way to view any snapshot of an ExecutionEnvironment (finite set of Artifacts + configured profiles) as a **ProvenanceGraph** that is a **pure projection** over:
* immutable Artifacts (including edge Artifacts), and
* published edge-type specifications and encoding profiles.
* A base vocabulary that higher profiles (PEL/1 integration, certification, facts, overlays, provenance) can use to declare:
* how they encode their relationships into edge Artifacts; and
* how provenance traces are computed as projections over the resulting graph.
In other words:
> TGK/1-CORE makes “graph over artifacts” a first-class, **purely logical** notion, with all evidence residing in ASL/1 Artifacts.
> **TGK/EDGE-AS-ARTIFACT/CORE/1**
> All TGK edges **MUST** be represented as ASL/1 Artifacts (“EdgeArtifacts”), and all references to edges **MUST** be ordinary ASL `Reference`s (“EdgeRef”). TGK/1-CORE **MUST NOT** introduce any separate identity scheme for edges.
### 1.2 Provenance kernel invariant & determinism
> **TGK/PROV-KERNEL/CORE/1**
> For any ExecutionEnvironment considered at a particular **logical snapshot** (a finite set of Artifacts and the profile set in effect at that point):
>
> * the corresponding `ProvenanceGraph` (as defined in §4) is a **pure function** of:
>
> * that Artifact set, and
> * the profiles’ decoding / edge-derivation rules; and
> * any persisted graph indexes or materialized views are **optimizations only** and **MUST** be consistent with this projection.
> **TGK/DET/CORE/1**
> For a fixed snapshot and fixed profile set, any two TGK/1-CORE–conformant implementations **MUST** derive isomorphic `ProvenanceGraph`s (identical edge and node sets, up to set equality). No aspect of the graph may depend on wall-clock time, process identity, storage layout, or other non-declared environment state.
> **TGK/NO-OFF-GRAPH-PROV/CORE/1**
> Any relationship that is intended to participate in TGK-level provenance **MUST** be representable as:
>
> * an EdgeArtifact whose payload decodes to an `EdgeBody`, and
> * Nodes (ASL `Reference`s) in its `from` / `to` / `payload` fields.
>
> TGK/1-CORE and its profiles **MUST NOT** rely on hidden, mutable, non-Artifactual state to represent provenance-relevant relationships.
TGK/1-CORE itself does **not** define a particular provenance algorithm; that is the role of `TGK/PROV/1` and higher-layer profiles.
### 1.3 Non-goals
TGK/1-CORE explicitly does **not** define:
* Canonical binary encodings or hashing rules for edges (delegated to edge-encoding profiles such as `ENC/TGK1-EDGE` and the ASL substrate stack).
* Store APIs, physical graph storage, or indexing strategies (delegated to `TGK/STORE/1` and implementation design).
* Error codes, authorization, or transport protocols.
* A query or provenance language (delegated to `TGK/PROV/1`, overlays, or higher-level APIs).
* Global registration or semantics of particular `EdgeTypeId` values (delegated to catalogs and profiles).
TGK/1-CORE is a **logical kernel** only.
### 1.4 Layering and dependencies
TGK/1-CORE sits:
* **Above ASL/1-CORE**:
* Reuses `Artifact`, `Reference`, `TypeTag`, and identity semantics.
* Treats edge data as Artifacts; edge identities are ordinary `Reference`s.
* **Orthogonal to PEL/1**:
* MAY model PEL/1 executions as edges (via profiles).
* Does not impose runtime behavior on PEL/1 engines.
#### 1.4.1 Layering invariant with PEL/1
**TGK/PEL-LAYERING-INV/CORE/1**
* TGK/1-CORE **MUST NOT** impose additional runtime behavior or API obligations on conformant PEL/1 engines beyond those defined in `PEL/1`.
* Any TGK edges that describe PEL/1 executions **MUST** be derivable solely from stored ASL/1 Artifacts (programs, inputs, execution results, receipts) and published specifications.
* Whether a PEL/1 implementation emits edge Artifacts directly is an implementation detail and is **not** part of PEL/1 conformance.
---
## 2. Core Graph Model
### 2.1 Node
A **Node** in TGK/1-CORE is any ASL/1 `Reference`:
```text
Node := Reference // i.e., an ArtifactRef
```
Properties:
* Nodes are identified **only** by their `Reference` value.
* TGK/1-CORE does not distinguish “edge nodes” vs “data nodes”; that is a profile-level notion.
* There is no separate node ID layer; there are no node identifiers beyond `Reference`.
* The presence of a Node in the ProvenanceGraph is implied by its appearance in any TGK edge’s `from`, `to`, or `payload` fields (see §4.1).
> **Edges-over-edges note (informative)**
> Because Nodes are plain `Reference`s, they can point to any Artifact, including EdgeArtifacts. TGK/1-CORE therefore allows edges-over-edges (meta-edges that describe or govern other edges). The semantics of such patterns are determined by the profiles that define the relevant `EdgeTypeId` values.
### 2.2 EdgeBody
An **EdgeBody** is the logical content of a TGK edge:
```text
EdgeBody {
type: EdgeTypeId
from: Node[] // ordered, MAY be empty
to: Node[] // ordered, MAY be empty
payload: Reference // ArtifactRef, always present
}
```
Semantics and invariants:
* `type : EdgeTypeId`
Identifies the **kind** of relationship (e.g., execution, attestation, overlay mapping). Semantics of each `EdgeTypeId` are defined in separate specifications, not by TGK/1-CORE.
* `from : Node[]`
Ordered list of source nodes. MAY be empty. Order is semantically significant and part of the logical value.
* `to : Node[]`
Ordered list of target nodes. MAY be empty. Order is semantically significant.
* `payload : Reference`
A syntactically valid ASL/1 `Reference`, always present. TGK/1-CORE does **not** require that `payload` be resolvable in any particular store; existence is a deployment concern.
* **Non-emptiness constraint**
> **TGK/EDGE-NONEMPTY-ENDPOINT/CORE/1**
> For a well-formed `EdgeBody`, at least one of `from` or `to` **MUST** be non-empty. An `EdgeBody` with `from = []` **and** `to = []` is invalid and MUST NOT be produced or accepted as a TGK edge.
> **TGK/PROV-EVIDENCE/CORE/1 (RECOMMENDED)**
> To support provenance, edge types that describe “how we got here” **SHOULD** ensure that:
>
> * `payload` references an Artifact whose content is a stable, replayable description of the relationship; and
> * the `from` and `to` node sets can, in principle, be recomputed from that payload and other Artifacts in the environment, according to the edge type’s profile.
>
> In edge types that use minimal descriptors as payload, those descriptors **SHOULD** themselves be defined such that their content is a deterministic function of the other Artifacts and parameters that define the relationship, so that edge Artifacts can always be re-derived.
**Duplicates and self-reference**
TGK/1-CORE does not forbid:
* duplicate entries within `from`,
* duplicate entries within `to`, or
* `payload` also appearing in `from` or `to`.
The semantics (if any) of such patterns are defined by the profiles that own the relevant `EdgeTypeId`. The kernel only requires that:
* `from` and `to` are ordered lists of syntactically valid ASL/1 `Reference`s; and
* they obey TGK/EDGE-NONEMPTY-ENDPOINT/CORE/1.
TGK/1-CORE does **not** constrain how `EdgeBody` values are encoded into `Artifact.bytes`; this is the role of encoding profiles like `ENC/TGK1-EDGE`.
### 2.3 EdgeTypeId
`EdgeTypeId` identifies the semantic type of an edge:
```text
EdgeTypeId = uint32
```
Constraints:
* For any given ExecutionEnvironment snapshot, each `EdgeTypeId` that appears in TGK edges **MUST** have a single, well-defined and immutable semantics within that environment.
* TGK/1-CORE does not prescribe a global registration mechanism or reserved ranges.
* Catalogs such as `TGK/TYPES-CORE` typically bind `EdgeTypeId` values to human-readable names, owning profiles, and structural constraints (e.g. allowed cardinalities of `from` / `to`), but TGK/1-CORE does not standardize that surface.
**Unknown types**
* If an ExecutionEnvironment encounters an Artifact whose payload decodes to an `EdgeBody` whose `type` is not recognized in its configured catalogs/profile set, it **MUST** treat that Artifact as **not** forming a TGK edge for that environment:
* that Artifact does **not** qualify as an `EdgeArtifact` under §3.1; and
* it therefore contributes no edges or nodes to the ProvenanceGraph.
> **Environment-relative semantics (informative)**
> Recognition of `EdgeTypeId` values depends on the ExecutionEnvironment’s configured catalogs and profiles. As a result, the exact set of TGK edges derived from a fixed set of Artifacts may differ between environments. TGK/1-CORE considers this expected: the kernel guarantees determinism only *relative* to a given snapshot + profile set, not across all possible environments.
---
## 3. Edge Artifacts and Decoding
TGK/1-CORE uses **EdgeArtifacts** as the only concrete representation of edges.
### 3.1 EdgeArtifact definition
An **EdgeArtifact** is any ASL/1 `Artifact` that, relative to a given ExecutionEnvironment snapshot:
1. Has a `type_tag` whose `tag_id` is recognized (by the local profile set) as an edge tag; and
2. Has `bytes` that, under at least one applicable edge encoding profile, decode to a single well-formed `EdgeBody` value as defined in §2.2; and
3. Has an `EdgeBody.type` that is recognized (by the local profile set) as a supported `EdgeTypeId` for this environment (see §2.3).
Formally, for a given snapshot:
* Let `EDGE_TAG_SET` be the set of `TypeTag.tag_id` values configured as TGK edge tags.
* For each active edge encoding profile `P` in the environment:
* `P` provides a **partial** decoding function:
```text
decode_edge_payload_P : OctetString -> EdgeBody | error
```
which is a pure function of its input bytes.
> **Configuration origin note (informative)**
> `EDGE_TAG_SET` is derived from the ExecutionEnvironment’s configured TGK-related profiles and catalogs (e.g., `TGK/TYPES-CORE`, `ENC/TGK1-EDGE`), and/or from explicit deployment configuration. TGK/1-CORE does not prescribe how this configuration is stored, distributed, or governed; it only assumes that, for any snapshot, there is a well-defined set of `TypeTag.tag_id` values considered edge tags. In many deployments, one or more `TypeTag` values (e.g., a `TGK_EDGE_V1` tag) will be reserved specifically for edge Artifacts, but this is a convention, not a kernel requirement.
Then, an Artifact `A` is an EdgeArtifact iff:
* `A.type_tag` is present and `A.type_tag.tag_id ∈ EDGE_TAG_SET`; and
* there exists at least one active profile `P` such that:
```text
decode_edge_payload_P(A.bytes) = EdgeBody E // succeeds, no error
```
where `E` is a well-formed `EdgeBody` per §2.2; and
* `E.type` is recognized in the environment as a supported `EdgeTypeId` for TGK purposes (see §2.3).
Artifacts that satisfy the edge-tag and decoding constraints but whose decoded `EdgeBody.type` is not recognized as a supported `EdgeTypeId` for this environment MUST NOT be treated as EdgeArtifacts (see §2.3).
TGK/1-CORE does not prescribe:
* a particular `tag_id` for EdgeArtifacts; or
* a particular encoding for `EdgeBody` into `Artifact.bytes`.
Those are the responsibility of edge encoding profiles and catalogs.
> **Single-edge-per-artifact invariant (informative)**
> TGK/1-CORE assumes each EdgeArtifact encodes exactly one `EdgeBody` and thus one logical edge. Bundling multiple logical edges into a single Artifact is outside the TGK/1-CORE model and, if needed, **SHOULD** be expressed as multiple EdgeArtifacts (e.g., via an index or bundle Artifact that refers to other EdgeArtifacts).
> **Environment-relative edgehood (informative)**
> An Artifact can be an EdgeArtifact in one ExecutionEnvironment (given its profile set) and not in another. TGK/1-CORE defines edgehood relative to the configured profiles, not as an intrinsic property of the Artifact alone.
### 3.2 Edge decoding and multi-profile behavior
For each active edge encoding profile `P`:
* The function `decode_edge_payload_P` **MUST** be:
* **partial** — returns either:
* a successfully decoded `EdgeBody`, or
* an error signaling “not a valid edge payload for this profile”;
* **deterministic** — no hidden state, randomness, or external configuration affects its output.
Additional constraints:
* For Artifacts whose `type_tag.tag_id ∉ EDGE_TAG_SET`, all edge encoding profiles **MUST** treat `decode_edge_payload_P` as not applicable (always error) and **MUST NOT** attempt to reinterpret arbitrary non-edge-tag Artifacts as TGK edges.
* For Artifacts whose `type_tag.tag_id ∈ EDGE_TAG_SET`:
* It is **permitted** that some active profiles do not apply (they simply return an error).
* If more than one active profile successfully decodes `A.bytes`, then all those profiles **MUST** decode to the **same** logical `EdgeBody` value. If two active profiles decode the same Artifact to different `EdgeBody` values, the ExecutionEnvironment is misconfigured and **MUST NOT** treat that Artifact as an EdgeArtifact until the conflict is resolved.
> **TGK/EDGE-PROFILE-RECOMMEND/CORE/1 (RECOMMENDED)**
> For operational simplicity, ExecutionEnvironments **SHOULD** configure at most one active edge-encoding profile for any given edge `TypeTag.tag_id` at a time. When multiple profiles may apply to the same EdgeArtifacts (e.g., during a migration), they **MUST** be governed so that any Artifact accepted by more than one profile decodes to the same `EdgeBody`.
### 3.3 EdgeRef
An **EdgeRef** is simply the ASL/1 `Reference` to an EdgeArtifact:
```text
EdgeRef := Reference // reference to an EdgeArtifact
```
Properties:
* No new identity scheme is introduced for edges.
* The identity and equality of EdgeArtifacts and EdgeRefs are fully governed by ASL/1-CORE (canonical encoding + hashing via `ENC/ASL1-CORE` and `HASH/ASL1`).
* For a fixed canonical Artifact encoding and hash profile:
* equality of EdgeRefs is equivalent to equality of the underlying EdgeArtifacts; and
* by injective edge encodings in the applicable encoding profile, equivalent (modulo cryptographic collision assumptions) to equality of their logical `EdgeBody` values.
> **Duplicate logical edges (informative)**
> In most deployments, a given logical edge type and encoding will produce a unique EdgeArtifact for a given `EdgeBody`, because canonical encoding + ASL hashing make that Artifact and its `Reference` unique. Distinct `EdgeRef` values that encode semantically equivalent relationships can still arise if different `TypeTag` / encoding / profile combinations are used to express the same relationship. TGK/1-CORE does not attempt to normalize such cases; higher-layer profiles MAY choose to detect or coalesce them.
> **Store interaction note (informative)**
> Any ASL/1-STORE that holds EdgeArtifacts can be used to resolve `EdgeRef` via normal `get(Reference)` semantics. TGK/1-CORE does not define a separate persistence layer for edges; they are ordinary Artifacts as far as ASL/1-STORE is concerned.
### 3.4 Relationship between EdgeArtifact and EdgeBody
For each EdgeArtifact:
```text
A_edge : Artifact
Ref_edge : Reference // derived per ASL/1-CORE
Body : EdgeBody // Body = EdgeBody(A_edge) via the unique decoding result
```
The mapping `EdgeBody(A_edge)` is determined by the environment’s active profiles and MUST obey the determinism and well-formedness constraints above.
Encoding profiles such as `ENC/TGK1-EDGE` define:
* the concrete layout of `EdgeBody` into `Artifact.bytes`; and
* how `TypeTag` values map to particular edge schemas.
---
## 4. ProvenanceGraph as Projection
### 4.1 Graph derived from Artifacts
Given:
* a finite snapshot set of Artifacts `Artifacts`; and
* a fixed set of active edge-encoding profiles and type catalogs (the **profile set**) in an ExecutionEnvironment,
the **ProvenanceGraph** induced by `Artifacts` and the profile set is the pair:
```text
ProvenanceGraph {
Nodes: set<Node>
Edges: set<(EdgeRef, EdgeBody)>
}
```
defined as follows:
1. **Edges**
* Let `EdgeArtifacts ⊆ Artifacts` be the subset of Artifacts that qualify as EdgeArtifacts under §3.1 and §3.2.
* For each `A_edge ∈ EdgeArtifacts`:
* Let `Ref_edge` be its ASL `Reference`.
* Let `Body = EdgeBody(A_edge)` be the decoded `EdgeBody`.
Then:
```text
Edges = { (Ref_edge, Body) | A_edge ∈ EdgeArtifacts }
```
2. **Nodes**
Nodes are all ArtifactRefs that appear anywhere in edges:
```text
Nodes = {
n : Reference |
∃ (Ref_edge, Body) ∈ Edges such that
n ∈ Body.from ∪ Body.to ∪ { Body.payload }
}
```
Clarifications:
* The `Nodes` set includes only `Reference`s that participate in at least one edge as source, target, or payload.
* Artifacts (and their References) that have no incoming or outgoing edges are **not** included in the ProvenanceGraph by TGK/1-CORE. Profiles MAY define derived views that treat all Artifacts as degree-zero nodes, but this is outside the TGK/1-CORE kernel.
* TGK/1-CORE does **not** require that every `Node` in `Nodes` correspond to an Artifact present in the `Artifacts` set. The ProvenanceGraph is a graph over the **Reference space**. Whether a given `Reference` is resolvable to an Artifact in a particular store or federation is outside this kernel and is governed by `ASL/1-STORE` and deployment policy.
> **TGK/GRAPH-PROJECTION/CORE/1**
> For a fixed snapshot set of Artifacts and a fixed profile set, the ProvenanceGraph, as defined above, is unique. Implementations MAY cache or index edges and nodes, but **MUST NOT** introduce logical edges that cannot be derived from EdgeArtifacts and the profiles in effect at that snapshot.
### 4.2 Informative: provenance traces
TGK/1-CORE does **not** define provenance or trace operations normatively. However, it is intended to be the substrate for:
* `TGK/PROV/1`, which defines:
* provenance policies (e.g., “which edge types participate”), and
* trace operators (e.g., backwards reachability) over `ProvenanceGraph`.
As an informative sketch, a backwards provenance operator would:
* start from a set of target `Node`s (ArtifactRefs); and
* walk backwards along edges whose `EdgeTypeId` are selected by some policy,
* until reaching nodes that are considered roots by that policy.
Any such operator **MUST**, when specified in `TGK/PROV/1`, be defined purely as a projection over `ProvenanceGraph`, consistent with `TGK/PROV-KERNEL/CORE/1`, `TGK/DET/CORE/1`, and `TGK/NO-OFF-GRAPH-PROV/CORE/1`.
---
## 5. Interaction with Other Layers (Informative)
### 5.1 Interaction with PEL/1
A PEL/1 execution typically involves:
* a `Program` ArtifactRef,
* zero or more input ArtifactRefs,
* an `ExecutionResult` ArtifactRef that references output ArtifactRefs.
A profile such as `TGK/PEL/1` can define:
* a specific `EdgeTypeId` (e.g., `EDGE_EXECUTION`); and
* an edge encoding that maps PEL/1 execution payloads to an `EdgeBody`:
```text
EdgeBody.type = EDGE_EXECUTION
EdgeBody.from = [program_ref] ∪ input_refs[]
EdgeBody.to = output_refs[] ∪ [execution_result_ref]
EdgeBody.payload = execution_result_ref
```
Then, for each execution, an EdgeArtifact is produced (by the runtime or an ingestion tool) with:
* a TGK edge `TypeTag`, and
* a payload encoding that an edge profile (e.g., `ENC/TGK1-EDGE`) decodes to such an `EdgeBody`.
The resulting ProvenanceGraph expresses execution relationships as edges over ArtifactRefs.
TGK/1-CORE does not require PEL/1 engines to emit such edge Artifacts; they MAY be derived post hoc from stored Artifacts.
### 5.2 Interaction with CIL/1
CIL/1 defines certificate Artifacts. A profile (e.g., `TGK/CIL/1`) can specify:
* `EdgeTypeId = EDGE_ATTESTS`.
For each certificate Artifact `cert_ref` whose subject is `subject_ref`:
```text
EdgeBody.type = EDGE_ATTESTS
EdgeBody.from = [cert_ref]
EdgeBody.to = [subject_ref]
EdgeBody.payload = cert_ref
```
EdgeArtifacts that encode these `EdgeBody` values make certificate relationships explicit in the ProvenanceGraph.
TGK/1-CORE itself does not verify signatures or policies; CIL/1 and governance profiles do.
### 5.3 Interaction with FCT/1, FER/1, OI/1
Profiles can similarly define:
* evidence-to-fact edges (e.g., `EDGE_FACT_SUPPORTS`),
* overlay mapping edges (e.g., `EDGE_OVERLAY_MAPS`),
* other domain relationships.
The common pattern is:
* define an `EdgeTypeId`;
* define how to encode a logical `EdgeBody` into an EdgeArtifact payload;
* derive the graph as in §4.1.
TGK/1-CORE itself is agnostic to those semantics.
---
## 6. Conformance
An implementation is **TGK/1-CORE–conformant** if and only if it satisfies all of the following:
1. **Node model**
* Treats any ASL/1 `Reference` as a potential Node (`Node := Reference`).
* Does not introduce a separate node identity layer for TGK purposes.
2. **Edge artifacts and decoding**
* Defines (via configuration or companion specs) which `TypeTag.tag_id` values represent TGK edge Artifacts (`EDGE_TAG_SET`).
* For each active edge encoding profile `P`, provides a partial, deterministic decoder:
```text
decode_edge_payload_P : OctetString -> EdgeBody | error
```
that:
* succeeds (returns `EdgeBody`) exactly for payloads considered valid edges under profile `P`; and
* returns an error otherwise.
* For any Artifact `A` with `A.type_tag.tag_id ∉ EDGE_TAG_SET`, all edge profiles **MUST** treat `decode_edge_payload_P` as not applicable (always error) and **MUST NOT** attempt to interpret `A.bytes` as a TGK edge payload.
* For any Artifact `A` with `A.type_tag.tag_id ∈ EDGE_TAG_SET`:
* `A` is an EdgeArtifact only if at least one active profile successfully decodes `A.bytes` to a well-formed `EdgeBody` whose `type` is recognized as a supported `EdgeTypeId` in the environment.
* If more than one active profile decodes `A.bytes` successfully, they **MUST** all decode it to the same logical `EdgeBody`. If they do not, the environment **MUST NOT** treat `A` as an EdgeArtifact until the inconsistency is resolved.
3. **EdgeBody invariants**
* Treats as well-formed only those `EdgeBody` values that satisfy §2.2:
* `from` and `to` are ordered lists of syntactically valid ASL/1 `Reference`s;
* they satisfy TGK/EDGE-NONEMPTY-ENDPOINT/CORE/1; and
* `payload` is always a syntactically valid ASL/1 `Reference` and always present.
* Edge encoding profiles **MUST** reject payloads that would decode to an `EdgeBody` violating these invariants.
4. **Graph projection**
* Given:
* a finite snapshot set of Artifacts; and
* the configured edge tags + decoding rules (profile set),
* it can construct the ProvenanceGraph as in §4.1:
* Edge set derived from EdgeArtifacts;
* Node set derived from `from`, `to`, and `payload` fields of `EdgeBody` values.
* Any graph indexes or caches it exposes **MUST** be consistent with this projection (`TGK/GRAPH-PROJECTION/CORE/1`, `TGK/DET/CORE/1`).
5. **Immutability**
* Treats EdgeArtifacts as immutable, as required by ASL/1-CORE.
* Does not attempt to “edit” an edge in place; logical changes **MUST** be represented by new Artifacts (edge Artifacts and/or other Artifacts) rather than mutating existing ones.
6. **Layering invariant with PEL/1**
* Respects `TGK/PEL-LAYERING-INV/CORE/1`:
* Does not impose additional requirements on PEL/1 engines beyond those in `PEL/1`.
* Allows PEL/1-related edge profiles to be implemented either by the runtime or by ingestion tools, without affecting PEL/1 conformance.
7. **Profile compatibility**
* If it claims to implement specific TGK-related profiles (e.g., `TGK/PEL/1`, `TGK/CIL/1`, `TGK/PROV/1`), it **MUST**:
* interpret `EdgeTypeId` and edge payloads according to those profiles; and
* ensure that all edges defined by those profiles can be represented as EdgeArtifacts consistent with TGK/1-CORE.
Everything else — canonical encodings for `EdgeBody`, edge hashing, graph store APIs, provenance algorithms, error models — belongs to:
* edge encoding profiles (`ENC/TGK1-EDGE`),
* storage/query profiles (`TGK/STORE/1`), and
* provenance profiles (`TGK/PROV/1`) and higher semantic layers (`FCT/1`, `FER/1`, `OI/1`, etc.).
---
## 7. Evolution (Informative)
TGK/1-CORE is intended to evolve **additively**:
* New edge types are introduced by assigning new `EdgeTypeId` values in catalogs and profiles.
* New edge tags are introduced by assigning new `TypeTag.tag_id` values to EdgeArtifacts.
* New encodings are introduced by adding new edge encoding profiles and decoders.
Existing EdgeArtifacts and their decoded `EdgeBody` values:
* **MUST NOT** be retroactively reinterpreted to have different logical meaning under TGK/1-CORE; and
* **MUST** remain valid inputs to any future profile sets that claim to support their `TypeTag` and `EdgeTypeId`, subject to the multi-profile behavior rules in §3.2.
Introducing a new edge-encoding profile that begins to treat previously non-edge Artifacts (e.g., with a new `TypeTag` or a previously unused `EdgeTypeId`) as EdgeArtifacts is allowed and considered an additive extension.
It is **not** permitted to change an existing profile or catalog in a way that causes an Artifact that previously decoded to a given `EdgeBody` (under a given `(TypeTag, EdgeTypeId)` and profile set) to be decoded to a different `EdgeBody` in the same environment. Such changes **SHOULD** instead be modeled via new `TypeTag` values and/or new `EdgeTypeId` assignments.
This aligns TGK/1-CORE with the broader Amduat design principle of **“never rewrite history; evolve by addition and projection.”**
---
## Document History
* **0.7.0 (2025-11-16):** Registered as Tier-1 spec and aligned to the Amduat 2.0 substrate baseline.
Reference in a new issue View git blame Copy permalink