Carl Niklas Rydberg 49fa2955cd docs: refine stack overview to repo stack

2025-12-22 12:54:51 +01:00

29 KiB

Raw Permalink Blame History

SUBSTRATE/STACK-OVERVIEW — Amduat 2.0 Substrate Stack

Document ID: SUBSTRATE/STACK-OVERVIEW Layer: Overview (Tier-1 orientation) Status: Approved (Tier-1 orientation; non-normative behaviour) Version: 0.4.2 Last updated: 2025-12-22

Depends on (normative):

ASL/1-CORE v0.4.x — Artifact substrate (value model)
ENC/ASL1-CORE v1.0.x — canonical encoding profile (ASL_ENC_CORE_V1)
HASH/ASL1 v0.2.4 — ASL1 hash family & registry
ASL/1-STORE v0.4.x — store semantics

References (up-stack / kernel & profiles):

PEL/1-CORE v0.3.x — Primitive Execution Layer (core semantics)
PEL/1-SURF v0.2.x — PEL store-backed execution surface
PEL/PROGRAM-DAG/1 v0.3.x — DAG scheme over PEL/1-CORE
PEL/PROGRAM-DAG-DESC/1 v0.1.x — scheme descriptor binding DAG scheme to an ASL/1 SchemeRef
PEL/TRACE-DAG/1 v0.1.x — DAG execution trace profile
ENC/PEL-PROGRAM-DAG/1 v0.2.x — canonical encoding for DAG programs
ENC/PEL-TRACE-DAG/1 v0.1.x — canonical encoding for DAG traces
OPREG/PEL1-KERNEL v0.1.x — kernel operation registry for PEL/1
OPREG/PEL1-KERNEL-PARAMS/1 v0.1.x — kernel operation parameter encodings
TGK/1-CORE v0.7.x — Trace Graph Kernel (core semantics)
ENC/TGK1-EDGE/1 v0.1.x — canonical encoding for TGK EdgeArtifacts
TGK/STORE/1 v0.2.x — graph store & query semantics over TGK/1-CORE
TGK/PROV/1 v0.1.x — provenance & trace semantics over TGK/1-CORE

Normativity note This document is Approved as a Tier-1 orientation surface. It is structurally normative for dependency and layering (what may depend on what) but does not introduce new behavioural rules beyond the referenced specs.

Scope note (v0.4.0) This revision relocates the stack map into /amduat/tier1/ and locks it to the Amduat 2.0 kernel scope. Certification, receipt, fact, and overlay profiles are explicitly deferred to later phases.

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. Purpose

This document is a short, shared map of the Amduat 2.0 substrate:

what the core layers are,
what each layer is responsible for (and not responsible for),
how they depend on one another.

It is the “you are here” page for kernel work and substrate profiles; detailed behaviour is defined in the referenced specs.

1. Design North Star

The substrate exists to make computing deterministic, inspectable, and replayable.

Key invariants:

Immutable artifacts, content-addressed identity Everything that matters is an immutable Artifact; identity is (hash_id, digest) over a canonical encoding.
Tiny kernel, rich profiles The kernel covers:
- Artifacts (values) — ASL/1-CORE
- pure execution — PEL/1-CORE
- graph semantics — TGK/1-CORE
Meaning (facts, receipts, overlays, policy) lives in profiles above.
Single logical provenance graph All relationships (execution, certs, overlays, facts, annotations) appear as typed edges in one logical graph over artifact IDs (References), via TGK/1-CORE. EdgeArtifacts are ordinary Artifacts; their identities are ordinary References.
Additive evolution, no history rewrites
- New capabilities are introduced via new versioned surfaces (new specs, new profile IDs, new type tags).
- Existing artifacts remain valid under their original versions.
- Canonical encodings (e.g. ASL_ENC_CORE_V1, PEL_ENC_PROGRAM_DAG_V1, TGK1_EDGE_ENC_V1) are never changed in place.
Storage-neutral, policy-neutral kernel
- No special filesystem, database, or policy model is assumed.
- Stores, transports, and policies are layered around the substrate via adapters and profiles.

2. Layered Stack (Overview)

At a high level:

Kernel (value + compute + graph)
- ASL/1-CORE — values
- PEL/1-CORE — primitive execution
- TGK/1-CORE — trace graph kernel
Near-core substrate & graph store profiles
- ENC/ASL1-CORE — canonical encoding for Artifact / Reference
- HASH/ASL1 — hash family & HashId registry
- ASL/1-STORE — store semantics
- ENC/TGK1-EDGE/1 — canonical encoding for TGK edges (EdgeArtifacts)
- TGK/STORE/1 — graph store & basic query semantics over the TGK provenance graph
- TGK/PROV/1 — provenance & trace semantics over ProvenanceGraph (pure functions over TGK/1-CORE)
Canonical PEL/1 execution stack (L1 profiles)
- PEL/1-SURF — store-backed execution surface over ASL/1-STORE
- PEL/PROGRAM-DAG/1 — DAG program scheme over PEL/1-CORE
- PEL/PROGRAM-DAG-DESC/1 — scheme descriptor binding DAG programs to a concrete SchemeRef and Program TypeTag/encoding
- PEL/TRACE-DAG/1 — DAG execution trace profile
- ENC/PEL-PROGRAM-DAG/1 — canonical encoding for DAG programs
- ENC/PEL-TRACE-DAG/1 — canonical encoding for DAG traces
- OPREG/PEL1-KERNEL — kernel operation set
- OPREG/PEL1-KERNEL-PARAMS/1 — canonical param encodings for kernel ops
Profiles above kernel + near-core — out of scope for this version to keep the focus on the Amduat 2.0 kernel contract. Certification, receipt, fact, overlay, and domain profiles return in later phases.

Below is a more explicit breakdown.

3. Kernel

3.1 ASL/1-CORE — Artifact Substrate (L0)

Document: ASL/1-CORE

Defines the logical value model:

Artifact {
  bytes:    OctetString
  type_tag: optional TypeTag
}

TypeTag {
  tag_id: uint32
}

Reference {
  hash_id: HashId
  digest:  OctetString
}

HashId = uint16

Responsibilities:

What an Artifact is.
How identity is defined via encoding profile + hash algorithm:
- EncodingProfileId (e.g. ASL_ENC_CORE_V1)
- HashId (e.g. 0x0001 = HASH-ASL1-256)
Separation of logical values from physical representation.

Not responsible for:

Encoding bytes on wire or disk (that’s ENC/ASL1-CORE).
Storage, replication, or access control (that’s ASL/1-STORE and up).
Execution, signatures, facts, overlays, or graph storage/query.

Everything else builds on this substrate.

3.2 PEL/1-CORE — Primitive Execution Layer (L1)

Document: PEL/1-CORE

Defines pure, deterministic execution over Artifacts:

Schemes are identified by SchemeRef (a Reference to a scheme descriptor Artifact).
Programs, inputs, outputs, and params are just Artifacts; their types are identified by TypeTag.

Each scheme defines a pure function:

Exec_s(program, inputs, params) -> (outputs, ExecutionResultValue)

No time, no network, no hidden mutable state, no implicit graph or certs.

Responsibilities:

“Given this scheme, program, inputs, params → what outputs and result Artifact-shape arise?”
Providing a deterministic ExecutionResultValue describing the outcome.

Not responsible for:

Graph storage, certificates, policy, or stores.
Encoding or hashing (PEL/1-CORE depends only on ASL/1-CORE; concrete surfaces use the near-core stack).

Core invariants (from the PEL spec):

Determinism — for fixed (scheme_ref, program, inputs, params), all conformant implementations produce identical outputs and result values.
Purity — no external mutable state, time, randomness, or I/O in the semantics of Exec_s.
Hot-path isolation — PEL/1-CORE execution does not require any certification, receipt, fact, or overlay profiles on the hot path; provenance is derived after the fact from Artifacts and results via TGK surfaces.

3.3 TGK/1-CORE — Trace Graph Kernel (L1.5)

Document: TGK/1-CORE

Defines the logical provenance graph as a projection over Artifacts:

Nodes are Artifact IDs:
```
Node := Reference
```

Edges are EdgeBody values encoded inside EdgeArtifacts:

EdgeBody {
  type:    EdgeTypeId  // uint32
  from:    Node[]      // ordered, MAY be empty
  to:      Node[]      // ordered, MAY be empty
  payload: Reference   // always present
}

EdgeArtifacts are ordinary Artifacts whose payload decodes (under some edge encoding profile) to an EdgeBody. Their identity is an ordinary Reference (“EdgeRef”).

Responsibilities:

Node model: Node := Reference.
Edge model: EdgeBody + edge-tag/type configuration.
Defining a ProvenanceGraph as a pure projection over:
- a finite set of Artifacts, and
- a configured set of edge encodings and type catalogs.

Core kernel rules:

All TGK edges must be represented as Artifacts; there is no separate edge ID space.
For any snapshot (finite Artifact set + profile set), the induced ProvenanceGraph is unique; any graph indexes or caches are optimizations only.
TGK does not define how edges are encoded into bytes; that is the role of edge encoding profiles such as ENC/TGK1-EDGE/1, built on the ASL stack.
TGK does not define how the graph is stored or queried; that is the role of TGK/STORE/1 and related profiles.

Not responsible for:

How the graph is physically stored or queried (TGK/STORE/1).
Policy decisions about what edge patterns “mean” (facts, authority, reachability); that’s profiles.

Layering with PEL/1-CORE:

PEL executions MAY be described via TGK edges (via future profiles).
TGK is not a runtime dependency for PEL; edges can be emitted by runtimes or reconstructed from Artifacts (programs, inputs, traces, receipts).

4. Near-core Substrate & Graph Store Profiles

These surfaces are not kernel primitives, but are canonical and expected in almost all deployments.

4.1 ENC/ASL1-CORE v1 — Core Canonical Encoding

Document: ENC/ASL1-CORE Profile ID: ASL_ENC_CORE_V1 = 0x0001

Defines the canonical binary encoding for ASL/1-CORE values:

ArtifactBytes — canonical encoding for Artifact.
ReferenceBytes — canonical encoding for Reference.

Responsibilities:

Provide stable, injective, streaming-friendly encodings for Artifact and Reference.
Define the canonical byte sequences used as input to ASL1 hashes and stores.

Not responsible for:

Hash algorithms or HashId registry (HASH/ASL1).
Storage or transport protocols.
Scheme-specific encodings (PEL, TGK, domain formats).

Identity discipline:

The profile ID (ASL_ENC_CORE_V1) and version are not embedded into ArtifactBytes / ReferenceBytes.
For any context where Reference values are derived, the applicable encoding profile (typically ASL_ENC_CORE_V1) MUST be fixed and explicit.
A given (hash_id, digest) pair corresponds to exactly one canonical ArtifactBytes under the chosen encoding profile.

4.2 HASH/ASL1 — Hash Algorithm Registry

Document: HASH/ASL1

Defines the ASL1 hash family:

Assigns stable HashId values (uint16) to concrete cryptographic hash algorithms.
Defines HASH-ASL1-256 (HashId = 0x0001, SHA-256) as the mandatory baseline.
Reserves ranges for additional classical and post-quantum algorithms.

Responsibilities:

Mapping HashId → algorithm descriptor (algorithm, digest length, constraints).
Ensuring assignments are immutable within the registry.
Providing a globally shared interpretation of Reference.hash_id throughout the stack.

Not responsible for:

When/how to migrate between algorithms (policy & profile level).
Encoding/storage of digests (handled by ASL/1-CORE + ENC/ASL1-CORE).
Store behaviour or execution semantics.

HASH/ASL1 + ENC/ASL1-CORE + ASL/1-CORE together define the identity discipline for Reference.

4.3 ASL/1-STORE — Store Semantics

Document: ASL/1-STORE

Defines the abstract content-addressable store model:

At a snapshot, a StoreInstance is a partial mapping:

Reference -> Artifact   // 0 or 1 Artifact per Reference

With a fixed StoreConfig:

StoreConfig {
  encoding_profile: EncodingProfileId  // e.g. ASL_ENC_CORE_V1
  hash_id:          HashId             // e.g. 0x0001 (HASH-ASL1-256)
}

Operations (logical):
- put(Artifact) -> Reference | ERR_INTEGRITY | ERR_UNSUPPORTED
- get(Reference) -> Artifact | ERR_NOT_FOUND | ERR_UNSUPPORTED | ERR_INTEGRITY

Responsibilities:

Content-addressable semantics over ASL/1-CORE.
Minimal logical error model at the store boundary.
Clear identity semantics: no two non-identical Artifacts may share a Reference under the same StoreConfig.

Not responsible for:

Concrete APIs / protocols (HTTP, gRPC, language APIs).
Security, multi-tenancy, replication, or GC.
Concurrency control or transactional semantics.
Execution or provenance semantics.

ASL/1-STORE reuses ASL identity; it does not invent a new notion of “object ID”.

4.4 PEL/1 Execution Stack — Canonical DAG & Trace Profiles

These are standard, near-core profiles that give a concrete, store-backed execution stack for PEL/1-CORE.

PEL/1-SURF — Primitive Execution Surface

Wires Exec_s from PEL/1-CORE to ASL/1-STORE.
Takes scheme_ref, program_ref, input_refs, params_ref plus a StoreInstance.
Resolves Artifacts, invokes Exec_s, persists outputs and a surface-level ExecutionResult Artifact.
Does not depend on TGK or higher profiles on the execution hot path.

PEL/PROGRAM-DAG/1 — DAG Program Scheme

Defines Programs as acyclic graphs (Nodes) over Artifact inputs/outputs.
Provides structural validity, a canonical topological order, and Exec_DAG as a PEL/1-CORE scheme.
Store-neutral; used by PEL/1-SURF as a concrete scheme.

PEL/PROGRAM-DAG-DESC/1 — DAG Scheme Descriptor

Defines the logical descriptor value for the DAG scheme (DagSchemeDescriptor) and its encoding as a dedicated scheme-descriptor Artifact.
Binds PEL/PROGRAM-DAG/1 to a concrete SchemeRef (SchemeRef_DAG_1) by hashing the descriptor Artifact under ASL_ENC_CORE_V1 + a chosen HashId.
Records which Program TypeTag and encoding profile identify Program Artifacts for this scheme.
Remains store- and graph-neutral; engines MAY treat the descriptor as build-time or configuration metadata and are not required to read it on the execution hot path.

ENC/PEL-PROGRAM-DAG/1 — Program Encoding

Canonical binary encoding for Program values (PEL/PROGRAM-DAG/1).
Fixes node layout, DagInput representation, and root layout.
Used as Artifact.bytes under a dedicated TypeTag (TYPE_TAG_PEL_PROGRAM_DAG_1).

PEL/TRACE-DAG/1 — DAG Execution Trace Profile

Defines TraceDAGValue: per-node run status, output refs, and deterministic diagnostics, linked to scheme_ref, program_ref, input_refs, params_ref.
Optional but deterministic; enables higher layers to reconstruct node-level execution relationships.

ENC/PEL-TRACE-DAG/1 — Trace Encoding

Canonical encoding for TraceDAGValue.
Used as Artifact.bytes under TYPE_TAG_PEL_TRACE_DAG_1.
Embeds Reference values via ReferenceBytes (ENC/ASL1-CORE).

OPREG/PEL1-KERNEL + OPREG/PEL1-KERNEL-PARAMS/1 — Kernel Ops & Params

Define a minimal, globally stable set of PEL kernel ops (e.g. pel.bytes.concat, pel.bytes.slice, pel.bytes.const, pel.bytes.hash.asl1).
Specify logical parameter types and runtime error codes.
Provide canonical parameter encodings/decodings for those ops.
Are pure, deterministic, and store-/graph-neutral; they sit entirely inside the PEL/1-CORE model.

4.5 TGK Edge Encoding — `ENC/TGK1-EDGE/1`

Document: ENC/TGK1-EDGE/1 Profile ID: TGK1_EDGE_ENC_V1

Defines the canonical binary encoding of TGK EdgeBody values:

EdgeBody {
  type:    EdgeTypeId
  from:    Node[]      // Node = Reference
  to:      Node[]
  payload: Reference
}

as EdgeBytes, and their embedding as EdgeArtifacts:

Artifact {
  bytes    = EdgeBytes
  type_tag = TYPE_TAG_TGK1_EDGE_V1
}

Responsibilities:

Give a single, injective, streaming-friendly layout for:
- EdgeTypeId,
- ordered from / to lists, and
- payload : Reference.
Define encode_edgebody_tgk1_v1 / decode_edgebody_tgk1_v1:
- A fixed edge_version (u16) guard word, always 1 in this profile.
- Use of canonical ReferenceBytes (ENC/ASL1-CORE) for embedded References, via EncodedRef length-prefix wrappers.
- Enforcement of TGK/EDGE-NONEMPTY-ENDPOINT/CORE/1 at the encoding layer.
Provide a canonical EdgeArtifact shape (TYPE_TAG_TGK1_EDGE_V1) that environments can treat as edges in TGK/1-CORE.

Not responsible for:

Semantics of specific EdgeTypeId values (those belong to TGK type catalogs and profiles).
Graph store or query semantics (those belong to TGK/STORE/1).
Edge identity (still given by ASL/1 Reference over the EdgeArtifact).

Design note:

edge_version is a guard, not an evolution knob:
- For TGK1_EDGE_ENC_V1, encoders MUST always write edge_version = 1.
- Decoders for this profile MUST accept only 1 and treat anything else as “not a TGK1_EDGE_ENC_V1 payload”.
- Any incompatible change should be a new profile (and typically a new TypeTag), not edge_version = 2 within this profile.

4.6 TGK/STORE/1 — Graph Store & Query Profile

Document: TGK/STORE/1

Defines the graph store abstraction and basic query semantics over the TGK provenance graph induced by Artifacts:

Treats the induced ProvenanceGraph as the source of truth:

ProvenanceGraph {
  Nodes: set<Node>
  Edges: set<(EdgeRef, EdgeBody)>
}

Introduces GraphStoreInstance / GraphStoreSnapshot as:
- a finite Artifacts set drawn from one or more ASL/1-STORE instances or equivalent feeds, and
- a TGKProfileSet (edge tags, encodings, edge types) “in effect” for that snapshot.
Exposes minimal, identity-preserving graph operations:
- resolve_edge(EdgeRef) -> EdgeBody | error
- adjacency queries: edges_from, edges_to, edges_incident
- optional scan_edges for paginated edge scans
- optional neighbors for node-neighbor projection

Responsibilities:

Ensure that all graph views are consistent with TGK/1-CORE’s projection for some (Artifacts, TGKProfileSet) snapshot.
Define a small graph-level error model (e.g. “ref is not an edge”, unsupported identity domain, underlying artifact error).
Fix a canonical edge and node ordering (based on (hash_id, digest)) for deterministic results across implementations.

Not responsible for:

Provenance algorithms (backward/forward reachability, trace construction) — those belong to TGK/PROV/1 and higher-level profiles.
Certificate, fact, or overlay semantics (future profiles).
Transport or API shapes (HTTP/gRPC/etc.).
Store semantics themselves (ASL/1-STORE is the source of artifact resolution).

TGK/STORE/1 is:

“Given a graph defined by TGK/1-CORE, how do we expose its edges and adjacency in a way that is deterministic, identity-preserving, and policy-neutral?”

Kernel provenance semantics (TGK/PROV/1) and higher-level profiles typically use TGK/STORE/1 as their standard graph-access surface.

4.7 TGK/PROV/1 — Provenance & Trace Semantics over TGK/1-CORE

Document: TGK/PROV/1

Defines the kernel provenance operators over a ProvenanceGraph snapshot:

Parameters: ProvDirection (BACKWARD/FORWARD/BOTH), EdgeTypeFilter, DepthLimit.
Pure, deterministic operators:
- prov_closure_nodes(G, S, Q) — reachable node set from finite seeds S,
- prov_depths(G, S, Q) — minimum-hop depth map over that closure,
- prov_layers(G, S, Q) — depth-partitioned layering of reachable nodes,
- prov_trace(G, S, Q) — induced TraceGraph subgraph view.

Responsibilities:

Define semantics purely over ProvenanceGraph snapshots and finite seed sets (store/index/API neutral).
Fix canonical behaviour for backward/forward/bidirectional reachability, depth assignment, and trace construction that higher profiles can rely on.
Make closure and trace behaviour algebraically well-behaved (closure operator, monotone in seeds, depth limits, and edge-type selection).

Not responsible for:

Graph store or adjacency APIs (TGK/STORE/1); these are implementation choices.
Edge-type meaning or provenance policy (“which edges count as causal vs decorative”); that is decided by profiles (e.g. PEL/TRACE-DAG and future profiles).
Encoding of provenance results into Artifacts (receipts, reports, overlays).

Layering:

Depends normatively only on TGK/1-CORE (and, via TGK, ASL/1-CORE).
Typically implemented on top of TGK/STORE/1 for adjacency and edge resolution, but any implementation over a ProvenanceGraph snapshot that satisfies TGK/PROV/1’s semantics is valid.
Used by higher layers as the canonical way to ask provenance questions over the TGK graph.

5. Profiles on Top

Profiles above kernel + near-core are deferred in this repository. When those profiles are introduced, they will:

encode their objects as Artifacts (own TypeTag ranges and encodings),
use References as durable pointers into the substrate,
typically expose relationships as TGK edges, and
query the resulting graph via TGK/STORE/1 / TGK/PROV/1 or equivalent.

6. Dependency Summary

Conceptual DAG (simplified):

ASL/1-CORE
- ↓ used by ENC/ASL1-CORE, HASH/ASL1, ASL/1-STORE, PEL/1-CORE, TGK/1-CORE, PEL/PROGRAM-DAG/1, PEL/PROGRAM-DAG-DESC/1, PEL/TRACE-DAG/1, OPREG/PEL1-KERNEL, OPREG/PEL1-KERNEL-PARAMS/1, ENC/TGK1-EDGE/1, TGK/STORE/1, TGK/PROV/1.
ENC/ASL1-CORE
- ↓ used by HASH/ASL1 (for ArtifactBytes / ReferenceBytes), ASL/1-STORE, PEL/1-SURF, ENC/PEL-PROGRAM-DAG/1, ENC/PEL-TRACE-DAG/1, PEL/PROGRAM-DAG-DESC/1, ENC/TGK1-EDGE/1, TGK/STORE/1, and future profiles.
HASH/ASL1
- ↓ used by ASL/1-STORE, PEL/1-SURF, ENC/PEL-PROGRAM-DAG/1, ENC/PEL-TRACE-DAG/1, PEL/PROGRAM-DAG-DESC/1, ENC/TGK1-EDGE/1, TGK/STORE/1, and future profiles for identity.
ASL/1-STORE
- ↓ used by PEL/1-SURF, TGK storage/indexing profiles (TGK/STORE/1).
PEL/1-CORE
- ↓ used by PEL/1-SURF, PEL/PROGRAM-DAG/1, PEL/PROGRAM-DAG-DESC/1, PEL/TRACE-DAG/1, OPREG/PEL1-KERNEL, domain execution schemes.
PEL/1-SURF, PEL/PROGRAM-DAG/1, PEL/PROGRAM-DAG-DESC/1, PEL/TRACE-DAG/1, ENC/PEL-PROGRAM-DAG/1, ENC/PEL-TRACE-DAG/1, OPREG/PEL1-KERNEL, OPREG/PEL1-KERNEL-PARAMS/1
- ↓ used by future profiles and domain layers to build reproducible executions, traces, and evidence.
TGK/1-CORE
- ↓ used by ENC/TGK1-EDGE/1 (for the logical EdgeBody model), TGK/STORE/1, TGK/PROV/1, and future profiles for provenance reconstruction.
ENC/TGK1-EDGE/1
- ↓ used by TGK-aware stores (TGK/STORE/1), provenance profiles (TGK/PROV/1), and by higher layers that emit or interpret EdgeArtifacts.
TGK/STORE/1
- ↓ used by TGK/PROV/1 (provenance operators), and by higher layers as the standard way to query the provenance graph.
TGK/PROV/1
- ↓ used by higher layers as the canonical kernel for provenance closure, depth, and trace semantics over TGK graphs, typically implemented on top of TGK/STORE/1.

7. How to Use This Overview When Editing Specs

When editing:

ASL/1-CORE:
- Keep this doc + Tier-0 invariants in view.
- Must not depend on any other spec.
ENC/ASL1-CORE / HASH/ASL1:
- Keep ASL/1-CORE + this overview in view.
- Must not re-define Artifact, Reference, or HashId.
ASL/1-STORE:
- Keep ASL/1-CORE, ENC/ASL1-CORE, HASH/ASL1 + this overview in view.
- Must not introduce new identity semantics or policy.
PEL/1-CORE:
- Keep ASL/1-CORE + this overview in view.
- Kernel semantics are storage- and graph-neutral.
- Must not require TGK/1-CORE, ENC/TGK1-EDGE/1, TGK/STORE/1, or higher profiles on the execution hot path.
PEL/1-SURF:
- Keep ASL/1-CORE, ENC/ASL1-CORE, HASH/ASL1, ASL/1-STORE, PEL/1-CORE + this overview in view.
- May wire Exec_s to stores, but must not depend on TGK or higher profiles on the execution hot path.
PEL/PROGRAM-DAG/1, ENC/PEL-PROGRAM-DAG/1 & PEL/PROGRAM-DAG-DESC/1:
- Keep ASL/1-CORE, PEL/1-CORE + this overview in view.
- PEL/PROGRAM-DAG/1 defines the scheme and evaluation semantics; ENC/PEL-PROGRAM-DAG/1 defines the canonical Program encoding; PEL/PROGRAM-DAG-DESC/1 binds the scheme to a SchemeRef and Program identity (type tag + encoding profile) via a descriptor Artifact.
- Must not depend on stores or TGK; keep descriptor logic store-/graph-neutral (no provenance/policy baked into scheme binding).
PEL/TRACE-DAG/1 & ENC/PEL-TRACE-DAG/1:
- Keep ASL/1-CORE, PEL/1-CORE, PEL/PROGRAM-DAG/1 + this overview in view.
- Define trace shape and encoding; TGK interprets traces into edges, not the other way around.
OPREG/PEL1-KERNEL & OPREG/PEL1-KERNEL-PARAMS/1:
- Keep ASL/1-CORE, PEL/1-CORE, PEL/PROGRAM-DAG/1 + this overview in view.
- Must only define pure, deterministic ops and param encodings; no store, graph, or policy semantics.
TGK/1-CORE:
- Keep ASL/1-CORE + this overview in view.
- Must define edges as Artifacts and the graph as a reconstructible projection.
- Must not depend on particular edge encodings (ENC/TGK1-EDGE/1 is a profile using TGK/1-CORE, not a kernel dependency).
- Must not depend on graph store/query details (TGK/STORE/1 sits above TGK/1-CORE).
ENC/TGK1-EDGE/1:
- Keep ASL/1-CORE, ENC/ASL1-CORE, HASH/ASL1, TGK/1-CORE + this overview in view.
- Must not re-define EdgeBody or EdgeTypeId; only define how EdgeBody ↔ EdgeBytes works for a specific profile.
- Must keep edge_version as a guard, not an in-place evolution knob; incompatible changes should become a new profile and (typically) a new TypeTag.
TGK/STORE/1:
- Keep ASL/1-CORE, ASL/1-STORE, ENC/ASL1-CORE, HASH/ASL1, TGK/1-CORE, ENC/TGK1-EDGE/1 + this overview in view.
- Must not re-define Node, EdgeBody, EdgeTypeId, or ProvenanceGraph; it only exposes and queries the graph that TGK/1-CORE defines.
- Must not introduce new identity schemes for nodes or edges; Node := Reference, EdgeRef := Reference.
- Must remain policy- and semantics-neutral: no fact, certificate, or provenance meaning inside TGK/STORE/1, just projection and queries.
TGK/PROV/1:
- Keep ASL/1-CORE, TGK/1-CORE, TGK/STORE/1 (as an implementation surface) + this overview in view.
- Must define provenance operators purely in terms of ProvenanceGraph snapshots and finite seed sets; semantics are graph-only and store-neutral.
- Must not depend on particular graph-store APIs (TGK/STORE/1 is an optimisation/implementation choice, not a semantic dependency).
- Must not bake in higher-profile semantics; it is a kernel layer that higher profiles specialise via edge-type selection and policies.

For any future profile (certification, receipts, facts, overlays, or domain-specific):

Treat this document as the “ground truth map” of what you’re allowed to assume from the substrate, and where your profile must stop.
If you find yourself needing new kernel behaviour, that likely means a new *-CORE surface, not a profile shortcut.

8. Document History (Informative)

0.4.2 (2025-12-22): Trimmed the overview to the repo’s implemented stack, removed deferred profile details and PH06 evidence hooks, and kept the focus on kernel + near-core orientation.
0.4.1 (2025-11-30): Highlighted TGK/STORE evidence hooks + PH06 governance linkage.
0.4.0 (2025-11-16): Relocated the stack overview into /amduat/tier1/, trimmed the PH06 scope to the kernel-only surfaces, and documented that certification/receipt/fact/overlay profiles are deferred to future phases.
0.3.3 (2025-11-16): Added PEL/PROGRAM-DAG-DESC/1 as the canonical DAG scheme descriptor across references, the PEL execution stack, dependency summary, and editing guidance.
0.3.2 (2025-11-16): Added TGK/PROV/1 to the stack overview as the canonical provenance kernel over TGK/1-CORE and wired it through references, dependency summary, and editing guidance.
0.3.1 (2025-11-16): Added TGK/STORE/1 into the overview as the standard graph store & query profile, clarified dependency summary/editing guidance, and introduced the history section.
0.3.0 (2025-11-16): Initial Tier-1 substrate stack orientation for Amduat 2.0 (kernel, near-core profiles, canonical PEL stack, and profile authoring guidance).

29 KiB Raw Permalink Blame History Unescape Escape

SUBSTRATE/STACK-OVERVIEW — Amduat 2.0 Substrate Stack

License

0. Purpose

1. Design North Star

2. Layered Stack (Overview)

3. Kernel

3.1 ASL/1-CORE — Artifact Substrate (L0)

3.2 PEL/1-CORE — Primitive Execution Layer (L1)

3.3 TGK/1-CORE — Trace Graph Kernel (L1.5)

4. Near-core Substrate & Graph Store Profiles

4.1 ENC/ASL1-CORE v1 — Core Canonical Encoding

4.2 HASH/ASL1 — Hash Algorithm Registry

4.3 ASL/1-STORE — Store Semantics

4.4 PEL/1 Execution Stack — Canonical DAG & Trace Profiles

4.5 TGK Edge Encoding — ENC/TGK1-EDGE/1

4.6 TGK/STORE/1 — Graph Store & Query Profile

4.7 TGK/PROV/1 — Provenance & Trace Semantics over TGK/1-CORE

5. Profiles on Top

6. Dependency Summary

7. How to Use This Overview When Editing Specs

8. Document History (Informative)

29 KiB

Raw Permalink Blame History

4.5 TGK Edge Encoding — `ENC/TGK1-EDGE/1`