feat: Expose AIR column names

[georgwiese]

This PR introduces the ColumnsAir trait and makes it required by all AIRs. Via this trait, AIRs can (optionally) provide a list of column names. At powdr, we use this to generate (somewhat) human-readable autoprecompiles for OpenVM (example).

Unfortunately, this touches all AIRs and therefore a lot of files, but the changes are small and now change to stark-backend are needed.

This change represents most of our diff to OpenVM.

[georgwiese]

Note that we didn't bother implementing it for AIRs we don't build autopecompiles for. This keeps the default implementation, which returns None.

[georgwiese]

Note that it would be possible to reduce these types of changes using a macro, but it becomes a bit ugly, especially in the presence of const generics.

See this discussion: powdr-labs#60 (comment)

[georgwiese]

I implemented the macro per powdr-labs#60 (comment), but Claude has been annoying to navigate on this large diff. I'll do a review pass myself and am marking the PR as draft until then.

[georgwiese]

OK, should be clean now!

[jonathanpwang]

Please mention in PR description / docs that default implementation is always safe, since this is just for labeling purposes.

Going to wait till @shuklaayush is back to review it, but overall I feel like the new macro makes it pretty clean

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/​struct-reflection@​0.1.0

View full report

[shuklaayush]

@claude review

[claude]

Claude finished @shuklaayush's task in 2m 34s —— View job

---

PR Review: ColumnsAir trait

• Read core trait definition and derive macro
• Review key implementation patterns across AIRs
• Check integration with VM architecture (extensions, integration API)
• Review consistency across all changed files
• Post review feedback

---

Overall Assessment

This is a clean, well-structured PR. The ColumnsAir trait design is sound — the default None return makes it safe for all existing AIRs, and the derive macro with #[columns_via(...)] keeps the boilerplate minimal. The AnyAirWithColumns super-trait with trait upcasting is an elegant way to thread column introspection through the VM without touching the stark-backend API.

Positive aspects

1. Safe default — The trait provides a default fn columns(&self) -> Option<Vec<String>> { None }, so AIRs that don't have a corresponding Cols struct can just write impl ColumnsAir for X {}.

2. Derive macro is well done — The #[derive(ColumnsAir)] + #[columns_via(ColsTy<u8>)] pattern is ergonomic and catches missing attributes at compile time with a clear error message.

3. Good comments — Each manual impl ColumnsAir for X {} includes a brief explanation of why columns aren't provided (e.g., external p3-poseidon2-air cols, dynamic FieldExpr layout, slice-borrowing ref structs). This makes future maintenance much easier.

4. VmAirWrapper composition — The ColumnsAir impl for VmAirWrapper<A, M> correctly chains adapter + core columns, matching the BaseAir::width() composition. The short-circuit via ? on both is the right behavior: if either half lacks names, the whole thing returns None.

Issues and suggestions

1. Doc comment should mention the default impl is always safe (per @jonathanpwang's request)

The trait doc says column names are "for debugging purposes" but doesn't explicitly call out that the default implementation is always safe. Per Jonathan's request, this should be mentioned clearly — perhaps something like:

"The default implementation returns None and is always safe to use, as column names are purely informational and have no effect on proving or verification."

This helps downstream implementors feel confident using the default.

Fix this →

2. Allocation on every call

fn columns(&self) -> Option<Vec<String>> allocates a fresh Vec on every invocation. This is fine for debugging/tooling, but if anyone calls it in a hot path it could be surprising. Worth noting in the doc that this is intended for introspection, not performance-critical paths. Not a blocker.

3. struct-reflection dependency — new supply chain surface

The PR adds a new external crate struct-reflection = "0.1.0". Socket flagged it clean, but it's a 0.1.0 crate — worth pinning or vendoring if stability matters. The crate's purpose (generating field names from struct definitions) is well-scoped. Just calling it out for awareness.

4. Minor: AirRef import in sdk/keygen and continuations/tests

The .map(|a| a as AirRef<_>) coercion at call sites (crates/sdk/src/keygen/mod.rs:68, crates/continuations/src/tests/mod.rs:225) works via trait upcasting. This is clean and correct. One thing to note: trait upcasting is stable since Rust 1.86, and the toolchain is 1.91.1, so no concerns there.

5. Minor: unused StructReflection/StructReflectionHelper imports

Several files import StructReflection and StructReflectionHelper even though they only use them transitively through the #[derive(StructReflection)] macro (which generates the import itself). For example, in crates/vm/src/arch/execution.rs, StructReflection and StructReflectionHelper are imported but the file only adds StructReflection to derives — the derive macro should handle the trait import internally. This is minor and might be needed for some edge cases with extern crate self as, but worth double-checking if any are actually unused.

6. No runtime validation of columns().len() == width()

The doc comment says "if the result is Some(names), names.len() == air.width() should always be true" but this is not enforced. A debug assert in VmAirWrapper::columns() or in the ColumnsAir derive macro output could catch mismatches early. Not a blocker, but a nice-to-have for safety.

Fix this →

Summary

The PR is well-executed for its scope. The trait design, derive macro, and integration are all sound. The main actionable item is adding the safety note to the trait doc per Jonathan's review comment. Everything else is minor or informational.

Recommendation: Approve with the doc comment update.

---

[shuklaayush]

looks fine