dispatch-consistency-audit

name

dispatch_consistency_audit

description

Audit Q3 C adoption's dispatch substrate consistency — three-way match of ZirOp tag count = per-op file count = 5-axis handler implementation count; `wasm_level` / `wasi_level` metadata consistency; sampling check that build-option DCE works as expected. Fires at periodic audit_scaffolding boundaries and on explicit request (the §9.12-B build trigger is now DONE — the substrate exists, so the check is always live).

dispatch_consistency_audit

Status: landed at §9.12-A (2026-05-19). Justified by ADR-0071 §Q3 + ADR-0073 (both Accepted). Post-§9.12-B mode is now ACTIVE — src/ir/dispatch_collector.zig exists with the collected_ops declaration, so the full three-way match runs. (Maintenance mode: invoke at periodic audit_scaffolding boundaries, not on a campaign phase edge.)

Purpose

Audit the consistency of Q3 C adoption (per-op file + comptime collector + build-option DCE) — the master plan §7.7 enforcement item.

The dispatch substrate must be consistent along these 4 axes:

1. ZirOp tag count = per-op file count — every ZirOp enum tag in src/ir/zir.zig has a corresponding src/instruction/wasm_X_Y/<op>.zig with a populated body (≥ 20 LOC; not a placeholder).
2. 5-axis handler completeness — every per-op file exports pub const handlers = .{ .validate, .lower, .arm64, .x86_64, .interp }, each pointing at a real function (not a stub returning error.Todo).
3. feature_level metadata consistency — every per-op file declares pub const wasm_level: WasmLevel = ... and the value matches the spec-derived classification table in .dev/wasm_3_0_zirop_mapping.md.
4. build-option DCE verification — a -Dwasm=v1_0 build's nm output contains no Wasm 2.0+ symbols; a -Dwasi=p1 build contains no WASI Preview 2 symbols. (Sampled via check_build_dce.sh.)

When to invoke

• Immediately after §9.12-B (Q3 C adoption completion) — mandatory.
• At each §9.12- chunk close* — sanity check (cheap; reports "deferred" in pre-§9.12-B mode).
• Integrated into audit_scaffolding §K.7 (Phase 9 completion enforcement section).
• Phase boundary before flipping ROADMAP §9.13 to [x].
• Manual by user-invoking the skill at any time.

Procedure

Mode detection (auto)

if [ -f src/ir/dispatch_collector.zig ] && \
   grep -q '^pub const collected_ops' src/ir/dispatch_collector.zig; then
  MODE=post_9_12_B
else
  MODE=pre_9_12_B
fi

Pre-§9.12-B mode (current; through §9.12-A)

The substrate doesn't exist yet. The skill emits a deferred report:

1. Inventory current per-op file presence:

   find src/instruction/wasm_X_Y -name '*.zig' | wc -l        # current file count
   find src/instruction/wasm_X_Y -name '*.zig' -exec wc -l {} + | tail -1 \
     | awk '{print $1}'                                       # total LOC
   

2. Confirm placeholders (per master plan §2.3): the 4 Wasm 1.0 placeholders (control.zig / parametric.zig / variable.zig) + multi_value.zig are listed as "to be populated in §9.12-B".

3. Report state: "Pre-§9.12-B substrate audit — N populated op files, M placeholder slots remaining. Awaiting §9.12-B dispatch_collector landing. Full audit re-runs at post-§9.12-B mode."

4. Exit 0 (not a block — pre-§9.12-B is expected).

Post-§9.12-B mode (active after §9.12-B completes)

Run the 4 axis checks:

Axis 1 — ZirOp ↔ per-op file completeness

# Extract ZirOp tags via zig build (the collector exports the count).
zig build dispatch-list > /tmp/zir_tags.txt   # build step lands in §9.12-B
n_tags=$(wc -l < /tmp/zir_tags.txt)

# Count populated per-op files (excluding placeholders < 20 LOC).
n_files=$(find src/instruction/wasm_X_Y -name '*.zig' \
            -exec sh -c 'wc -l "$1" | awk "{print \$1}" | \
              { read n; [ "$n" -ge 20 ] && echo OK; }' _ {} \; | wc -l)

# Diff: any tag without a file? any file without a tag?
diff <(sort /tmp/zir_tags.txt) <(find src/instruction/wasm_X_Y -name '*.zig' \
        | sed -E 's|.*/||; s/\.zig$//' | sort) > /tmp/zir_diff.txt
[ -s /tmp/zir_diff.txt ] && fail=1

Axis 2 — 5-axis handler completeness

# For each per-op file, verify pub const handlers exports all 5 axes.
for f in $(find src/instruction/wasm_X_Y -name '*.zig'); do
  for axis in validate lower arm64 x86_64 interp; do
    if ! grep -qE "\.${axis}[[:space:]]*=" "$f"; then
      echo "MISS $f.$axis"
      fail=1
    fi
  done
done

Axis 3 — feature_level metadata consistency

# Cross-reference each op file's wasm_level against the canonical mapping.
python3 scripts/check_wasm_level_mapping.py \
  src/instruction/wasm_X_Y \
  .dev/wasm_3_0_zirop_mapping.md

(Python helper lands alongside §9.12-G when the mapping doc is machine-generated by dispatch_collector.)

Axis 4 — build-option DCE sampling

bash scripts/check_build_dce.sh --sample 3

Report

Lands at private/dispatch_audit-YYYY-MM-DD.md:

# Dispatch consistency audit — YYYY-MM-DD

Mode: post_9_12_B
Generated: <timestamp>

## Axis 1 — ZirOp ↔ per-op file
- ZirOp tag count: 581
- populated file count: 581
- diff: (none)
- status: OK

## Axis 2 — 5-axis handler completeness
- files inspected: 581
- missing axes: 0
- status: OK

## Axis 3 — feature_level mapping
- mismatches: 0
- status: OK

## Axis 4 — build-option DCE (sample 3)
- v1_0:p1 → clean
- v2_0:p2 → clean
- v3_0:p1 → clean
- status: OK

## Verdict
All 4 axes consistent. Dispatch substrate is coherent.

Severity

Finding	Severity
ZirOp tag without per-op file (Axis 1)	block
Per-op file without ZirOp tag (Axis 1)	block
Missing handler on any of 5 axes (Axis 2)	block
wasm_level drift vs spec mapping (Axis 3)	block
check_build_dce sampling fail (Axis 4)	block
Pre-§9.12-B mode	defer (not a fail)

Q3 C adoption presupposes dispatch consistency; any block-level finding is a Phase 9 completion blocker.

Related

• ADR-0071 §Q3 (Phase 9 substrate audit resolution; Accepted 2026-05-19)
• ADR-0073 (build-option DCE substrate; Accepted 2026-05-19)
• ADR-0023 §4.5 amend (per-op file pattern formalised)
• Master plan §7.7 (Q3 C design consistency audit)
• scripts/check_build_dce.sh (functional A1; sampling mode used here)
• scripts/p9_completion_status.sh (deleted 2026-05-22 per ADR-0104; superseded by scripts/check_phase9_close_invariants.sh per .dev/phase9_close_master.md Phase C wiring)
• audit_scaffolding §K.7 (Phase 9 completion enforcement integration)