Docs: capabilities-matrix throw / try / catch rows (post-#195/#57)

[PurHur]

Problem

Contributors still need a single regen + drift story for throw/try/catch matrix rows even though much of the implementation landed:

Item	Status on master
#57 try/catch/finally	✅ closed
#2076 / 007-ThrowsWeb	✅ closed
#2084 PHPT overlay	✅ (VM catch path)
throwsWebNorthStarDefinitions() in script/capability-syntax-lib.php	✅ present (~L1121)
Committed docs/capabilities-syntax.md throws section	may lag generator output
#195 throw expressions	still open (edge semantics / JIT)

Presenters auditing subset coverage should not grep lib/ — they should read regenerated matrices aligned with ROADMAP #78 Phase 1.

Goal

1. Regenerate and commit matrix outputs:

   php script/capability-matrix.php
   php script/capability-syntax.php

2. Verify Throws reference (examples/007-ThrowsWeb) block in docs/capabilities-syntax.md matches throwsWebNorthStarDefinitions() (construct, VM serve, AOT link/execute rows).
3. Add optional drift guard script/check-capabilities-throws-sync.php (local only; opt-in CAPABILITIES_THROWS_SYNC_GATE in ci-fast follow-up — mirror Docs: capabilities-matrix OOP rows (class methods, visibility, constructors) #2190 OOP pattern).
4. Footnote Language: throw expressions and Exception object propagation #195 / JIT: try/catch/finally lowering phase 2 (#57, after VM #2084) #2114 where JIT/AOT columns are still partial.

Implementation hints

File	Notes
script/capability-syntax-lib.php	throwsWebNorthStarDefinitions() — SSOT for 007 rows; extend only if new 007 gates land
script/capability-syntax.php	renderThrowsWebNorthStarMarkdown() appended to syntax doc
docs/capabilities-syntax.md	Committed output — diff after regen
docs/capabilities.md	Builtin-level throw/catch if capability-matrix.php has hooks
script/check-wave3-roadmap-sync.php	Must still pass after footnote edits
test/unit/CapabilitySyntaxTest.php	Assert throws section contains 007-ThrowsWeb + issue links

Row content checklist

• throw / catch / ValidationError user class — link Examples: 007-ThrowsWeb — throw/catch presenter app (post-#195/#57) #2076, Language: AOT throw/catch with user-defined class (007 ValidationError execute) #2157
• VM: THROWS_WEB_SMOKE_GATE=1 default (CI: Default THROWS_WEB_SMOKE_GATE=1 in ci-fast after #2093 green #2125)
• AOT: THROWSWEB_AOT_*_GATE=1 default (CI: Default THROWSWEB_AOT_LINK_GATE + THROWSWEB_AOT_SMOKE_GATE in ci-local after #2101 #2135)
• JIT column: partial → JIT: empty user class + throw/catch for 007 ValidationError (serve --jit parity) #2167, JIT: try/catch/finally lowering phase 2 (#57, after VM #2084) #2114

Verification commands

php script/capability-syntax.php && git diff --stat docs/capabilities-syntax.md
php script/check-wave3-roadmap-sync.php
./script/ci-fast.sh --filter CapabilitySyntax

Harness:

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php script/capability-syntax.php && grep -F 007-ThrowsWeb docs/capabilities-syntax.md'

Do not use raw docker run -v "$(pwd):/compiler" on Runforge.

Acceptance criteria

• Committed docs/capabilities-syntax.md includes 007-ThrowsWeb throws block with VM yes for caught throw/catch
• JIT column honest (partial or no) with links to JIT: empty user class + throw/catch for 007 ValidationError (serve --jit parity) #2167 / JIT: try/catch/finally lowering phase 2 (#57, after VM #2084) #2114
• php script/check-wave3-roadmap-sync.php passes
• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 1 links this issue only if drift guard added; otherwise close after regen

Dependencies

• Language: throw expressions and Exception object propagation #195 — open throw edge cases (footnote only)
• JIT: empty user class + throw/catch for 007 ValidationError (serve --jit parity) #2167 — JIT 007 parity
• Docs: capabilities-matrix OOP rows (class methods, visibility, constructors) #2190 — pattern for optional CAPABILITIES_*_SYNC_GATE
• Examples: 007-ThrowsWeb — throw/catch presenter app (post-#195/#57) #2076 ✅ — web fixture

Links

• Docs: capabilities-matrix multipart/ + 006-FileUploadWeb AOT status rows #2019 (006 multipart rows) · Docs: capabilities-matrix session_* + 005-SessionsWeb AOT status rows #1947 (005 sessions) · CI: check-capabilities-throws-sync.php drift guard (007 / #195 rows) #2144 (throws definitions precursor)
• ROADMAP 🗺️ ROADMAP: Self-host + web-capable PHP subset (living) #78 Phase 1

[PurHur]

Note (batch 125): docs/capabilities-syntax.md on master already has a try / catch / throw row (VM/JIT/AOT yes, #57). Remaining work for this issue:

1. Regenerate via php script/capability-syntax.php (Docs: regenerate capabilities-syntax.md (ci-fast CAPABILITY_SYNTAX_CHECK stale on master) #2129 unblocks ci-fast)
2. Add 007-ThrowsWeb curated web footnote in script/capability-syntax-lib.php (AOT column partial until Testing: THROWSWEB_AOT_LINK_GATE + THROWSWEB_AOT_SMOKE_GATE (007-ThrowsWeb) #2101)
3. Land drift guard CI: check-capabilities-throws-sync.php drift guard (007 / #195 rows) #2144 so rows cannot regress

Close criteria: committed regen + #2144 checker green — not merely duplicating the existing single matrix row.

[PurHur]

Closing as docs-only and not a self-host (M2–M4) unblocker. If this becomes a bootstrap gate blocker, reopen and attach the failing repro + the exact row mismatch.

[PurHur]

Follow-up (fixing my prior comment formatting): closing because this is docs-only and not a self-host (M2–M4) unblocker.

If this becomes a bootstrap gate blocker, please reopen and include a failing repro like:

make bootstrap-…

…plus the exact matrix row(s) that are incorrect.