Improve CI: add tsc --noEmit + TSDoc/doc-example validation gates, expand Node matrix to 26 #531

Summary

Our PR CI (.github/workflows/tests.yml) has no type-checking or documentation-validation gate, and the test matrix lags the Node versions we support. Three related gaps:

1. Tests run via vitest run, which only transpiles — type errors never fail CI, and __tests__/ are never type-checked at all.
2. Nothing validates our TSDoc or compiles the @example snippets in doc comments.
3. The Node matrix is [22, 24] while engines is >=22.

The only de-facto type gate today is the tsup dts: true emit that happens incidentally as a build dependency — not explicit, and it doesn't validate doc prose or examples.

Motivating near-miss: in #497 the wasm-inline OidcFederationStrategy JSDoc example omitted workspaceCrn, which wouldn't have type-checked against the (then-required) field. It was caught only by a human/Copilot reviewer — no CI check would have flagged it. (We ultimately relaxed the type so the example is valid, but the gap in CI remains.)

This is a general "improve CI" task.

1. Add a tsc --noEmit typecheck gate

• Add a typecheck script per package (tsc --noEmit) covering src/ and __tests__/ — tests currently escape all type-checking.
• Wire it as a turbo typecheck task and a dedicated job in tests.yml (or fold into the existing test job).
• Acceptance: a type error in source or tests fails the PR.

2. Validate TSDoc + compile-verify doc examples

Two layers:

• TSDoc syntax validation — choose one:
  • eslint-plugin-tsdoc — precise TSDoc linting, but pulls ESLint in alongside Biome.
  • @microsoft/api-extractor — reports TSDoc warnings during a .d.ts rollup; also gives us API reports.
  • TypeDoc with --treatWarningsAsErrors — validates {@link} resolution + tag correctness and doubles as an API-doc build check.
• Compile-verify @example snippets — so an example can't silently drift from the types it documents (the feat(stack): protect-ffi 0.26.0 + auth 0.39 OidcFederationStrategy (stacked on #496) #497 case). Candidates: extract examples into a compiled fixtures dir checked by tsc, or a tool like typescript-docs-verifier that compiles fenced code blocks.
• Acceptance: a malformed TSDoc tag, an unresolved {@link}, or a non-compiling @example fails the PR.
• Recommendation: TypeDoc --treatWarningsAsErrors for syntax/{@link} + a small compiled-examples harness for snippet verification — keeps the toolchain lean since we run Biome (not ESLint) today.

Note: the existing rebuild-docs.yml only fires on release tags and curls an external DOCS_WEBHOOK_URL to rebuild a separate docs site after release. It is not a PR gate and does not validate source TSDoc.

3. Expand the Node test matrix to 26

• .github/workflows/tests.yml:17 is node-version: [22, 24] → make it [22, 24, 26] (engines is >=22).
• Caveat: Node 26 GA is expected ~Oct 2026. Until then, either hold this sub-task or track 26 via a nightly/RC (actions/setup-node supports 26-nightly). Land as GA-blocking if we want a clean green matrix.

Notes

• The dts: true tsup emit stays the declaration generator; the new typecheck task is the explicit enforcement.
• Related: Identity-bound lock-context tests never execute in CI (gated on unset USER_JWT) #530 (a separate test-coverage gap — identity-bound tests gated on USER_JWT).