perf(executors): lazy-load the executor registry — defer class imports + construction to first use (#11220)

[oyi77]

Summary

Implements the on-demand executor loading proposed in #11220 (the lazy PROVIDERS Proxy facet already exists upstream in open-sse/config/constants.ts:74; this PR covers the remaining two facets: the executor barrel and per-use construction).

Measured problem (isolated DATA_DIR, tsx/esm)

Phase	Before	After
Barrel import (all ~100 executors)	1295–1923 ms, ~65 MB heap	712–832 ms, ~45 MB
Marginal cost of the ~100 unused executors at boot	~0.7–1.2 s + ~35 MB	~0
First use of one executor	—	+120–150 ms, once

The barrel previously pulled every executor module and constructed every instance at boot even for deployments using a handful of providers.

Design

• executors/index.ts: the declarative alias table stays byte-stable — same keys, same order, same ctor args — but each value is now a deferred loader (() => import("./x.ts").then(m => new m.XExecutor(...))). Bundlers split these into on-demand chunks.
• executors/registry.ts: new registerLazyExecutor / loadRegisteredExecutor. Aliases are declared EAGERLY so hasSpecializedExecutor() and listExecutorAliases() remain synchronous and include lazy aliases; the instance materializes once on first use and caches into the same registry map a static registration would have used. Concurrent first uses share one in-flight load.
• getExecutor() is now async; all production call sites await it: chatCore proxy resolver (direct/cliproxyapi/dario/fallback legs), video generation (Veo free), compression judge + eval clients (resolved per call inside complete(), keeping the sync factory signatures), quotaAutoPing deps type, anthropic OAuth validation.
• The cliproxy wrapper ExecutorLike types drop their [key: string]: unknown index signatures so BaseExecutor satisfies them structurally under the newly-explicit return type.

Contract preserved

The golden lock (tests/unit/executor-map-golden.test.ts) passes with a byte-identical snapshot: keys, classes, provider identities and dispatch guards unchanged. Each alias still gets its OWN instance (aliases never share), matching previous semantics.

Test impact

24 unit suites adapted mechanically to the async seam: await getExecutor(...), async callbacks, union narrowing on the Response | { response } execute result, and class imports moved from the barrel to their module files. Guard tests converted from assert.throws to await assert.rejects with identical status/message assertions.

Verification:

• golden locks (executor-map / g13-combo-chatcore / provider-translate-path): 8/8 pass
• updated executor suites: 244/244 + 152/152 pass
• executor-web-cookie-sweep SIGABRT failure is PRE-EXISTING — reproduced identically on the stashed clean base
• pre-commit lint-staged suppression drift also reproduced on clean base (documented in commit)

Base: release/v3.8.51 (3192eb88d).

[oyi77]

CI triage + real fix pushed (514a0fd)

Genuine regression — FIXED in this push

Round 1 of the test migration only covered suites importing from executors/index.ts directly. Suites importing getExecutor through other paths (open-sse root re-export, dynamic imports inside tests) still called it synchronously → Promise instanceof X assertion failures (e.g. providers-yuanbao-web). A repo-wide sweep found 35 more suites; all adapted mechanically in 514a0fd. Locally verified green: providers-yuanbao-web, ninerouter-executor, provider-request-failure-pipeline, provider-limits-accesstoken-fallback-on-refresh-failure, executor-registry, chatcore-executor-proxy, poe-api-executor-regression, web-cookie-providers-new — 113/113 pass.

Remaining red checks after that fix

Check	Verdict	Evidence
No new ESLint warnings / Fast Quality Gates	Pre-existing on base	"suppressions left that do not occur anymore" reproduced verbatim on stashed clean release/v3.8.51. Green PRs (#11428/#11429/#11434) target release/v3.8.50 with different suppression state.
dast-smoke	Does not reproduce from this diff	Fuzz 500s hit DELETE /api/keys/{id}, OPTIONS /api/keys, OPTIONS /api/auth/logout; probed locally against this branch: 204/401/204 (documented statuses). Unrelated to executor resolution.
Any residual unit-shard failures	Flakes	ollama-local-embedding-2824 (rmSync ENOTEMPTY race in its own after-hook) and token-health-check-kimi (jitter timing) both fail at most 1/8500 tests per shard, in files untouched here, and pass locally.

[diegosouzapw]

Solid piece of engineering — the eager-alias/lazy-instance registry design preserves the golden snapshot and we confirmed check:cycles and the golden locks pass on your branch. Two mechanical blockers, both reproduced locally: (1) check:known-symbols hard-fails because it parses the literal name const executors = { which you renamed to lazyExecutors — please update scripts/check/check-known-symbols.ts (or keep the name); (2) dropping the eslint-disable-next-line in EditConnectionModal.tsx introduces a new set-state-in-effect error and is your only conflict with the base — restoring the comment resolves both problems at once.

[oyi77]

Both blockers are fixed in 11db30065 (pushed to this branch):

1. check-known-symbols literal — took your update-the-checker option: extractExecutorAliases now matches "const lazyExecutors" instead of "const executors = {". Deliberately without the = { suffix, because commit eb144cd (#11220) left a type annotation between name and initializer (const lazyExecutors: Record<string, () => Promise<BaseExecutor>> = {), so the old full-string match could never hit again. Verified: npx tsx scripts/check/check-known-symbols.ts now gets past extraction and reaches the alias-validation stage; its remaining output is the pre-existing missing-executor set that also fails on a clean base — untouched by this branch.

2. EditConnectionModal.tsx — the dropped eslint-disable-next-line comment is restored verbatim, which was also our only conflict with the base, so both problems resolved together as you said.

On the current CI reds (Docs Gates / unit shards / Vitest / ESLint-suppressions gate): same upstream-tip drift we've been tracking — reproduced at the current merge ref with none of this branch's content: check:docs-counts fails STRICT on README/AGENTS/llm.txt still saying "159 migrations" while code has 160, and tests/unit/agent-card-route.test.ts + providers-constants-split.test.ts fail at the tip itself. They'll clear from every open PR whenever the counts bump lands.