fix(wire-shape): close 4 review-surfaced gaps

- load_baseline raises SystemExit with regen hint when the JSON file
  is malformed instead of dumping an opaque traceback.
- write_baseline cleans up its tmp sidecar on any exception so a
  crashed run can't poison the next refresh from the same PID.
- The validator now exits 1 (not 0) when AXONFLOW_OPENAPI_SPECS_DIR
  is set but doesn't point at a directory. A misconfigured CI step
  silently disabling the gate produces a green check on a non-running
  validator, which we refuse to do. An unset env still skips with 0.
- Workflow's SHA-bump guard distinguishes "baseline missing on base
  branch" (genuine first-pin introduction) from "baseline present
  but unparseable" (bypass attempt). A malformed baseline on the
  base branch can no longer route a labelless PR through the
  first-pin path.
- Java source parser:
    * Recognises Java 15+ text blocks (`"""..."""`). Previously the
      first `"""` looked like quote-empty-quote and the body parsed
      as live source — fake `@JsonProperty(...)` and `class X {`
      inside a text block silently corrupted attribution.
    * Filters annotation matches whose position falls inside a
      blanked range (string, comment, text block) so the wire-name
      regex on raw content can't grab annotations the structural
      pass already nullified.
    * Attributes record-parameter annotations to the record. Pending
      decls are now tracked between their token and the body `{`,
      so `record Foo(@JsonProperty("x") int x) {}` no longer drops
      the wire name. The SDK has no records today; this is forward
      defence for the next type-class refactor.
- Documents the remaining anonymous-inner-class limitation (no
  `class` keyword, so annotations would leak to the enclosing type).
  The SDK does not put @JsonProperty inside anonymous inners.

Synthetic-fixture tests cover record params, text blocks with fake
annotations, line and block comments, nested classes, and enum
values. Real Java SDK baseline unchanged: 70 registered types, 39
drift, 8 cross-spec, 1 intra-file.

Author: saurabhjain1592

.github/workflows/wire-shape-contract.yml

@@ -72,13 +72,27 @@ jobs:
           PR_SHA: ${{ steps.specs_sha.outputs.sha }}
         run: |
           set -e
-          BASE_SHA=$(
-            git show "origin/${BASE_REF}:tests/fixtures/wire-shape-baseline.json" 2>/dev/null \
-              | python3 -c "import json, sys; print(json.load(sys.stdin).get('openapi_specs_sha','') or '')" \
-              || true
-          )
+          BASE_FILE=$(mktemp)
+          if git show "origin/${BASE_REF}:tests/fixtures/wire-shape-baseline.json" > "$BASE_FILE" 2>/dev/null; then
+            # File exists on the base branch. It MUST parse — a malformed
+            # baseline file would otherwise let `BASE_SHA` come back empty
+            # and route this PR through the "first pin introduction"
+            # bypass below, silently authorizing a SHA bump.
+            BASE_SHA=$(python3 -c "import json, sys; print(json.load(open(sys.argv[1])).get('openapi_specs_sha','') or '')" "$BASE_FILE")
+          else
+            # File genuinely absent on the base branch (first-time
+            # introduction). Distinguishing this from "file present but
+            # unparseable" is what guards the bypass.
+            BASE_SHA=""
+          fi
+          rm -f "$BASE_FILE"
           if [ -z "$BASE_SHA" ]; then
-            echo "::notice::Base branch has no openapi_specs_sha yet; treating this PR as first pin introduction."
+            if git cat-file -e "origin/${BASE_REF}:tests/fixtures/wire-shape-baseline.json" 2>/dev/null; then
+              echo "::error::tests/fixtures/wire-shape-baseline.json on origin/${BASE_REF} parsed with empty openapi_specs_sha."
+              echo "::error::This is unrecoverable from inside the gate. Re-run scripts/wire_shape/refresh.py on main."
+              exit 1
+            fi
+            echo "::notice::Base branch has no wire-shape-baseline.json yet; treating this PR as first pin introduction."
             exit 0
           fi
           if [ "$BASE_SHA" = "$PR_SHA" ]; then

scripts/wire_shape/lib.py

@@ -20,6 +20,14 @@ class whose body contains them.
 - Avoids the `mvn compile` round-trip in CI and stays dependency-free
   beyond PyYAML. If nested-generic or annotation-inside-string edge
   cases start causing false positives, switch to `javalang`.
+- Record-parameter annotations (`record Foo(@JsonProperty("x") int x)`)
+  are attributed to the record because the parser tracks pending
+  decls between their token and their body `{`.
+- Anonymous inner classes (`new Foo() { @JsonProperty("x") ... }`) do
+  NOT have a `class` keyword, so their annotations leak to the
+  enclosing type. This SDK does not put `@JsonProperty` inside
+  anonymous inners; if that ever lands, the `<anon>` sentinel pattern
+  is the place to add coverage.
 """
 
 from __future__ import annotations
@@ -178,8 +186,26 @@ def _strip_strings_and_comments(src: str) -> str:
                 j += 2
             i = j
             continue
-        # String / char literal. Handles escapes; skips newlines (text
-        # blocks in Java 15+ break this but none of our SDK types use them).
+        # Java 15+ text block: `"""..."""`. Without explicit handling,
+        # the leading `"""` looks like quote-emptyString-quote, then
+        # content runs as live source until a stray `"` rebalances.
+        if c == '"' and src[i : i + 3] == '"""':
+            j = i + 3
+            out[i] = out[i + 1] = out[i + 2] = " "
+            while j < n and src[j : j + 3] != '"""':
+                if src[j] != "\n":
+                    out[j] = " "
+                j += 1
+            if j < n:
+                out[j] = out[j + 1] = out[j + 2] = " "
+                j += 3
+            i = j
+            continue
+        # String / char literal. Handles escapes; preserves newlines so
+        # offsets line up with the original text. Java string literals
+        # cannot span newlines (text blocks above are the only multi-
+        # line form), so a bare newline mid-quote is a malformed source
+        # we let fall through.
         if c == '"' or c == "'":
             quote = c
             j = i + 1
@@ -228,19 +254,24 @@ def _extract_types_from_java(content: str) -> dict[str, list[str]]:
     # @JsonProperty annotations: match on the RAW content so the
     # wire-name string literal is preserved. Positions line up with
     # `cleaned` because string-stripping replaces in place without
-    # changing length.
+    # changing length. Filter out matches whose `@` falls inside a
+    # blanked range (string literal, comment, text block) — the
+    # cleaner replaces those with whitespace, so cleaned[m.start()]
+    # is a space rather than the original `@`.
     props: list[tuple[int, str]] = [
-        (m.start(), m.group(1)) for m in _JSON_PROPERTY_RE.finditer(content)
+        (m.start(), m.group(1))
+        for m in _JSON_PROPERTY_RE.finditer(content)
+        if m.start() < len(cleaned) and cleaned[m.start()] == "@"
     ]
 
-    # Walk the cleaned source, tracking a stack of (open_brace_pos, type_name).
-    # When we see `class X` followed (after modifiers/generics) by `{`,
-    # push X onto the stack at that depth. Pop on matching `}`.
-    stack: list[str] = []
-    # Map from brace_depth_at_open -> type_name, so we only pop type
-    # frames when the matching `}` fires (not every random `{` in
-    # method bodies / initializers).
-    type_frames: dict[int, str] = {}
+    # Walk the cleaned source. Two queues: decls already seen but
+    # whose body `{` hasn't been hit yet (pending), and active type
+    # frames (stack). Annotations attribute to the innermost pending
+    # decl (record-parameter case) if any, otherwise the innermost
+    # active frame. This keeps record(@JsonProperty(...) X x) {} from
+    # silently dropping its annotations.
+    pending_decls: list[str] = []
+    stack: list[tuple[int, str]] = []  # (depth_at_open, type_name)
     depth = 0
     next_decl_idx = 0
     next_prop_idx = 0
@@ -249,41 +280,47 @@ def _extract_types_from_java(content: str) -> dict[str, list[str]]:
     i = 0
     n = len(cleaned)
     while i < n:
-        c = cleaned[i]
+        # Promote any decls whose name token has now been passed.
+        while next_decl_idx < len(decls) and decls[next_decl_idx][0] <= i:
+            pending_decls.append(decls[next_decl_idx][1])
+            next_decl_idx += 1
 
-        # Consume any pending annotation at or before this index.
+        # Consume any annotation at this position. Pending-decl wins
+        # so record params attribute correctly.
         while next_prop_idx < len(props) and props[next_prop_idx][0] <= i:
             _, wire = props[next_prop_idx]
-            if stack:
-                result.setdefault(stack[-1], []).append(wire)
+            owner = (
+                pending_decls[-1] if pending_decls
+                else stack[-1][1] if stack
+                else None
+            )
+            if owner is not None:
+                result.setdefault(owner, []).append(wire)
             next_prop_idx += 1
 
+        c = cleaned[i]
         if c == "{":
-            # Is this the opening brace of the most recent unconsumed
-            # class declaration? i.e. the declaration's class-name
-            # token ended before this `{` and no other `{` has consumed it.
-            if (
-                next_decl_idx < len(decls)
-                and decls[next_decl_idx][0] <= i
-            ):
-                name = decls[next_decl_idx][1]
-                stack.append(name)
-                type_frames[depth] = name
-                next_decl_idx += 1
+            if pending_decls:
+                # This brace opens the body of the oldest pending decl.
+                name = pending_decls.pop(0)
+                stack.append((depth, name))
             depth += 1
         elif c == "}":
             depth -= 1
-            if depth in type_frames:
-                type_frames.pop(depth)
-                if stack:
-                    stack.pop()
+            if stack and stack[-1][0] == depth:
+                stack.pop()
         i += 1
 
     # Consume any trailing annotations (defensive; shouldn't happen).
     while next_prop_idx < len(props):
         _, wire = props[next_prop_idx]
-        if stack:
-            result.setdefault(stack[-1], []).append(wire)
+        owner = (
+            pending_decls[-1] if pending_decls
+            else stack[-1][1] if stack
+            else None
+        )
+        if owner is not None:
+            result.setdefault(owner, []).append(wire)
         next_prop_idx += 1
 
     return {k: sorted(set(v)) for k, v in result.items() if v}
@@ -323,24 +360,42 @@ def empty_baseline() -> dict[str, Any]:
 def load_baseline() -> dict[str, Any]:
     if not BASELINE_PATH.exists():
         return empty_baseline()
-    with BASELINE_PATH.open() as f:
-        parsed = json.load(f)
+    try:
+        with BASELINE_PATH.open() as f:
+            parsed = json.load(f)
+    except json.JSONDecodeError as e:
+        # Truncated mid-write, hand-edited and corrupted, or otherwise
+        # not parseable. Fail loudly with a regeneration hint instead
+        # of letting the validator bail with an opaque traceback.
+        raise SystemExit(
+            f"❌ tests/fixtures/wire-shape-baseline.json is malformed "
+            f"({e.__class__.__name__}: {e}).\n"
+            f"   Regenerate via:\n"
+            f"     python3 scripts/wire_shape/refresh.py "
+            f"<axonflow community specs dir>"
+        ) from None
     base = empty_baseline()
     base.update(parsed)
-    base["cross_spec_duplicates"] = parsed.get("cross_spec_duplicates", {})
-    base["intra_file_duplicates"] = parsed.get("intra_file_duplicates", {})
-    base["registered_types"] = parsed.get("registered_types", [])
-    base["per_type_drift"] = parsed.get("per_type_drift", {})
     return base
 
 
 def write_baseline(baseline: dict[str, Any]) -> None:
     BASELINE_PATH.parent.mkdir(parents=True, exist_ok=True)
     tmp = BASELINE_PATH.with_suffix(f".json.tmp.{os.getpid()}")
-    with tmp.open("w") as f:
-        json.dump(baseline, f, indent=2, sort_keys=True)
-        f.write("\n")
-    tmp.replace(BASELINE_PATH)
+    try:
+        with tmp.open("w") as f:
+            json.dump(baseline, f, indent=2, sort_keys=True)
+            f.write("\n")
+        tmp.replace(BASELINE_PATH)
+    except BaseException:
+        # If anything fails between open() and replace(), don't leave
+        # a stray .tmp.<pid> sidecar — the next run from the same PID
+        # would collide and confuse a future writer.
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
 
 
 def difference(a: list[str], b: list[str]) -> list[str]:

scripts/wire_shape/validate.py

@@ -35,27 +35,35 @@
 )
 
 
-def _specs_dir() -> Path | None:
+def main() -> int:
     env = os.environ.get("AXONFLOW_OPENAPI_SPECS_DIR")
     if not env:
-        return None
-    p = Path(env)
-    return p if p.is_dir() else None
-
-
-def main() -> int:
-    specs = _specs_dir()
-    if specs is None:
+        # No env at all → local dev / unconfigured CI. Skip.
         print(
-            "⏭️  AXONFLOW_OPENAPI_SPECS_DIR not set to a directory; "
-            "wire-shape gate skipped."
+            "⏭️  AXONFLOW_OPENAPI_SPECS_DIR not set; wire-shape gate skipped."
         )
         print(
             "    The dedicated CI job clones getaxonflow/axonflow at the "
             "pinned SHA and exports this variable before running the "
             "validator."
         )
         return 0
+    specs = Path(env)
+    if not specs.is_dir():
+        # Env set but path is bogus. CI probably failed to check out the
+        # specs at the pinned SHA; treating that as a skip would let a
+        # broken pipeline produce a green check. Fail loudly instead.
+        print(
+            f"❌ AXONFLOW_OPENAPI_SPECS_DIR={env} is not a directory.",
+            file=sys.stderr,
+        )
+        print(
+            "   The wire-shape job's specs-checkout step must run before "
+            "this validator. A misconfigured path silently disables the "
+            "gate, which we refuse to do.",
+            file=sys.stderr,
+        )
+        return 1
 
     merged, cross_spec, intra_file = load_all_schemas(specs)
     if not merged: