feat(abi-verify): teach the converter Zig reserved words (standards#92 follow-up) (#15)

Phase 2's spot-check across the boj-server cartridge corpus found that
when an Idris2 variant snake_cases to a Zig reserved word, the cartridge
renames the Zig identifier to avoid the collision (e.g. `Error → err`
in airtable-mcp, postgresql-mcp). The verifier raised this as
`variant-missing-in-zig` + `variant-extra-in-zig` — a false-positive
class that masked real findings.

## Changes

- `manifest_schema.rs`:
  - `ZIG_RESERVED` — Zig 0.15.x reserved-word list (50 keywords)
  - `is_zig_reserved(word)` — predicate
  - `zig_reserved_workaround(word)` — cartridge convention table
    (`error → err` is the verified case; generic `<name>_` fallback
    for future cartridges that pick a different rename)
  - `zig_variant_candidates(idris_name)` — returns the snake_case form,
    plus the workaround when the snake_case is reserved
- `verify.rs`:
  - enum-variant lookup tries every candidate; first match wins
  - `manifest_keys` records every candidate so the accept-by-omission
    check doesn't flag a Zig variant the manifest legitimately covers
  - transition-table resolution uses candidates symmetrically (so
    `Error → SomeState` in the manifest matches `err → some_state`
    in the Zig switch)
  - finding messages now name every candidate tried, not just the
    snake_case form

## Verified

- 43 lib tests green (was 39; +4 new in `manifest_schema::tests`)
- `airtable-mcp` was DRIFT (Error→err false-positive), is now CLEAN
- `postgresql-mcp` now passes the reserved-word check; remaining drift
  is a separate naming-convention issue (`BeginTransaction → begin_tx`,
  abbreviation, not reserved-word — out of scope for this PR)
- `ssg-mcp`, `k9iser-mcp` unchanged (still clean)
- `007-mcp` still DRIFT (`ToolRisk` missing in Zig — that's a real
  cartridge defect, not a verifier defect, will be fixed separately)

## Note on `type`

`type` is a Zig **primitive** (alongside `bool`, `u32`, etc.), not a
reserved keyword — it's a legal identifier in enum contexts. Explicit
test pinning this so a future reader doesn't add it to the reserved
list by mistake.

Refs hyperpolymath/standards#92
Refs hyperpolymath/standards#89

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

src/abi/manifest_schema.rs

@@ -68,6 +68,51 @@ pub fn to_snake_case(s: &str) -> String {
     out
 }
 
+/// Zig 0.15.x reserved words that can collide with a snake_case-converted
+/// Idris2 variant name. When the converted name matches one of these,
+/// the cartridge convention is to rename the variant in Zig — the
+/// verifier accepts the cartridge convention as a valid alternative.
+const ZIG_RESERVED: &[&str] = &[
+    "addrspace", "align", "allowzero", "and", "anyframe", "anytype", "asm",
+    "async", "await", "break", "callconv", "catch", "comptime", "const",
+    "continue", "defer", "else", "enum", "errdefer", "error", "export",
+    "extern", "fn", "for", "if", "inline", "linksection", "noalias",
+    "noinline", "nosuspend", "null", "opaque", "or", "orelse", "packed",
+    "pub", "resume", "return", "struct", "suspend", "switch", "test",
+    "threadlocal", "try", "union", "unreachable", "usingnamespace", "var",
+    "volatile", "while",
+];
+
+pub fn is_zig_reserved(word: &str) -> bool {
+    ZIG_RESERVED.contains(&word)
+}
+
+/// Cartridge-convention workaround for a Zig reserved word. Verified
+/// against the actual `*_ffi.zig` corpus on `boj-server/main`:
+///   `error` → `err` (airtable-mcp, postgresql-mcp, others)
+///   _other_ → `<name>_` generic suffix fallback (Zig accepts this and
+///   no current cartridge uses a non-`error` reserved word; will be
+///   refined if a real cartridge picks a different convention)
+fn zig_reserved_workaround(reserved: &str) -> String {
+    match reserved {
+        "error" => "err".to_string(),
+        other => format!("{}_", other),
+    }
+}
+
+/// Candidate Zig identifiers for a variant name. Returns the snake_case
+/// form first; if that's a Zig reserved word, the cartridge-convention
+/// workaround is appended as a fallback. The verifier accepts a match
+/// against any candidate.
+pub fn zig_variant_candidates(idris_name: &str) -> Vec<String> {
+    let snake = to_snake_case(idris_name);
+    if is_zig_reserved(&snake) {
+        vec![snake.clone(), zig_reserved_workaround(&snake)]
+    } else {
+        vec![snake]
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -82,4 +127,38 @@ mod tests {
         assert_eq!(to_snake_case("ReadyToDeploy"), "ready_to_deploy");
         assert_eq!(to_snake_case("Hugo"), "hugo");
     }
+
+    #[test]
+    fn detects_zig_reserved_words() {
+        assert!(is_zig_reserved("error"));
+        assert!(is_zig_reserved("test"));
+        assert!(is_zig_reserved("struct"));
+        assert!(!is_zig_reserved("foo"));
+        assert!(!is_zig_reserved("err"));
+        // `type` is a Zig PRIMITIVE, not a reserved keyword, so the
+        // identifier is legal — no workaround needed.
+        assert!(!is_zig_reserved("type"));
+    }
+
+    #[test]
+    fn candidates_pass_through_non_reserved() {
+        let c = zig_variant_candidates("Empty");
+        assert_eq!(c, vec!["empty".to_string()]);
+    }
+
+    #[test]
+    fn candidates_include_workaround_for_reserved() {
+        // The real airtable-mcp / postgresql-mcp case: Error → err.
+        let c = zig_variant_candidates("Error");
+        assert_eq!(c, vec!["error".to_string(), "err".to_string()]);
+    }
+
+    #[test]
+    fn candidates_use_generic_suffix_for_other_reserved() {
+        // No current cartridge uses these; lock in the fallback behaviour
+        // for a genuinely-reserved keyword (`test` is reserved; `type` is
+        // a primitive and would not trigger the workaround).
+        let c = zig_variant_candidates("Test");
+        assert_eq!(c, vec!["test".to_string(), "test_".to_string()]);
+    }
 }

src/abi/verify.rs

@@ -16,7 +16,7 @@ use std::path::Path;
 use anyhow::{Context, Result};
 use serde::Serialize;
 
-use crate::abi::manifest_schema::{AbiManifest, to_snake_case};
+use crate::abi::manifest_schema::{AbiManifest, to_snake_case, zig_variant_candidates};
 use crate::abi::zig_ffi_parser::{ZigEnum, ZigFfi, parse as parse_zig};
 
 #[derive(Debug, Clone, Serialize)]
@@ -95,17 +95,34 @@ pub fn verify(
         };
         let mut manifest_keys: BTreeSet<String> = BTreeSet::new();
         for v in &manifest_enum.variants {
-            let zig_name = to_snake_case(&v.name);
-            manifest_keys.insert(zig_name.clone());
-            match zig_enum.variants.get(&zig_name) {
+            let candidates = zig_variant_candidates(&v.name);
+            // Pick the first candidate that appears in the Zig enum;
+            // if none do, the variant is missing.
+            let resolved: Option<(String, i64)> = candidates
+                .iter()
+                .find_map(|c| zig_enum.variants.get(c).map(|&val| (c.clone(), val)));
+            // Record every candidate as "claimed by the manifest" so the
+            // accept-by-omission check downstream doesn't flag a Zig
+            // variant that the manifest legitimately covers via either
+            // its primary name or its reserved-word workaround.
+            for c in &candidates {
+                manifest_keys.insert(c.clone());
+            }
+            match resolved {
                 None => findings.push(Finding {
                     kind: "variant-missing-in-zig".into(),
                     detail: format!(
-                        "enum `{}` variant `{}` (Zig: `{}`) is in the manifest but absent from the Zig FFI",
-                        manifest_enum.name, v.name, zig_name
+                        "enum `{}` variant `{}` (Zig candidates: {}) is in the manifest but absent from the Zig FFI",
+                        manifest_enum.name,
+                        v.name,
+                        candidates
+                            .iter()
+                            .map(|c| format!("`{}`", c))
+                            .collect::<Vec<_>>()
+                            .join(" / ")
                     ),
                 }),
-                Some(&actual) if actual != v.value => findings.push(Finding {
+                Some((zig_name, actual)) if actual != v.value => findings.push(Finding {
                     kind: "variant-value-mismatch".into(),
                     detail: format!(
                         "enum `{}` variant `{}` (Zig: `{}`) — manifest says {}, Zig FFI says {}",
@@ -171,11 +188,21 @@ pub fn verify(
         // Build the accepted-pair set from the manifest (only `allowed: true`
         // counts; `allowed: false` is the manifest's way of pinning a
         // safety invariant — see e.g. `ContentLoaded → Previewing` in
-        // ssg-mcp).
+        // ssg-mcp). Variants are resolved through `zig_variant_candidates`
+        // so a Zig-reserved-word-renamed variant (e.g. Error → err)
+        // matches its manifest entry.
+        let resolve = |idris_name: &str| -> String {
+            for c in zig_variant_candidates(idris_name) {
+                if zig_pairs.iter().any(|(f, t)| f == &c || t == &c) {
+                    return c;
+                }
+            }
+            to_snake_case(idris_name)
+        };
         let mut manifest_allowed: BTreeSet<(String, String)> = BTreeSet::new();
         for row in &tt.rows {
-            let f = to_snake_case(&row.from);
-            let t = to_snake_case(&row.to);
+            let f = resolve(&row.from);
+            let t = resolve(&row.to);
             if row.allowed {
                 manifest_allowed.insert((f, t));
             } else if zig_pairs.contains(&(f.clone(), t.clone())) {
@@ -205,8 +232,8 @@ pub fn verify(
                 // explicitly list — accept-by-omission is itself drift.
                 let listed_as_forbidden = tt.rows.iter().any(|r| {
                     !r.allowed
-                        && to_snake_case(&r.from) == pair.0
-                        && to_snake_case(&r.to) == pair.1
+                        && zig_variant_candidates(&r.from).contains(&pair.0)
+                        && zig_variant_candidates(&r.to).contains(&pair.1)
                 });
                 if !listed_as_forbidden {
                     findings.push(Finding {