niklas/amduat
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
amduat/tier1/amduat20-stack-overview.md
Carl Niklas Rydberg b47b914224 Scaffold C layout and ASL registry model
2025-12-19 19:22:40 +01:00

805 lines
33 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.

# 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.1
**Last updated:** 2025-11-30
**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 required by PH06. Certification, receipt, fact, and
> overlay profiles are explicitly deferred to later phases.
> **PH06 closure note (v0.4.1)**
> TGK store/provenance surfaces now reference the PH06 TGK rebuild evidence:
> `/amduat/vectors/ph06/tgk/manifest.json`,
> `/amduat/logs/ph06/evidence/tgk/PH06-EV-TGK-REBUILD-001/`, and the governance
> bundle `PH06-EV-GOV-REG-001` that records registry/ADR alignment for closure.
© 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. Purpose
This document gives 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. All detailed behaviour is defined in the referenced specs.
---
## 1. Design North Star
The substrate exists to make computing **deterministic, inspectable, and replayable**.
Key invariants:
1. **Immutable artifacts, content-addressed identity**
Everything that matters is an immutable `Artifact`; identity is `(hash_id, digest)` over a canonical encoding.
2. **Tiny kernel, rich profiles**
The kernel only knows:
* Artifacts (values) — `ASL/1-CORE`
* pure execution — `PEL/1-CORE`
* graph semantics — `TGK/1-CORE`
Meaning (facts, receipts, overlays, policy) lives in profiles on top.
3. **Single logical provenance graph**
All relationships (execution, certs, overlays, facts, annotations) appear as typed edges in one logical graph over artifact IDs (`Reference`s), via `TGK/1-CORE`. EdgeArtifacts are ordinary Artifacts; their identities are ordinary `Reference`s.
4. **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.
5. **Storage-neutral, policy-neutral kernel**
* No special filesystem, database, or policy model is assumed.
* Stores, transports, graph stores, 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** — intentionally out-of-scope for this
version to keep the focus on the Amduat 2.0 kernel contract. Certification,
receipt, fact, overlay, and domain profiles will reattach once the kernel is
proven inside future 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**:
```text
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:
```text
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:
```text
Node := Reference
```
* **Edges** are `EdgeBody` values encoded inside EdgeArtifacts:
```text
EdgeBody {
type: EdgeTypeId // uint32
from: Node[] // ordered, MAY be empty
to: Node[] // ordered, MAY be empty
payload: Reference // always present
}
```
* **EdgeArtifacts** are ordinary `Artifact`s 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 encoding profiles 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 (e.g., `EDGE_EXECUTION`, `EDGE_RECEIPT_SUPPORTS`).
* 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 injective, stable, deterministic, streaming-friendly encodings for `Artifact` and `Reference`.
* Define the canonical byte sequences used as input to ASL1 hash functions and stores.
* Satisfy all canonical encoding constraints from `ASL/1-CORE` (injective, stable, deterministic, explicit structure, type-sensitive, byte-transparent, streaming-friendly).
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:
```text
Reference -> Artifact // 0 or 1 Artifact per Reference
```
* With a fixed `StoreConfig`:
```text
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, CIL, FER, FCT, or OI on the execution hot path.
**`PEL/PROGRAM-DAG/1` — DAG Program Scheme**
* Defines Programs as acyclic graphs (`Node`s) 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 that descriptor Artifact under `ASL_ENC_CORE_V1` and a chosen `HashId` (Amduat 2.0 baseline: `HASH-ASL1-256`, `HashId = 0x0001`).
* Records, in a content-addressed way, which `TypeTag` and encoding profile (`TYPE_TAG_PEL_PROGRAM_DAG_1`, `PEL_ENC_PROGRAM_DAG_V1`) 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 TGK to reconstruct node-level execution edges (via profiles like `TGK/PEL/1`).
**`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:
```text
EdgeBody {
type: EdgeTypeId
from: Node[] // Node = Reference
to: Node[]
payload: Reference
}
```
as `EdgeBytes`, and their embedding as EdgeArtifacts:
```text
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 `Reference`s, 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 TGK’s `ProvenanceGraph` as the source of truth:
```text
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 (`CIL/1`, `FER/1`, `FCT/1`, `OI/1`).
* Transport or API shapes (HTTP/gRPC/etc.).
* Store semantics themselves (`ASL/1-STORE` is the source of artifact resolution).
`TGK/STORE/1` is strictly:
> “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 (`FER/1`, `FCT/1`, `CIL/1`, `OI/1`, domain 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:
* A small, store-neutral provenance parameter model:
* `ProvDirection` (BACKWARD, FORWARD, BOTH),
* `EdgeTypeFilter` (edge-type selection),
* `DepthLimit` (hop-count bound).
* 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:
* Provide a **graph-only** provenance kernel over `TGK/1-CORE`:
* semantics are defined purely in terms of `ProvenanceGraph` snapshots and finite seed sets,
* no dependence on any particular store, index, or query API.
* 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, `FER/1`, `FCT/1`, `OI/1`).
* 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 that operates over a `ProvenanceGraph` snapshot and satisfies `TGK/PROV/1`’s semantics is valid.
* Used by `FER/1`, `FCT/1`, `CIL/1`, `OI/1`, and domain profiles as the canonical way to ask provenance questions over the TGK graph.
---
## 5. Profiles on Top
These build on kernel + near-core and express semantics and policy.
* **CIL/1 — Certification & Integrity Layer**
* Certificates as Artifacts.
* Generic signatures over `Reference`s and other Artifacts.
* Separation between “is the signature cryptographically valid?” (CIL) and “what does it mean?” (profiles such as FCT/1).
* **FER/1 — Evidence / Receipts**
* Receipts bundling descriptors, inputs, outputs, traces, and certs as Artifacts.
* Plays well with TGK via edges like “this receipt supports this fact” or “this receipt is attached to this execution”.
* Typically uses `TGK/PROV/1` to construct provenance cones and trace projections when building or checking receipts.
* **FCT/1 — Facts / Transactions**
* Facts/transactions as semantics over receipts + certificates + TGK graph patterns.
* Governs acceptance criteria for domain-level “truth”.
* May rely on `TGK/PROV/1` to define which provenance patterns or trace shapes are acceptable evidence for particular fact schemas.
* **OI/1 — Overlays & Navigation**
* Overlays mapping human-friendly names, paths, or views to `Reference`s.
* Graph-based navigation and UI surfaces, often driven by `TGK/PROV/1` queries over `TGK/STORE/1`.
All of these:
* encode their objects as Artifacts (own `TypeTag` ranges and encodings),
* use `Reference`s as durable pointers into the substrate,
* typically expose relationships as TGK edges, using edge types bound to `ENC/TGK1-EDGE/1` (or other edge encodings where appropriate),
* and query the resulting graph via `TGK/STORE/1` / `TGK/PROV/1` or equivalent.
Higher-level domain profiles (AI evals, CI pipelines, governance processes, ledgers, etc.) sit above all of this.
---
## 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`,
`CIL/1`, `FER/1`, `FCT/1`, `OI/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 higher 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 higher profiles for identity.
* `ASL/1-STORE`
* ↓ used by `PEL/1-SURF`, TGK storage/indexing profiles (`TGK/STORE/1`),
`CIL/1`, `FER/1`, `FCT/1`, `OI/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 `FER/1`, `FCT/1`, `CIL/1`, `OI/1` and domain profiles 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`,
`FER/1`, `FCT/1`, `CIL/1`, `OI/1`, and domain 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 (e.g. `FER/1`, `FCT/1`, `CIL/1`, `OI/1`) that emit or interpret EdgeArtifacts.
* `TGK/STORE/1`
* ↓ used by `TGK/PROV/1` (provenance operators),
and by higher layers (`FER/1`, `FCT/1`, `CIL/1`, `OI/1` and domain profiles) as the standard way to query the provenance graph.
* Evidence hooks: PH06 rebuild CLI and parity receipts live under
`/amduat/vectors/ph06/tgk/manifest.json` and
`/amduat/logs/ph06/evidence/tgk/PH06-EV-TGK-REBUILD-001/`.
* `TGK/PROV/1`
* ↓ used by `FER/1`, `FCT/1`, `CIL/1`, `OI/1`, and domain profiles as the canonical kernel for provenance closure, depth, and trace semantics over TGK graphs, typically implemented on top of `TGK/STORE/1`.
Higher-level domain profiles depend on all of the above as needed.
---
## 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`, `CIL/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, CIL, FER, FCT, or OI 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 model and evaluation semantics; `ENC/PEL-PROGRAM-DAG/1` defines the canonical Program encoding; `PEL/PROGRAM-DAG-DESC/1` binds that scheme to a concrete `SchemeRef` and Program `TypeTag`/encoding via a descriptor Artifact.
* Must not depend on store semantics or graph/cert layers; descriptor logic must remain store- and TGK-neutral (no provenance or policy semantics baked into the 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.
* PH06 evidence discipline: implementations MUST cite `tools/tgk/rebuild.py`
receipts (`/amduat/logs/ph06/evidence/tgk/PH06-EV-TGK-REBUILD-001/`) and the
governance bundle `PH06-EV-GOV-REG-001` when wiring store adapters into CLI
workflows.
* **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 CIL/FER/FCT/OI semantics; it is a kernel layer that higher profiles specialise via edge-type selection and policies.
For any profile (`CIL/1`, `FER/1`, `FCT/1`, `OI/1`, 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.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).
---
* **0.4.1 (2025-11-30):** Highlighted TGK/STORE evidence hooks + PH06 governance linkage.
### Commit message
**Commit title:**
`PEL/PROGRAM-DAG-DESC/1 v0.1.6 + SUBSTRATE/STACK-OVERVIEW v0.3.3 — wire DAG scheme descriptor into stack map`
**Commit body:**
* `PEL/PROGRAM-DAG-DESC/1` → v0.1.6
* Finalised the DAG scheme descriptor value model and encoding, and fixed `SchemeRef_DAG_1` as the canonical `SchemeRef` for `PEL/PROGRAM-DAG/1` under `ASL_ENC_CORE_V1` + `HASH-ASL1-256`.
* Clarified that the descriptor binds the scheme to a Program `TypeTag` and encoding profile and remains store- and graph-neutral.
* `SUBSTRATE/STACK-OVERVIEW` → v0.3.3
* Added `PEL/PROGRAM-DAG-DESC/1` to the references list and the canonical PEL execution stack.
* Described the descriptor’s role in §4.4 and wired it into the dependency summary (§6) and editing guidance (§7) as the scheme binding between `PEL/1-CORE`, `PEL/PROGRAM-DAG/1`, and ASL/1 `SchemeRef`s.
* Orientation-only change; no behavioural rules added.
Reference in a new issue View git blame Copy permalink