From f69742dc0b3b91a9de54afcad1ed67ef010c4acb Mon Sep 17 00:00:00 2001 From: Carl Niklas Rydberg Date: Sat, 20 Dec 2025 12:30:53 +0100 Subject: [PATCH] Define TGK edge tag and registry entry --- include/amduat/enc/tgk1_edge.h | 15 ++++++++++ include/amduat/tgk/core.h | 16 ++++++++++ registry/README.md | 1 + registry/type-tag.jsonl | 1 + registry/type-tag.schema.md | 53 ++++++++++++++++++++++++++++++++++ tier1/enc-tgk1-edge-1.md | 10 +++---- tier1/tgk-1-core.md | 18 +++++++++--- 7 files changed, 104 insertions(+), 10 deletions(-) create mode 100644 registry/type-tag.jsonl create mode 100644 registry/type-tag.schema.md diff --git a/include/amduat/enc/tgk1_edge.h b/include/amduat/enc/tgk1_edge.h index e69de29..460b22b 100644 --- a/include/amduat/enc/tgk1_edge.h +++ b/include/amduat/enc/tgk1_edge.h @@ -0,0 +1,15 @@ +#ifndef AMDUAT_ENC_TGK1_EDGE_H +#define AMDUAT_ENC_TGK1_EDGE_H + +#ifdef __cplusplus +extern "C" { +#endif + +enum { TYPE_TAG_TGK1_EDGE_V1 = 0x00000201u }; +enum { AMDUAT_TYPE_TAG_TGK1_EDGE_V1 = TYPE_TAG_TGK1_EDGE_V1 }; + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* AMDUAT_ENC_TGK1_EDGE_H */ diff --git a/include/amduat/tgk/core.h b/include/amduat/tgk/core.h index e69de29..cd30ba5 100644 --- a/include/amduat/tgk/core.h +++ b/include/amduat/tgk/core.h @@ -0,0 +1,16 @@ +#ifndef AMDUAT_TGK_CORE_H +#define AMDUAT_TGK_CORE_H + +#include "amduat/enc/tgk1_edge.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* Core TGK header re-exports encoding constants for convenience. */ + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* AMDUAT_TGK_CORE_H */ diff --git a/registry/README.md b/registry/README.md index 24ecad4..c773a9d 100644 --- a/registry/README.md +++ b/registry/README.md @@ -81,6 +81,7 @@ This uses the generic registry container in `amduat/asl/registry`. - `registry/hash-asl1.jsonl` — ASL1 HashId assignments. - `registry/enc-asl1-core.jsonl` — ASL1 core encoding profile assignments. +- `registry/type-tag.jsonl` — ASL1 TypeTag assignments. ## Design constraints diff --git a/registry/type-tag.jsonl b/registry/type-tag.jsonl new file mode 100644 index 0000000..6f820ed --- /dev/null +++ b/registry/type-tag.jsonl @@ -0,0 +1 @@ +{"registry":"TYPE/ASL1","tag_id":"0x00000201","handle":"amduat.type.asl1.tag.00000201@1","name":"TYPE_TAG_TGK1_EDGE_V1","status":"mandatory","spec_ref":"ENC/TGK1-EDGE/1 v0.1.0","notes":"Canonical TypeTag for TGK1 EdgeArtifacts encoded with ENC/TGK1-EDGE/1.","descriptor_sha256":"5a6c0733433544923a98317e1c3bebfc3e0fb3f9e8ec1975be3d936b417f5990"} diff --git a/registry/type-tag.schema.md b/registry/type-tag.schema.md new file mode 100644 index 0000000..ebc9e79 --- /dev/null +++ b/registry/type-tag.schema.md @@ -0,0 +1,53 @@ +# TYPE/ASL1 Registry Manifest (draft) + +This file documents the JSONL rows in `registry/type-tag.jsonl`. Each line is +one entry descriptor for a single `TypeTag` assignment. The key is the `tag_id` +itself (a concept); the descriptor is data. + +## Field definitions + +- `registry`: string. Constant `"TYPE/ASL1"`. +- `tag_id`: string. Hex `u32` formatted as `0x00000000`. +- `handle`: string. Stable concept handle for this TypeTag assignment, e.g. + `amduat.type.asl1.tag.00000201@1`. +- `name`: string or null. Symbolic tag name if assigned (e.g. + `TYPE_TAG_TGK1_EDGE_V1`). +- `status`: string. One of: `mandatory`, `reserved`, `deprecated`, + `experimental`. +- `spec_ref`: string. Document/version that defines the assignment. +- `notes`: string. Short human-readable note. +- `descriptor_sha256`: string. Lowercase hex SHA-256 digest of the canonical + descriptor (see below). + +## Canonical registry key + +`tag_id` is the registry key. Its key bytes are the big-endian `u32` encoding +defined in `ASL/1-CORE` for `TypeTag.tag_id`. + +## Handle naming scheme + +Handles are opaque identifiers in the `amduat` namespace: + +``` +amduat.type.asl1.tag.@1 +``` + +`hex8` is the 8-digit lowercase hex of the tag ID (zero-padded). + +## Descriptor digest rule + +`descriptor_sha256` is computed as SHA-256 over the UTF-8 bytes of the +canonical JSON object with these fields **in order**: + +``` +registry, tag_id, handle, name, status, spec_ref, notes +``` + +The canonical JSON uses no extra whitespace and does **not** include the +`descriptor_sha256` field itself. + +## Intended use + +- Source of truth for codegen (C tables, enums) and documentation tables. +- `descriptor_sha256` can be treated as the stable digest for mapping entries + into graph references or evidence tables. diff --git a/tier1/enc-tgk1-edge-1.md b/tier1/enc-tgk1-edge-1.md index 1c67b41..b6e3a0f 100644 --- a/tier1/enc-tgk1-edge-1.md +++ b/tier1/enc-tgk1-edge-1.md @@ -454,18 +454,16 @@ Artifact { Where: -* `TYPE_TAG_TGK1_EDGE_V1` is a `TypeTag` whose concrete `tag_id`: - - * is assigned in the global TypeTag registry, and - * is included in the environment’s `EDGE_TAG_SET` when this profile is active. +* `TYPE_TAG_TGK1_EDGE_V1` is `TypeTag{ tag_id = 0x0000_0201 }`, assigned in the + global TypeTag registry (`TYPE/ASL1`, handle `amduat.type.asl1.tag.00000201@1`). +* When this profile is active, the environment’s `EDGE_TAG_SET` **MUST** include + `TYPE_TAG_TGK1_EDGE_V1.tag_id`. ExecutionEnvironments that wish to treat such Artifacts as TGK edges MUST: * include `TYPE_TAG_TGK1_EDGE_V1.tag_id` in their configured `EDGE_TAG_SET`; and * register `TGK1_EDGE_ENC_V1` as the edge-encoding profile for that tag, so that `decode_edge_payload_TGK1_EDGE` is used for those Artifacts’ `bytes`. -This document treats `TYPE_TAG_TGK1_EDGE_V1` symbolically and does not assign a numeric `tag_id`. - ### 5.2 Integration with TGK/1-CORE’s `decode_edge_payload_P` For ExecutionEnvironments that activate `TGK1_EDGE_ENC_V1` for `TYPE_TAG_TGK1_EDGE_V1`, the corresponding `decode_edge_payload_P` function from `TGK/1-CORE §3.2` is: diff --git a/tier1/tgk-1-core.md b/tier1/tgk-1-core.md index 80dc823..aa6d7a5 100644 --- a/tier1/tgk-1-core.md +++ b/tier1/tgk-1-core.md @@ -326,8 +326,16 @@ Formally, for a given snapshot: 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. +> **Configuration origin note (normative)** +> `EDGE_TAG_SET` is an explicit part of the ExecutionEnvironment’s TGK profile set. +> It **MUST** include every `TypeTag.tag_id` bound to an active edge-encoding +> profile, and **MUST** exclude any `TypeTag.tag_id` for which no edge-encoding +> profile is active. For `ENC/TGK1-EDGE/1` (`TGK1_EDGE_ENC_V1`), the bound edge +> tag is `TYPE_TAG_TGK1_EDGE_V1.tag_id = 0x0000_0201` (assigned in `TYPE/ASL1`), +> so environments that activate this profile **MUST** include that tag in +> `EDGE_TAG_SET`. 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. Then, an Artifact `A` is an EdgeArtifact iff: @@ -347,10 +355,12 @@ Artifacts that satisfy the edge-tag and decoding constraints but whose decoded ` TGK/1-CORE does not prescribe: -* a particular `tag_id` for EdgeArtifacts; or +* a particular `tag_id` assignment policy beyond what active edge-encoding + profiles declare; or * a particular encoding for `EdgeBody` into `Artifact.bytes`. -Those are the responsibility of edge encoding profiles and catalogs. +Those are the responsibility of edge encoding profiles and catalogs (e.g., +`ENC/TGK1-EDGE/1` assigns `TYPE_TAG_TGK1_EDGE_V1`). > **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).