Expose post-run exported-global snapshot + a witness-harness mode (coverage backend for witness MC/DC)

[avrabe]

Why

witness (MC/DC for Wasm) instruments core modules, adding exported mutable globals __witness_counter_<id>, and reads coverage back by snapshotting those globals after a run. It can do this for cores it runs under its embedded preview1 runtime, but not for Component-Model artifacts (wasm32-wasip2/p3): a component must run through a runtime's component API, and wasmtime's component::Instance gives no way to read the inner core's globals.

kiln is the opportunity here: we own it, it already does Component-Model decode/instantiation + WASI 0.2, it's no_std/deterministic/formally-verified (a certifiable coverage runtime is on-thesis), and it already reads globals internally (kiln-instructions … get_global, kiln-runtime/global.rs). Exposing that outward makes kiln a witness coverage backend — and lets us run the same instrumented artifact under kiln and wasmtime to differentially cross-check (kiln validated against wasmtime as oracle while it matures). Strategy tracked in pulseengine/witness#110.

The ask (concrete)

1. Post-run exported-global snapshot API. After running a module/component, read the values of exported globals by name (or a snapshot of all __witness_counter_*). The internal machinery exists (get_global by index + export info); this needs an outward, post-run accessor keyed by export name, reachable from a host driver. Return type: name → integer value.

2. Harness/CLI mode usable by witness. A kilnd invocation (or library entry) that witness's --harness can call: it receives WITNESS_MODULE / WITNESS_MANIFEST / WITNESS_OUTPUT env vars, instantiates + runs the module (invoking the specified export(s)), then writes the counter snapshot (step 1) to WITNESS_OUTPUT in witness's counter-snapshot JSON shape. (Happy to share that shape.)

3. Coverage-grade imports. For coverage we need imports satisfied only enough that branches execute — functionally-correct WASI is not required; stubbed/no-op wasi:* is acceptable. Flag which wasi:0.2 interfaces are real vs. need stubbing for a syscall-heavy fused core.

Scope / non-goals (for now)

• p3 async-lift / streams are out of scope here — that's gated on p3 execution maturity (kiln parses stream<>/future<> types but doesn't execute async-lift tasks yet; nobody really does). Tracked separately as witness REQ-057 / witness#107(B).
• This is about synchronous Component-Model coverage first.

How witness uses it

meld fuse component.wasm -o core.wasm        # leaf/syscall-heavy → single core
witness instrument core.wasm -o inst.wasm    # adds __witness_counter_* globals
witness run inst.wasm --harness 'kilnd …'    # kiln runs it, dumps counters
                                             # witness reconstructs the MC/DC truth tables

Refs: pulseengine/witness#110 (strategy + dual-runtime cross-check), witness DEC-003 (counter mechanism), witness REQ-054/FEAT-034 (meld composition).

🤖 Drafted with Claude Code

[avrabe]

Triaged and landed in rivet (#341): REQ_WITNESS_COV (the capability, release-v0.4.0) + AD-MCDC-001 (the regime decision — kiln dogfoods the same MC/DC regime the sibling tools follow; AD-QUALITY-001 currently lists Verus/Kani/fuzz/WAST/Miri but omits MC/DC, so this closes that gap). rivet validate: 0 errors.

Feasibility — confirmed against the code, the hard part already exists:

• `ModuleInstance::global_by_name()` (`kiln-runtime/src/module_instance.rs:306`) + `GlobalWrapper::get()` (`module.rs:4291`) already read exported globals by name on a live core instance — all ValueTypes incl. i32/i64.
• Export metadata (name / `ExportKind::Global` / index) is a `DirectMap` lookup (`module.rs:2823`).
• Your pipeline runs `meld fuse … -o core.wasm` first, so the instrumented artifact is a core module — `global_by_name` applies directly; no live-component global traversal needed for the primary path. That simplifies (1) a lot.

So the new work is mostly wiring + serialization:

1. Snapshot API — a thin prefix-keyed accessor over `global_by_name` returning name→int. Buildable now.
2. `kilnd --harness` mode — reads `WITNESS_MODULE`/`WITNESS_MANIFEST`/`WITNESS_OUTPUT`, instantiates+runs, invokes the export(s), writes the snapshot.
3. wasi:0.2 stub inventory — implemented today: `filesystem, cli, clocks, io, random` (`kiln-wasi`, default features). For a syscall-heavy fused core we'd add no-op stubs for anything outside that set; I'll enumerate the gaps against a real fused core.

Two things I need from you to build Phase 2 (the harness output):

1. The counter-snapshot JSON shape `WITNESS_OUTPUT` expects (you offered to share it) — exact keys/types. Is it `{ "__witness_counter_0": 3, … }` or a richer envelope (run id, module hash, manifest ref)?
2. The harness invocation contract — does `witness run --harness 'kilnd …'` pass the module path as an arg, or purely via `WITNESS_MODULE`? And which export(s) to invoke — from `WITNESS_MANIFEST`, a fixed entry (`_start`/`run`), or a CLI arg?

Plan: Phase 1 (snapshot API, TDD) lands independent of the JSON shape; Phase 2 (harness emit) follows once (1)/(2) are pinned. I'll keep it on the dual-runtime cross-check track (kiln validated against wasmtime as oracle) per witness#110.

[avrabe]

Great — and your feasibility read is right: because the pipeline meld-fuses to a core before instrumenting, global_by_name() applies directly and there's no live-component global traversal on the primary path. Here are both answers, pinned to witness's code (crates/witness-core/src/run_record.rs HarnessSnapshot, and the harness driver in crates/witness/src/run.rs:run_via_harness).

(1) Counter-snapshot JSON shape — target witness-harness-v1 first

It's a minimal envelope, not a rich one — witness already has the manifest (it loads WITNESS_MANIFEST itself) and stamps run-id/module path into the run record, so the snapshot is just schema + counters:

{
  "schema": "witness-harness-v1",
  "counters": { "0": 7, "1": 0, "2": 3 }
}

Important correction to your guess: the counters keys are the bare numeric branch id as a string ("0", "1", …), not "__witness_counter_0". witness does key.parse::<u32>() on them (into_id_map, run_record.rs:295). So the harness reads each exported global named __witness_counter_<id>, strips the __witness_counter_ prefix, and emits { "<id>": value }. Value is the hit count (u64).

Type note (v0.32+): the hit counters are now i64 globals (overflow-safe). global_by_name → read the i64, emit as the integer value. (brval/brcnt globals stay i32, but those are v2 — see below.)

That's the whole v1 contract: {schema, counters}. No run id / module hash / manifest ref in the snapshot.

→ This gives branch coverage (per-branch hit counts), which is plenty for Phase 1/2 and the dual-runtime cross-check.

Later, for full MC/DC there's witness-harness-v2: adds rows: [{ name, outcome, brvals{}, brcnts{}, trace_b64 }] (per-invocation captures, with __witness_trace_reset/__witness_row_reset called between rows). Definition: HarnessSnapshot/HarnessRow in run_record.rs; worked example in the run.rs tests (search witness-harness-v2). Don't build v2 yet — v1 unblocks the run-path and the cross-check.

(2) Harness invocation contract

witness spawns your command via sh -c '<harness_cmd>' and passes everything by env var (not CLI args):

env var	meaning
WITNESS_MODULE	abs path to the instrumented .wasm (read this)
WITNESS_MANIFEST	abs path to the .witness.json manifest (branch list; needed for v2 per-row, optional for v1)
WITNESS_OUTPUT	abs path the harness must write the snapshot JSON to

• Module path: purely WITNESS_MODULE. witness does not append it as an arg — it runs your literal --harness 'kilnd …' string. So kilnd should read WITNESS_MODULE (a non-zero exit, or no file at WITNESS_OUTPUT, is treated as harness failure).
• Which exports to invoke: the harness chooses. In harness mode witness's own --invoke / --invoke-with-args are ignored — witness hands you the module+manifest and reads counters back; what to run is the harness's call. For v1, run the module however exercises it (e.g. call _start, or the fixture's run_row_*/named exports) and snapshot counters at the end. (For v2 you'd invoke per-row and reset between — later.)

Net for kiln Phase 1/2

• Phase 1 (snapshot API): thin prefix accessor over global_by_name — for each export matching __witness_counter_*, map <id> → value. Independent of everything above. ✅ buildable now.
• Phase 2 (kilnd --harness): read WITNESS_MODULE, instantiate+run, invoke export(s), write { "schema":"witness-harness-v1", "counters": {…} } to WITNESS_OUTPUT.

Then witness run inst.wasm --harness 'kilnd …' round-trips, and we can diff kiln's counters against the wasmtime path on the same instrumented artifact (witness#110 cross-check). Ping me when Phase 2 lands and I'll wire up the differential compare on the witness side.

[avrabe]

Phase 2 is up — #343. kilnd is now a witness harness end-to-end.

Verified against the real binary through your exact env contract:

$ wasm-tools parse cov.wat -o inst.wasm     # _start hits __witness_counter_0 3x
$ WITNESS_MODULE=inst.wasm WITNESS_OUTPUT=out.json kilnd ; echo $?
0
$ cat out.json
{"schema":"witness-harness-v1","counters":{"0":3,"1":0}}

Implements the pinned contract exactly: reads WITNESS_MODULE, runs the meld-fused core (invokes first of [_start, run, 0, 1, main]), snapshots __witness_counter_*, strips the prefix to the bare numeric id (numeric-ordered), writes {"schema":"witness-harness-v1","counters":{…}} to WITNESS_OUTPUT; non-zero exit on failure. i64 counters. TDD throughout (4 tests, RED-watched + mutation-proven).

Ready for the dual-runtime cross-check (witness#110) — point witness run inst.wasm --harness 'kilnd' at it and diff kiln's counters against the wasmtime path on the same instrumented artifact. Ping me if the entry-export set needs tuning for your fused cores, or once you wire the differential compare.

Two follow-ups I deliberately deferred (tracked in REQ_WITNESS_COV):

1. wasi:0.2 no-op stubs for syscall-heavy fused cores — today filesystem/cli/clocks/io/random are real; anything outside that set currently fails loud at instantiate rather than no-op stubbing. Send me a representative fused core and I'll enumerate the gap + add the stub layer (Phase 3).
2. witness-harness-v2 per-row MC/DC — holding per your "don't build yet."