Strengthen TypeScript contract checks and review

[dsfaccini]

This pull request was posted by Codex Desktop using gpt-5.6-sol on behalf of David.

Operational contract

This PR gives TypeScript changes two distinct lines of defense:

Layer	Where it appears	What it adds	Outcome we can rely on
Deterministic package checks	Existing test-js CI job through root npm run ci	stricter compiler/lint policy, API Extractor, package-root type tests, and packed-artifact validation	CI fails when implementation types, the committed public API, consumer-visible types, or the published tarball contract drift unexpectedly
Advisory agent review	New TypeScript Review workflow after CI succeeds	one Pydantic AI review of the eligible current PR head, with inline findings plus one formal verdict	while the repository agentic-workflow switch is enabled, same-repository TypeScript-relevant PR heads receive a deduplicated APPROVE or REQUEST_CHANGES review without code-write authority

Deterministic checks prove mechanical properties. The agent reviews semantic risks that are difficult to encode as compiler rules. The agent starts only after deterministic CI is green.

Deterministic checks added to npm run ci

These run inside the existing test-js job. This PR does not add duplicate CI jobs.

Check	Tool / policy	Failure means
TypeScript implementation	exactOptionalPropertyTypes, noImplicitReturns, noPropertyAccessFromIndexSignature	optional-property presence, return paths, or dynamic record access are imprecise
TypeScript lint contract	explicit errors for no-explicit-any, no-unsafe-type-assertion, switch-exhaustiveness-check, and unused disable directives	code introduces an unsafe escape hatch, misses an exhaustive branch, or carries a stale suppression
Public declaration baseline	API Extractor report generated from dist/index.d.ts	the npm package's exported type surface changed without an acknowledged report update
Package-root consumer types	tsd exact-signature assertions	consumers see a widened or narrowed function/type contract, including setProviderData silently becoming unknown
Packed npm artifact	one npm pack tarball checked by strict publint and @arethetypeswrong/cli	the publishable artifact has an export, resolution, or declaration compatibility problem

The stricter policies exposed real issues that are fixed here rather than suppressed: absent optional properties are omitted, fallthrough returns are explicit, dynamic records use bracket access, and decoded provider JSON stays unknown until validation produces precise internal and public types.

Agent added after successful CI

Property	Contract
Workflow	TypeScript Review from .github/workflows/typescript-review.md
Engine	pydantic-ai through the repository's .github/workflows/shared/pydantic.md
Engine provenance	byte-identical to github/gh-aw@db25fdfdb4ad50c5b0d10de9977b709401760378, shared with the staged triage pilot
Model	copilot/claude-sonnet-4-5
Billing/authentication	repository Copilot billing through copilot-requests: write; no repository LLM API-key secret
Runtime	.github/workflows/typescript-review.lock.yml, compiled only for this workflow with gh-aw v0.86.2
Off switch	existing AGENTIC_WORKFLOWS_ENABLED repository variable, currently enabled

Reusing the repository-local engine removes a duplicate gh-aw import cache and keeps both Pydantic AI workflows on one reviewable engine definition.

Eligibility and trust boundary

Before any PR code is checked out, eligibility proves all of the following:

• the triggering run is successful pull-request CI;
• exactly one open PR matches the triggering branch and SHA;
• the triggering repository and resolved PR head are this repository, not a fork;
• the PR is open and not draft;
• the triggering SHA is still the PR's current head;
• no equivalent TypeScript Review exists for this workflow and SHA;
• at least one relevant TypeScript, workspace, configuration, generated-data, unit/provider-data, or generator-source path changed.

Only then does the workflow check out the resolved same-repository SHA. Fork code is never checked out or executed.

Review scope and writes

The prompt covers:

• exported API widening or narrowing;
• new any, unknown, assertions, or suppressions;
• validation at untrusted boundaries;
• wire-format versus internal types;
• Promise and thenable behavior;
• generated declarations and data agreement;
• JavaScript and Python behavioral parity;
• compile-time and runtime test coverage.

The agent job is read-only. Its only writes are gh-aw safe outputs targeted to the eligibility-resolved PR number:

• up to 30 inline review comments; and
• exactly one formal APPROVE or REQUEST_CHANGES review attributed to the current head SHA.

The fresh threat-detection runner installs the same pinned Pydantic AI harness before it inspects agent output. Fallback issue creation is disabled. Reruns serialize on workflow, branch, and SHA. The eligibility marker prevents duplicate formal reviews for the same head.

What changes after merge

• Every root npm run ci enforces all three public-package contract layers after the existing build, typecheck, lint, and coverage checks.
• The first subsequent eligible same-repository PR becomes a live proof of the reviewer workflow's latency, reliability, and false-positive rate.
• The reviewer remains advisory. This PR does not change the ruleset, require the review or status, or merge code automatically.
• The existing price-check workflows and staged triage pilot remain unchanged. The TypeScript reviewer only reuses their repository-local Pydantic AI engine definition and shared off switch.

Verification

• npm run ci — passed
• make all — passed
• pre-commit run --all-files — passed
• TypeScript review eligibility tests — passed, including stale heads, forks, unrelated/relevant paths, and CI reruns
• gh aw compile typescript-review --strict --validate --no-emit with v0.86.2 — passed
• generated lock source consistency — passed; no existing workflow source or lock was recompiled

gh-aw v0.86.2 has an actionlint-wrapper defect: it filters the generated copilot-requests and concurrency.queue extension syntax to zero findings, then exits nonzero in strict mode. Direct actionlint v1.7.12 does not yet recognize those GitHub/gh-aw extensions. The same generated syntax is already present in the merged triage pilot lock.

[cubic-dev-ai]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 6 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>