Typecheck slowdown: durable `packages/ai` regression from `888da0e1` (core task/Workflow generics)

[sroussey]

Summary

tsc typecheck of the monorepo has grown from ~11s (mid-Feb 2026) to ~40s today (~3.6×). A bisection isolated two regressions; one is fixed, one is still in main and is tracked here.

Full investigation + method + timeline: docs/technical/typecheck-performance-investigation.md (added in #555). A CI guard to prevent recurrences also lands in #555 (scripts/typecheck-budget.ts).

Bisected culprits

1. 16a94b54 — MCP task schemas spread …properties + allOf, exploding packages/tasks instantiations 289k → 6.77M (23×). Already fixed (tasks back to ~207k).
2. 888da0e1 ("image generation pipeline with ImageValue boundary") — a task-runner refactor that doubled packages/ai isolated check time (0.9s → 3.4s), persisting to today. This is the open item.

Root cause (888da0e)

The cost is diffuse in the core task / Workflow generics, not in any single construct. Each Workflow.prototype.<name> = CreateWorkflow(<Task>) assignment relates two distinct Workflow<I,O> instantiations (inferred I ≠ written I in the declare module augmentation), forcing a full structural relation over the heavily augmented Workflow interface (~124 builder methods). Cost scales super-linearly with augmentation count; 888da0e1 added imageGenerate/imageEdit, tipping ai over.

Fixes prototyped and measured — all ineffective/net-negative

Measured on the real metric (deps pre-built, isolated tsc -p ai, 0 errors), baseline ai = 3.4s:

Attempt	Result
FromSchema<…> input type → hand-written interface in ToolCallingTask	no effect (3.4s)
WithImageValuePorts<…> image-task types → explicit interfaces	no effect (image tasks ~13ms each)
Restore tsBuildInfoFile line deleted from root tsconfig.json	no real effect; only changes tsc -b orchestration and breaks solution builds (TS6377)
Declare correct variance Workflow<in out Input, out Output>	no effect (3.4s → 3.58s); removes getVariancesWorker but the structural relation still runs

There is no surgical fix.

Remaining options

• Architectural: rethink how Workflow is augmented (124 CreateWorkflow<…> members in one mega-interface) and/or how AI task input types are derived. Multi-day effort; validate under both tsc and tsgo before investing.
• Operational: confirm whether user-felt slowness is tsserver (still tsc) vs build-types (already tsgo, which sidesteps most of this). Note the biggest absolute cost, packages/test (~12s), is mostly legitimate file-count growth exercising the same machinery ×N.

Mitigation already in flight (#555)

• CI typecheck-budget guard gating per-package instantiation counts. Both culprits above would have failed it.

Suggested next steps

• Decide tsc vs tsgo as the metric that matters for DX (editor responsiveness vs build).
• Spike the Workflow/CreateWorkflow augmentation refactor and measure under both compilers before committing.
• Land Add typecheck budget guard to catch type-instantiation regressions #555 (guard + writeup).

[sroussey]

Proof-slice landed (PR #555, commit 03bb8cf5)

Decisive experiments redirected the fix from the Workflow generics to FromSchema derivation:

• Disabling all 50 Workflow.prototype.X = CreateWorkflow(...) assignments in ai → only 4.29s → 4.05s (~6%). The getVariancesWorker trace time does not translate to wall cost. → "rethink Workflow augmentation" is not the lever.
• Not computing FromSchema<typeof Schema> → 4.29s → 2.69s, instantiations 564k → 193k. → AI input/output type derivation is the lever.
• Tuning FromSchema options (parseIfThenElseKeywords/parseNotKeyword → false) gave no win and was not semantically safe (changed a type), so the only capture is concrete (non-derived) types.

What landed

Converted the plain type X = FromSchema<typeof Schema> aliases for the AI Text task family + foundational model types (ModelConfig/ModelRecord) to concrete interfaces. Each concrete type is the type checker's exact resolution of the original FromSchema type (equivalent by construction; verified by a clean full tsc -b). Schemas remain the runtime contract.

Measured (pinned tsc, deps prebuilt, isolated tsc -p):

scope	instantiations	check time
ai baseline	564,545	4.29s
this 7-file slice	520,877	~3.4s
full-ai conversion (codemod, measured)	320,039 (−43%)	2.60s (−39%)
ripple on packages/test (full-ai)	1.43M → 1.18M (−14%)	12.4s → 10.7s

Tradeoff / open decision for full rollout

A hot-path Equal<X, FromSchema<typeof Schema>> drift guard is intentionally omitted — it would recompute FromSchema and defeat the win. Options for the full rollout: (a) accept hand-maintained types with schemas as the runtime contract, or (b) a dedicated typecheck-only equivalence check run as a separate CI step (like the budget guard) so it doesn't tax normal builds. The mechanical conversion of the remaining ~56 aliases can be done with the same checker-driven codemod.

---

Generated by Claude Code