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