Automate struct offset maintenance: weekly version check + monthly drift check

[rlerdorf]

Depends on #165 — this branches from fix-struct-bugs, so its first 3
commits are already under review there. The genuinely new work is the last
6 commits (Automate struct offset maintenance... through Grant the check job write permissions...); everything before that is #165 unchanged.

What this adds

Two scheduled workflows that build on the real-from-source-build approach
dump_structs.yml already uses (rather than a compile-time manifest/
offset-table system), so adding this didn't require inventing new
infrastructure -- just automating what already worked:

• check_struct_versions.yml (weekly): tools/find_php_updates.sh
  does a cheap git ls-remote check (no PHP build, ~0.5s) for newer tags
  on any PHP series phpspy already tracks, or for PHP 8.6 finally getting
  a real release tag instead of master. Only when it finds something
  does it dump the single changed version on both architectures, patch
  the existing mirror headers via tools/render_struct_update.sh, and
  open a PR -- it never auto-merges.

  A genuinely new PHP series beyond what phpspy supports (e.g. a future
  8.7) is deliberately left alone -- that needs code changes beyond struct
  data (dispatch, -V help text, README), which is a job for a human, not
  this workflow. find_php_updates.sh just notes it on stderr.

• struct_drift_check.yml (monthly): reuses dump_structs.yml's full
  24-cell matrix (now callable via workflow_call) to re-verify every
  already-pinned version still matches a fresh build, and opens an issue
  (not a PR) if anything unexpectedly drifted.

tools/patch_struct_header.awk is the core piece both workflows share: it
adjusts only a field whose offset moved plus its immediately preceding
pad, using each field's already-absolute offset comment rather than
tracking a cursor across the whole struct -- see its header comment for
why that's sufficient, and what it deliberately refuses to touch (union
blocks, a field with no adjustable preceding pad, or a negative resulting
pad size all get flagged for a human instead of silently patched).

Verification

Before ever running this in real CI:

• patch_struct_header.awk reproduces both of Fix PHP 8.6 sapi_globals offset, PHP 7.0 frame-slot bug, and get real aarch64 struct data #165's real fixes
  (x86_64/86, aarch64/86) and all 8 aarch64 placeholder replacements
  byte-for-byte against the actual committed headers.
• Idempotent across all 24 current header/arch combinations.
• All four refusal paths (no preceding pad, union field, negative pad,
  exact match) verified against synthetic fixtures.
• The full monthly drift-check loop simulated locally against all 24 real
  CI dump artifacts from Fix PHP 8.6 sapi_globals offset, PHP 7.0 frame-slot bug, and get real aarch64 struct data #165's dump_structs.yml run: zero drift on
  current data, correct drift detection when fed a known-broken fixture.

Then validated end-to-end against real GitHub Actions runs on a fork,
which surfaced four real bugs before this was trustworthy -- all fixed
and re-verified:

1. actions/checkout@v4's persisted credentials leak an Authorization
   header onto any github.com URL, not just the checked-out repo;
   find_php_updates.sh's git ls-remote against the unrelated
   php/php-src inherited it and got rejected in ~0.3s. Fixed by clearing
   it for that one invocation, and reproduced locally with a bogus header
   to confirm the fix actually addresses it.
2. A real bug in find_php_updates.sh: under set -e -o pipefail, a
   grep that legitimately finds nothing (e.g. "no php-8.6.* tag exists
   yet") aborts the whole script. My own local testing had missed this --
   wrapping the script in time was silently masking its real exit code.
3. Missing permissions: contents: write, pull-requests: write on the
   weekly workflow's PR-opening job (the default GITHUB_TOKEN is
   read-only otherwise).
4. Same class of bug in the monthly workflow's issue-opening job, caught
   by inspection since the test fork has Issues disabled and never
   actually exercised that step.

Real, closeable test artifacts from this: a PR
(closed) that correctly
detected 3 real upstream tag updates (php-8.1.34/8.2.33/8.3.33), correctly
determined none of them change any struct layout (only the pinned tags
needed bumping), and opened a real PR with that diff; and a real
struct_drift_check
run that
rebuilt all 12 versions on both architectures and correctly found zero
drift.

One thing left genuinely unverified: the "drift found -> open an issue"
path itself, since the test fork has Issues disabled and the real
monthly run found no drift to trigger it. High confidence given it's the
same permissions/gh-CLI pattern as the now-proven PR path, but flagging
it as honest, not silently assumed.

🤖 Generated with Claude Code