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

[coderdan]

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).

[tobyhede]

Inheriting the ungated-typecheck residual from #778 (2026-07-30)

The v2-removal work left a documented, deliberate typecheck gap that was pinned to #778. #778 has handed its remaining work to #816, and #816's typecheck criterion covers only the stack-drizzle clause — so the rest of the residual is about to be orphaned. It belongs here, under sub-task 1 ("a typecheck script per package covering src/ and __tests__/").

The comment at .github/workflows/tests.yml:169-176 currently reads:

NOT fully gated yet, and deliberately: @cipherstash/stack (147 errors under its own tsconfig), stash (21) and @cipherstash/stack-supabase (11). Their test:types scripts only cover __tests__/**/*.test-d.ts, so src and the runtime test suites compile nowhere. @cipherstash/stack-drizzle now type-tests every integration/** source as well; its remaining src / runtime-test errors share one root cause — V3_MATRIX's indexes union in @cipherstash/test-kit — see #778.

Adding to this issue's scope:

• @cipherstash/stack — 147 errors under its own tsconfig; src and runtime tests compile nowhere
• stash — 21 errors, same shape
• @cipherstash/stack-supabase — 11 errors, same shape
• @cipherstash/stack-drizzle — remaining src / runtime-test errors, single root cause: V3_MATRIX's indexes union in @cipherstash/test-kit
• Re-point the tests.yml:169-176 comment from EQL v2 removal: review remediation for #772 #778 to this issue, so the pin does not reference a closed issue

That last item is a one-line code change and is the only thing blocking #778's closure.