From 96bf3f08b3cb37fa454d9929a6c9b449075e3dd6 Mon Sep 17 00:00:00 2001 From: Carl Niklas Rydberg Date: Sat, 20 Dec 2025 12:54:32 +0100 Subject: [PATCH] Register PEL encodings and SchemeRef digest --- include/amduat/enc/pel1_result.h | 15 ++++++++ include/amduat/enc/pel_program_dag.h | 15 ++++++++ include/amduat/enc/pel_trace_dag.h | 15 ++++++++ include/amduat/pel/enc.h | 18 +++++++++ registry/README.md | 8 ++++ registry/enc-pel1.jsonl | 3 ++ registry/enc-pel1.schema.md | 55 ++++++++++++++++++++++++++++ registry/type-tag.jsonl | 4 ++ tier1/pel-program-dag-desc-1.md | 21 +++++++++++ 9 files changed, 154 insertions(+) create mode 100644 include/amduat/enc/pel1_result.h create mode 100644 include/amduat/pel/enc.h create mode 100644 registry/enc-pel1.jsonl create mode 100644 registry/enc-pel1.schema.md diff --git a/include/amduat/enc/pel1_result.h b/include/amduat/enc/pel1_result.h new file mode 100644 index 0000000..cf87590 --- /dev/null +++ b/include/amduat/enc/pel1_result.h @@ -0,0 +1,15 @@ +#ifndef AMDUAT_ENC_PEL1_RESULT_H +#define AMDUAT_ENC_PEL1_RESULT_H + +#ifdef __cplusplus +extern "C" { +#endif + +enum { PEL_ENC_EXECUTION_RESULT_V1 = 0x0103u }; +enum { AMDUAT_PEL_ENC_EXECUTION_RESULT_V1 = PEL_ENC_EXECUTION_RESULT_V1 }; + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* AMDUAT_ENC_PEL1_RESULT_H */ diff --git a/include/amduat/enc/pel_program_dag.h b/include/amduat/enc/pel_program_dag.h index e69de29..2e577a1 100644 --- a/include/amduat/enc/pel_program_dag.h +++ b/include/amduat/enc/pel_program_dag.h @@ -0,0 +1,15 @@ +#ifndef AMDUAT_ENC_PEL_PROGRAM_DAG_H +#define AMDUAT_ENC_PEL_PROGRAM_DAG_H + +#ifdef __cplusplus +extern "C" { +#endif + +enum { PEL_ENC_PROGRAM_DAG_V1 = 0x0101u }; +enum { AMDUAT_PEL_ENC_PROGRAM_DAG_V1 = PEL_ENC_PROGRAM_DAG_V1 }; + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* AMDUAT_ENC_PEL_PROGRAM_DAG_H */ diff --git a/include/amduat/enc/pel_trace_dag.h b/include/amduat/enc/pel_trace_dag.h index e69de29..91694cc 100644 --- a/include/amduat/enc/pel_trace_dag.h +++ b/include/amduat/enc/pel_trace_dag.h @@ -0,0 +1,15 @@ +#ifndef AMDUAT_ENC_PEL_TRACE_DAG_H +#define AMDUAT_ENC_PEL_TRACE_DAG_H + +#ifdef __cplusplus +extern "C" { +#endif + +enum { PEL_ENC_TRACE_DAG_V1 = 0x0102u }; +enum { AMDUAT_PEL_ENC_TRACE_DAG_V1 = PEL_ENC_TRACE_DAG_V1 }; + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* AMDUAT_ENC_PEL_TRACE_DAG_H */ diff --git a/include/amduat/pel/enc.h b/include/amduat/pel/enc.h new file mode 100644 index 0000000..fb1d76d --- /dev/null +++ b/include/amduat/pel/enc.h @@ -0,0 +1,18 @@ +#ifndef AMDUAT_PEL_ENC_H +#define AMDUAT_PEL_ENC_H + +#include "amduat/enc/pel1_result.h" +#include "amduat/enc/pel_program_dag.h" +#include "amduat/enc/pel_trace_dag.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* Umbrella header for PEL encoding profile IDs. */ + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif /* AMDUAT_PEL_ENC_H */ diff --git a/registry/README.md b/registry/README.md index c773a9d..d405c18 100644 --- a/registry/README.md +++ b/registry/README.md @@ -12,6 +12,13 @@ graph mappings later without rewriting identifiers. - **Registry values are data.** Each entry has a descriptor row that is data (name, digest length, status, notes). Values are not treated as concepts. +## Naming conventions + +- **Spec series** use the `/1` form (e.g. `ASL/1-CORE`, `ASL/1-STORE`). +- **Family/registry tokens** use the compact form (e.g. `HASH/ASL1`, + `ENC/ASL1-CORE`, `TYPE/ASL1`). This keeps registry IDs short and aligns with + the existing hash/encoding identifiers. + This matches MS/1: concept handles are stable identifiers; the descriptor bytes are data nodes that can be hashed and referenced. @@ -82,6 +89,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. +- `registry/enc-pel1.jsonl` — PEL encoding profile assignments. ## Design constraints diff --git a/registry/enc-pel1.jsonl b/registry/enc-pel1.jsonl new file mode 100644 index 0000000..9d3e672 --- /dev/null +++ b/registry/enc-pel1.jsonl @@ -0,0 +1,3 @@ +{"registry":"ENC/PEL1","profile_id":"0x0101","handle":"amduat.enc.pel1.profile.0101@1","name":"PEL_ENC_PROGRAM_DAG_V1","version":"0x0200","status":"mandatory","spec_ref":"ENC/PEL-PROGRAM-DAG/1 v0.2.0","notes":"Canonical encoding profile for PEL/PROGRAM-DAG/1 Program Artifacts.","descriptor_sha256":"a47c2022b7e68f54a5644c3ac35397e083c22162265df4af1359379b2729063f"} +{"registry":"ENC/PEL1","profile_id":"0x0102","handle":"amduat.enc.pel1.profile.0102@1","name":"PEL_ENC_TRACE_DAG_V1","version":"0x0100","status":"mandatory","spec_ref":"ENC/PEL-TRACE-DAG/1 v0.1.0","notes":"Canonical encoding profile for PEL/TRACE-DAG/1 Trace Artifacts.","descriptor_sha256":"7bbd936a0bcd5ff9874b9858191bcf586a3ce135b485d49c1f2249cdd081f74f"} +{"registry":"ENC/PEL1","profile_id":"0x0103","handle":"amduat.enc.pel1.profile.0103@1","name":"PEL_ENC_EXECUTION_RESULT_V1","version":"0x0300","status":"mandatory","spec_ref":"ENC/PEL1-RESULT/1 v0.3.0","notes":"Canonical encoding profile for PEL/1 surface ExecutionResult Artifacts.","descriptor_sha256":"f74c0a796ee43fb8e4841c0523b19176cef10bf43a808678eb8ca299a34b3795"} diff --git a/registry/enc-pel1.schema.md b/registry/enc-pel1.schema.md new file mode 100644 index 0000000..d65f9f6 --- /dev/null +++ b/registry/enc-pel1.schema.md @@ -0,0 +1,55 @@ +# ENC/PEL1 Registry Manifest (draft) + +This file documents the JSONL rows in `registry/enc-pel1.jsonl`. Each line is +one entry descriptor for a single PEL encoding profile assignment. The key is +the profile ID (a concept); the descriptor is data. + +## Field definitions + +- `registry`: string. Constant `"ENC/PEL1"`. +- `profile_id`: string. Hex `u16` formatted as `0x0000`. +- `handle`: string. Stable concept handle for this profile assignment, e.g. + `amduat.enc.pel1.profile.0101@1`. +- `name`: string or null. Profile name if assigned (e.g. + `PEL_ENC_PROGRAM_DAG_V1`). +- `version`: string. Hex `u16` encoded version from the descriptor table. +- `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 + +`profile_id` is the registry key. Its key bytes are the big-endian `u16` +encoding defined in `ENC/ASL1-CORE` (see `amduat_enc_asl1_core_key` for the +encoding convention). + +## Handle naming scheme + +Handles are opaque identifiers in the `amduat` namespace: + +``` +amduat.enc.pel1.profile.@1 +``` + +`hex4` is the 4-digit lowercase hex of the profile 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, profile_id, handle, name, version, 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/registry/type-tag.jsonl b/registry/type-tag.jsonl index 6f820ed..ca14fe3 100644 --- a/registry/type-tag.jsonl +++ b/registry/type-tag.jsonl @@ -1 +1,5 @@ +{"registry":"TYPE/ASL1","tag_id":"0x00000100","handle":"amduat.type.asl1.tag.00000100@1","name":"TYPE_TAG_PEL_SCHEME_DESC_1","status":"mandatory","spec_ref":"PEL/PROGRAM-DAG-DESC/1 v0.1.6","notes":"PEL scheme descriptor tag for PEL/PROGRAM-DAG-DESC/1.","descriptor_sha256":"939ebb66e4effbcd5dd74cb872f82b4216a95341309c64f3f0d13ffec5e49f5b"} +{"registry":"TYPE/ASL1","tag_id":"0x00000101","handle":"amduat.type.asl1.tag.00000101@1","name":"TYPE_TAG_PEL_PROGRAM_DAG_1","status":"mandatory","spec_ref":"ENC/PEL-PROGRAM-DAG/1 v0.2.0","notes":"Canonical TypeTag for PEL/PROGRAM-DAG/1 Program Artifacts.","descriptor_sha256":"85c45f422bbea91898aa16922f074aeb50391190a1fed0a1083a859101c5616e"} +{"registry":"TYPE/ASL1","tag_id":"0x00000102","handle":"amduat.type.asl1.tag.00000102@1","name":"TYPE_TAG_PEL_TRACE_DAG_1","status":"mandatory","spec_ref":"ENC/PEL-TRACE-DAG/1 v0.1.0","notes":"Canonical TypeTag for PEL/TRACE-DAG/1 Trace Artifacts.","descriptor_sha256":"e044e3d9423442c51d3a2008a090aeca5575ca5ba30293965dd40c6baa67b3d2"} +{"registry":"TYPE/ASL1","tag_id":"0x00000103","handle":"amduat.type.asl1.tag.00000103@1","name":"TYPE_TAG_PEL1_RESULT_1","status":"mandatory","spec_ref":"ENC/PEL1-RESULT/1 v0.3.0","notes":"Canonical TypeTag for PEL/1 ExecutionResult Artifacts.","descriptor_sha256":"0e90731d9fbb4cddf4a1fae055faad66a19db33eab199e9a53db716ca07cef83"} {"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/tier1/pel-program-dag-desc-1.md b/tier1/pel-program-dag-desc-1.md index 1792b53..9ba2d8a 100644 --- a/tier1/pel-program-dag-desc-1.md +++ b/tier1/pel-program-dag-desc-1.md @@ -659,6 +659,27 @@ In the Amduat 2.0 baseline: * Engines that implement the Amduat 2.0 baseline DAG scheme MUST treat this specific `Reference` as “the” scheme identifier for `PEL/PROGRAM-DAG/1`. +For the baseline registry assignments: + +```text +TYPE_TAG_PEL_SCHEME_DESC_1.tag_id = 0x00000100 +TYPE_TAG_PEL_PROGRAM_DAG_1.tag_id = 0x00000101 +PEL_ENC_PROGRAM_DAG_V1 = 0x0101 +``` + +the canonical bytes and digest are: + +```text +DagSchemeDescriptorBytes_DAG_1 (hex) = + 00010000001150454c2f50524f4752414d2d4441472f310000010101010000 + +ArtifactBytes_DAG_1 (hex) = + 0100000100000000000000001f00010000001150454c2f50524f4752414d2d4441472f310000010101010000 + +digest_DAG_1 = + c50fb2a734a5cc233c3875b70a7d96eaad374f000029771d8bef1af2cd6384dd +``` + ### 5.3 Alternative deployments (non-baseline) Other deployments MAY derive alternative scheme references from: