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”).