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.

Note: the filesystem ASL store (`asl_store_fs`) is a legacy convenience backend
and will be considered non-conformant to ASL index/log specs once the index/log
store is introduced. Audits for ASL index/log specs target the new backend only.

## Test Expectations (Planned)

These tests are planned to validate index/log behavior once implemented:

| Area | Example tests |
| --- | --- |
| Segment encoding | Round-trip encode/decode; CRC mismatch rejection; offset bounds checks |
| Log encoding | Hash-chain validation; unknown record type skip; truncated record rejection |
| Replay | Snapshot anchor + log replay determinism; segment seal visibility |
| Tombstones | Shadowing and lift across snapshots; domain-local shadowing rules |
| Visibility | CURRENT computed by `(SnapshotID, LogPosition)`; reverse seal-log order |
| Recovery | Crash with open segment; replay yields deterministic CURRENT |

## Spec Coverage (Implementation Status)

Status legend: ✅ implemented, 🟡 planned/in-progress, ⬜ not started.

| Spec | Status | Notes |
| --- | --- | --- |
| `ASL/1-CORE` | ✅ | Core artifact semantics implemented. |
| `ASL/1-STORE` | ✅ | Store semantics + fs backend. |
| `ENC/ASL1-CORE` | ✅ | Artifact/Reference encoding. |
| `HASH/ASL1` | ✅ | Hash registry + streaming API. |
| `PEL/1-CORE` | ✅ | Core execution semantics. |
| `PEL/1-SURF` | ✅ | Store-backed surface execution. |
| `PEL/PROGRAM-DAG/1` | ✅ | DAG scheme execution. |
| `PEL/PROGRAM-DAG-DESC/1` | ✅ | Scheme descriptor codec + wiring. |
| `ENC/PEL-PROGRAM-DAG/1` | ✅ | Program encoding. |
| `ENC/PEL1-RESULT/1` | ✅ | Result encoding. |
| `PEL/TRACE-DAG/1` | ✅ | Trace semantics + wiring. |
| `ENC/PEL-TRACE-DAG/1` | ✅ | Trace encoding. |
| `TGK/1-CORE` | ✅ | Edge semantics + validation. |
| `ENC/TGK1-EDGE/1` | ✅ | Edge encoding. |
| `TGK/STORE/1` | ✅ | Store semantics. |
| `TGK/PROV/1` | ✅ | Provenance operators. |
| `OPREG/PEL1-KERNEL` | ✅ | Kernel op registry. |
| `OPREG/PEL1-KERNEL-PARAMS/1` | ✅ | Kernel params encoding. |
| `AMDUAT20-STACK-OVERVIEW` | ✅ | Orientation surface aligned. |
| `ASL/1-CORE-INDEX` | ✅ | Index semantics + replay implemented. |
| `ASL/STORE-INDEX/1` | ✅ | Index/log store backend implemented (fs). |
| `ENC/ASL-CORE-INDEX/1` | ✅ | Segment encoding/decoding implemented. |
| `ASL/LOG/1` | ✅ | Log semantics implemented. |
| `ENC/ASL-LOG/1` | ✅ | Log encoding/decoding implemented. |
| `ASL/INDEX-ACCEL/1` | ✅ | Routing key + bloom/shard helpers implemented. |
| `ASL/INDEXES/1` | 🟡 | Taxonomy planned. |
| `ASL/TGK-EXEC-PLAN/1` | 🟡 | Encoding implemented; executor out of scope. |
| `ENC/ASL-TGK-EXEC-PLAN/1` | ✅ | Plan encoding implemented. |
| `ASL/FEDERATION/1` | ✅ | Core federation primitives implemented. |
| `ASL/FEDERATION-REPLAY/1` | ✅ | Deterministic replay and view construction implemented. |
| `ASL/SYSTEM/1` | 🟡 | Cross-cutting view planned. |
| `TGK/1` | 🟡 | Semantic layer planned. |

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

## 2026-01-18 — ASL index/log stack (`tier1/asl-core-index-1.md`, `tier1/asl-store-index-1.md`, `tier1/enc-asl-core-index-1.md`, `tier1/asl-log-1.md`, `tier1/enc-asl-log-1.md`)
- Scope: index semantics, filesystem index/log store, segment encoding, and log encoding/decoding paths.
- Findings: N/A (implemented components already present).
- Resolution: recorded implementation status and aligned routing/shard helpers with index usage.
- Tests: `ctest --test-dir build` (user reported “100% tests passed, 0 tests failed out of 23”).

## 2026-01-18 — ASL/INDEX-ACCEL/1 (`tier1/asl-index-accel-1.md`)
- Scope: routing key derivation, shard selection contract, bloom advisory behavior.
- Findings: missing formal routing-key API and tests around acceleration helpers.
- Resolution: added routing-key/shard helpers and tests for routing-key layout, shard determinism, and bloom advisory behavior.
- Tests: `ctest --test-dir build` (user reported “100% tests passed, 0 tests failed out of 23”).

## 2026-01-18 — ENC/ASL-TGK-EXEC-PLAN/1 (`tier1/enc-asl-tgk-exec-plan-1.md`)
- Scope: execution plan encoding/decoding; validation of operator IDs/inputs.
- Findings: encoding layer missing.
- Resolution: implemented encode/decode/free API and round-trip validation tests.
- Tests: `ctest --test-dir build` (user reported “100% tests passed, 0 tests failed out of 23”).

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

## 2025-12-22 — TGK/STORE/1 (`tier1/tgk-store-1.md`)
- Scope: graph store configuration, edge resolution error mapping, adjacency
  ordering, scan/pagination, and neighbor semantics for TGK store adapters.
- Findings: `resolve_edge` maps conflicting artifacts (same `EdgeRef` with
  different bytes) to `GS_ERR_INTEGRITY`, but the spec requires artifact-layer
  integrity conflicts from `resolve_artifact` to surface as
  `GS_ERR_ARTIFACT_ERROR`.
- Resolution: mapped conflicting artifacts during `resolve_edge` to
  `GS_ERR_ARTIFACT_ERROR` to match artifact-level integrity error handling.
- Tests: user reported “100% tests passed, 0 tests failed out of 14”.

## 2025-12-22 — TGK/PROV/1 (`tier1/tgk-prov-1.md`)
- Scope: provenance query parameters, closure/depth/layer semantics, and trace
  graph construction over TGK/1-CORE projections.
- Findings: no gaps found; `prov_closure_nodes`, `prov_depths`, `prov_layers`,
  and `prov_trace` follow TGK/PROV/1 semantics, including seed handling,
  payload non-traversal, depth limits, and trace node/edge construction.
- Resolution: none required.
- Tests: not run (tgk provenance tests exist under `tests/tgk/test_tgk_prov.c`).

## 2025-12-22 — OPREG/PEL1-KERNEL (`tier1/opreg-pel1-kernel.md`)
- Scope: kernel op registry entries, runtime status codes, diagnostics
  requirements, and Params/arity enforcement for the four kernel ops.
- Findings: `pel.bytes.params` is registered as a kernel op with
  `kernel_op_code = 0x0005` but is not listed in the OPREG/PEL1-KERNEL registry;
  `amduat_pel_program_dag_exec` attaches diagnostics for kernel op runtime
  failures even though the spec mandates an empty diagnostics list for kernel
  ops; internal/invalid artifact handling can yield `status_code = 1` or
  `AMDUAT_PEL_KERNEL_STATUS_INTERNAL`/`AMDUAT_PEL_KERNEL_STATUS_OOM`, which do
  not follow the `kernel_op_code << 16 | error_index` scheme and are not
  specified as kernel runtime error codes.
- Resolution: documented `pel.bytes.params/1` in OPREG/PEL1-KERNEL and params
  profile; missing global params now yields `INVALID_INPUTS`; Exec_DAG no longer
  emits diagnostics for kernel op runtime failures; internal/OOM paths now
  return out-of-model (no `ExecutionResultValue`), avoiding non-registry status
  codes.
- Tests: `ctest --test-dir /home/niklas/build/amduat` (pass, 14 tests).

## 2025-12-22 — OPREG/PEL1-KERNEL-PARAMS/1 (`tier1/opreg-pel1-kernel-params-1.md`)
- Scope: kernel params canonical encodings/decoding, size bounds, and
  `INVALID_PROGRAM` mapping for param decode errors.
- Findings: `amduat_decode_const` accepts `params_bytes` longer than
  `0xFFFF_FFFF` as long as `bytes.len` fits in `size_t`, but the spec requires
  any kernel params payload length exceeding `u32::MAX` to be treated as a
  decode error (even for non-`ENC/PEL-PROGRAM-DAG` inputs).
- Resolution: added a `params_bytes.len <= UINT32_MAX` guard in
  `amduat_pel_kernel_params_decode` so all kernel param decodes enforce the
  u32 bound; added a regression test that feeds an oversized `params_bytes`
  length and expects `INVALID_PROGRAM`.
- Tests: user reported “100% tests passed, 0 tests failed out of 14”.

## 2025-12-22 — SUBSTRATE/STACK-OVERVIEW (`tier1/amduat20-stack-overview.md`)
- Scope: orientation doc maintenance; align overview to this repo’s implemented
  kernel + near-core stack and avoid implying unsupported/deferred layers.
- Findings: overview included deferred up-stack profile details, PH06-specific
  evidence hooks, and a stray embedded “commit message” appendix, making it
  look more normative and broader than the repo’s current scope.
- Resolution: trimmed to implemented stack; replaced references to deferred
  profiles with “future profiles” language; removed PH06 evidence hooks and the
  embedded commit-message appendix; tightened wording throughout; bumped the
  document version/date.
- Tests: N/A (documentation-only change).

## 2026-02-XX — Federation core (`tier1/asl-federation-1.md`, `tier1/asl-federation-replay-1.md`)
- Scope: core federation registry, ingest validation, deterministic replay, view
  construction, and resolve semantics.
- Findings: missing record typing and identity coverage for PER/TGK/tombstones;
  policy gating needed explicit per-domain + optional per-record handling; view
  build and resolve error reporting needed explicit codes and tests.
- Resolution: added federation registry storage, ingest validation, replay/view
  build, resolve APIs, and tests for ordering, tombstone scoping, conflicts,
  bounds, and metadata preservation; documented middle-layer boundary and
  ref-only remote fetch guidance.
- Tests: user reported “100% tests passed, 0 tests failed out of 29”.