amduat/AUDITS.md

Audit Log

This file tracks spec-to-implementation audits.

Audit intent: keep the implementation aligned with the normative Tier-1 specs by identifying gaps, inconsistencies, and missing tests, then recording resolutions and verification status.

Audit scope: Tier-1 specs under tier1/ covering ASL, PEL, TGK, and OPREG layers, along with their encoding profiles and registry bindings.

Audit template (for future entries):

• Date:
• Spec path(s):
• Scope:
• Findings:
• Resolution:
• Tests:
• Follow-ups (optional):

Verification notes:

• Prefer explicit commands and paths (e.g., ctest --test-dir build).
• If results are user-reported, note that explicitly.

Audit Plan

Status legend: ✅ completed, ⬜ pending.

1. ✅ tier1/asl-1-core.md
2. ✅ tier1/asl-1-store.md
3. ✅ tier1/enc-asl1-core.md
4. ✅ tier1/hash-asl1.md
5. ✅ tier1/pel-1-core.md
6. ✅ tier1/pel-1-surf.md
7. ✅ tier1/pel-program-dag-1.md
8. ✅ tier1/pel-program-dag-desc-1.md
9. ✅ tier1/enc-pel-program-dag-1.md
10. ✅ tier1/enc-pel1-result-1.md
11. ✅ tier1/pel-trace-dag-1.md
12. ✅ tier1/enc-pel-trace-dag-1.md
13. ✅ tier1/tgk-1-core.md
14. ✅ tier1/enc-tgk1-edge-1.md
15. ⬜ tier1/tgk-store-1.md
16. ⬜ tier1/tgk-prov-1.md
17. ⬜ tier1/opreg-pel1-kernel.md
18. ⬜ tier1/opreg-pel1-kernel-params-1.md
19. ⬜ tier1/opreg-tgk-docgraph-1.md
20. ⬜ tier1/amduat20-stack-overview.md

2025-12-22 — ASL/1-CORE (tier1/asl-1-core.md)

• Scope: ASL/1-CORE conformance for value semantics, encoding profiles, and reference derivation.
• Findings: immutability enforcement gaps; EncodingProfileId layering leak; no central ASL ref-derivation API; amduat_octets_eq missing invalid-input guard.
• Resolution: implemented fixes and added amduat_asl_ref_derive conformance test.
• Tests: ctest --test-dir build (11 tests).

2025-12-22 — ASL/1-STORE (tier1/asl-1-store.md)

• Scope: ASL/1-STORE conformance for store semantics, error mapping, and StoreConfig handling in ASL store implementations.
• Findings: put could delete existing artifacts on fsync failure; non-integrity failures surfaced as integrity errors; malformed references treated as unsupported; StoreConfig not enforced at the wrapper boundary.
• Resolution: gated unlink on new writes; introduced AMDUAT_ASL_STORE_ERR_IO and mapped I/O paths; treat malformed refs as ERR_INTEGRITY; added optional validate_config hook with minimal wrapper checks; added amduat_asl_store_ops_init helper to avoid uninitialized ops.
• Tests: command not provided — pass (user reported “100% tests passed, 0 tests failed out of 11”).

2025-12-22 — ENC/ASL1-CORE (tier1/enc-asl1-core.md)

• Scope: canonical encoding/decoding for ArtifactBytes and ReferenceBytes in store-related paths.
• Findings: Reference codec rejected unknown hash_id values; FS store requires digests >= 2 bytes (layout constraint).
• Resolution: accept unknown hash_id values with framing, enforce digest length only when known; reject reserved hash_id = 0; documented FS store digest-length constraint in README.md.
• Tests: not run.

2025-12-22 — HASH/ASL1 (tier1/hash-asl1.md)

• Scope: registry behavior, reserved IDs, immutability, and streaming support.
• Findings: reserved IDs treated as usable; 0x0000 reachable via registry enumeration; SHA-256 override allowed; no streaming API.
• Resolution: reserved-ID guard + registry rows for 0x8002–0x80FF; removed 0x0000 from runtime list; block SHA-256 override; added streaming API and updated tgk mem-store test to use a non-reserved unsupported hash ID.
• Tests: ctest --test-dir /home/niklas/build/amduat (pass, 11 tests).

2025-12-22 — PEL/1-CORE (tier1/pel-1-core.md)

• Scope: core execution semantics, totality, and out-of-model failure handling.
• Findings: OOM paths emitted core results; amduat_pel_exec_program_bytes returned false on invalid program bytes; decode OOM indistinguishable from invalid; kernel op OOM mapped to runtime failure.
• Resolution: treat OOM as out-of-model throughout; add decode status API; make amduat_pel_exec_program_bytes return deterministic INVALID_* results; propagate kernel op OOM status to abort execution.
• Tests: not run.

2025-12-22 — PEL/1-SURF (tier1/pel-1-surf.md)

• Scope: store-backed surface execution wiring, store error mapping, result artifact semantics, and params handling for DAG scheme.
• Findings: params_ref resolved but not passed to scheme; store ERR_IO mapped to StoreFailure instead of environment failure; trace+result persistence and result TypeTag wiring needed alignment.
• Resolution: pass global params into scheme execution; treat ERR_IO as environment failure (no surface result); ensure surface result TypeTag and diagnostics wiring; add conformance tests for params and store I/O behavior.
• Tests: command not provided — pass (user reported “100% tests passed, 0 tests failed out of 11”).

2025-12-22 — PEL/PROGRAM-DAG/1 (tier1/pel-program-dag-1.md)

• Scope: Exec_DAG semantics, structural validity, canonical order, diagnostics, and scheme entrypoint correctness.
• Findings: Exec_DAG accepted raw bytes without enforcing program TypeTag; diagnostics were empty for invalid program/input/runtime cases; OOM returned false with no ExecutionResultValue; CLI exec lacked diagnostics and could not accept tagged program artifacts.
• Resolution: added artifact entrypoint with TypeTag enforcement; demoted raw bytes helper; deterministic diagnostics across validation and runtime; treat OOM as deterministic RUNTIME_FAILED; expose diagnostics in formatters and CLI; allow amduat-pel exec to accept artifact input via --program-format (defaulting to artifact when --input-format artifact is set); refined structural diagnostics for node output index errors.
• Tests: command not provided — pass (user reported “100% tests passed, 0 tests failed out of 11”).

2025-12-22 — PEL/PROGRAM-DAG-DESC/1 (tier1/pel-program-dag-desc-1.md)

• Scope: scheme descriptor Artifact layout, SchemeRef derivation, and DAG scheme binding behavior.
• Findings: missing descriptor encode/decode implementation; no recognition path for TYPE_TAG_PEL_SCHEME_DESC_1; program interpretation ignored descriptor program_type_tag/program_enc_profile; scheme dispatch did not reject non-SchemeRef_DAG_1.
• Resolution: added descriptor codec + round-trip tests; added canonical descriptor recognition helpers; wired validation in CLI; introduced binding accessor for program type/profile and used it across execution/CLI/seed; added scheme-aware exec path and CLI flag.
• Tests: command not provided — pass (user reported “100% tests passed, 0 tests failed out of 12”).

2025-12-22 — ENC/PEL-PROGRAM-DAG/1 (tier1/enc-pel-program-dag-1.md)

• Scope: ProgramBytes encoding/decoding, canonical order, and framing limits.
• Findings: size overflow risk when allocating canonical node order and when computing roots byte size, leading to non-canonical encodes.
• Resolution: added explicit overflow guards; added regression test for large count rejection.
• Tests: command not provided — pass (user reported “100% tests passed, 0 tests failed out of 13”).

2025-12-22 — ENC/PEL1-RESULT/1 (tier1/enc-pel1-result-1.md)

• Scope: surface result encoding, inline ExecutionResultValue, and encoding invariants.
• Findings: encoder did not enforce ExecutionStatus/summary invariants or store_failure ↔ status coupling; decoder accepted out-of-range status/kind.
• Resolution: enforced invariants in encoder; added strict status/kind checks in decoder; added invariant regression tests.
• Tests: not run (new runtime-diagnostics test added after prior user-reported pass of 14 tests).

2025-12-22 — PEL/TRACE-DAG/1 (tier1/pel-trace-dag-1.md)

• Scope: trace artifact construction, node-level trace semantics, and surface wiring for Exec_DAG runs.
• Findings: trace artifacts never include exec_result_ref even when a surface ExecutionResult Artifact is persisted; node-level diagnostics are always empty (including NODE_FAILED, which SHOULD carry at least one deterministic diagnostic entry).
• Resolution: wired exec_result_ref into trace construction by persisting an initial surface result (pre-trace) to obtain exec_result_ref, then encoding the trace with that reference, then persisting the final surface result with trace_ref (note: this produces two result Artifacts for a successful run); per-node runtime diagnostics are now captured and copied into trace entries for failed nodes.
• Tests: command not provided — pass (user reported “100% tests passed, 0 tests failed out of 14”).

2025-12-22 — ENC/PEL-TRACE-DAG/1 (tier1/enc-pel-trace-dag-1.md)

• Scope: canonical TraceDAGBytes encoding, EncodedRef framing, and validation rules for trace payloads.
• Findings: EncodedRef encoding rejected unknown hash_id values by requiring a registry-backed digest length, contradicting ENC/ASL1-CORE’s ReferenceBytes rules (which allow unknown hash IDs and variable digest lengths as long as they are not reserved).
• Resolution: relaxed EncodedRef length validation to reject reserved hash IDs but permit unknown IDs and digest lengths, matching ENC/ASL1-CORE v1 behavior.
• Tests: command not provided — pass (user reported “100% tests passed, 0 tests failed out of 14”).

2025-12-22 — TGK/1-CORE (tier1/tgk-1-core.md)

• Scope: TGK/1-CORE EdgeArtifact recognition, EdgeBody invariants, profile configuration, and deterministic graph projection behavior in TGK stores.
• Findings: amduat_tgk_store_mem_init does not validate config.tgk_profiles.edge_tags/edge_tags_len or config.tgk_profiles.edge_types/edge_types_len, so null pointers with non-zero lengths can lead to undefined behavior and prevent the required EDGE_TAG_SET/edge-type catalogs from being well-defined; no consistency checks ensure edge tags correspond to active edge encodings.
• Resolution: added validation for edge tag/type list pointers and duplicates; enforced TYPE_TAG_TGK1_EDGE_V1 presence when TGK1_EDGE_ENC_V1 is active, and rejection when the encoding is inactive.
• Tests: command not provided — pass (user reported “100% tests passed, 0 tests failed out of 14”).

2025-12-22 — ENC/TGK1-EDGE/1 (tier1/enc-tgk1-edge-1.md)

• Scope: TGK1 EdgeBody encoding/decoding, EncodedRef framing, and profile invariants for TGK1_EDGE_ENC_V1.
• Findings: amduat_enc_tgk1_edge_encode_v1 rejects edges whose references use unknown (non-registry) hash_id values because it requires a registry-backed digest length when calculating EncodedRef sizes, which contradicts ENC/ASL1-CORE v1.x and §2.4’s requirement to accept unknown hash IDs with only reserved-ID rejection and length checks when known.
• Resolution: updated amduat_enc_tgk1_edge_encode_v1 sizing to allow unknown hash IDs per ENC/ASL1-CORE; added regression test for unknown hash_id edge references.
• Tests: command not provided — pass (user reported “100% tests passed, 0 tests failed out of 14”).