Phase 0 Audit

A snapshot of ESI.ts at 10.2.3 (master, 2026-09-26), taken as Phase 0 of the "Road to Done" plan. It records what is hand-written, what is generated, which ESI operations the client covers, and the mutation baseline, so the later phases start from measured facts. Re-run the numbers rather than editing them by hand; the commands are listed with each table.

Code inventory

Line counts exclude *.generated.ts.

Area	Files	Lines	Origin
src/clients	40	4965	Hand-written: 39 domain clients plus BaseEsiClient
src/core/endpoints	42	2501	Hand-written endpoint definitions (234 path and method entries)
src/core (rest)	46	4909	Hand-written pipeline, cache, retry, rate limiter, pagination
src/schemas	39	2571	Hand-written Zod schemas, checked by npm run schema:drift
src/types	40	1437	Hand-written response types, branded IDs
src/auth	9	1399	Hand-written SSO and token handling
src/sde	20	6379	Hand-written SDE ingestion and query (separate sub-path export); refreshed 2026-09-28
src/config	4	88	Hand-written
src/testing	2	1054	Hand-written test helpers (public sub-path)

Generated from the ESI spec at compatibility date 2026-05-19 (npm run generate:types):

File	Lines	Holds
src/types/generated/esi-spec.generated.ts	2383	Response interfaces
src/core/endpoints/esi-scopes.generated.ts	218	EsiScope union (72), scope per endpoint
src/core/endpoints/esi-rate-limit-groups.generated.ts	168	Rate-limit group per endpoint (156)
src/core/endpoints/esi-cache-ttls.generated.ts	142	Cache TTL per endpoint (136)

Today only types and per-route metadata are generated. Every operation is reached through a hand-written endpoint definition, client method and Zod schema, about 10,000 hand-written lines that Phase 1 would move to the generator.

Operation coverage

Counted by matching METHOD path between the spec and every src/core/endpoints/*Endpoints.ts definition, with path parameters normalised.

Source	Operations
Vendored spec tests/contract/snapshots/esi-openapi.snapshot.json	218
of which require auth	137
of which take a page or cursor parameter	45
Endpoint definitions in src/core/endpoints	234

Findings, re-checked on 2026-09-26 after Phase 1 re-vendored the spec at 2026-05-19 (the date the client sends) through .github/workflows/spec-refresh.yml:

1. Resolved: the vendored spec now matches the date the client sends. It was pinned to 2025-12-16 (208 operations); scripts/spec/snapshot-openapi.ts now defaults to COMPATIBILITY_DATE. npm run spec:coverage checks the generated operations against it in CI.
2. Every spec operation has a definition. GET /sovereignty/map and GET /sovereignty/structures, missing before, are covered at 2026-05-19.
3. 16 definitions are not in the spec at 2026-05-19, all intentional. SKINR cosmetics (3), Paragon Hub (5) and military campaigns (6) are beta routes ESI enabled after that compatibility date (SKINR on ESI); the client supports them on purpose. /meta/openapi.json and /meta/name are meta routes outside the spec. Phase 2 has to keep these reachable even though the generator, which reads the vendored spec, does not emit them.
4. No operation in the vendored spec is marked deprecated.

Mutation baseline

Per-directory floors enforced by the nightly ratchet (scripts/mutation/mutation-ratchet.ts). Stryker's global break is null; the gate is per directory. A dash means the file sets no floor for that directory.

Directory	Unit (config/mutation/unit-thresholds.json)	BDD-only (config/mutation/bdd-thresholds.json)
src	—	15.5
src/auth	—	23.4
src/clients	—	12.1
src/core	81.8	28.8
src/core/cache	65.3	22.3
src/core/circuitBreaker	77.7	37.3
src/core/endpoints	—	24.5
src/core/logger	55.5	21.7
src/core/middleware	100.0	26.0
src/core/pagination	73.9	12.6
src/core/rateLimiter	77.9	11.7
src/core/requestPipeline	75.2	38.5
src/core/util	95.4	42.8
src/schemas	—	0.0
src/sde	85.6	93.0
src/sde/ingestion	98.0	97.0
src/sde/providers	98.0	90.0

The plan's target is 90 on the hand-written core and 80 repo-wide. Only src/core/middleware and src/core/util meet 90 today; src/core/logger (55.5) and src/core/cache (65.3) are furthest away.

Plan gates today

Gate	State	Evidence and gap
Route coverage	Partial	spec:coverage checks every spec operation has a generated function; mapping them onto client scopes is Phase 2
Spec drift	Partial	nightly-spec-drift.yml and schema:drift exist; the vendored snapshot is at the sent date and spec-refresh.yml re-vendors it
Public API	Met	etc/esi.ts.api.md committed, API Surface Check and API SemVer Gate in CI
Type safety	Partial	strict and noUncheckedIndexedAccess on; exactOptionalPropertyTypes on (11.0); isolatedDeclarations checked over the pipeline, ports, generated code, client, auth and entry points (typecheck:isolated), not the Zod schemas or endpoint maps, whose types are inferred by design (ROADMAP Phase 3); tsd type tests exist
Tests	Partial	Unit, BDD, contract replay, fuzz, faults and consumer tiers all run; mutation floors below the plan's 90/80
Security	Partial	Provenance on publish, CodeQL, Scorecard, zizmor, SHA-pinned actions; publishing still uses NPM_TOKEN, not trusted publishing; pino and zod are runtime deps
Package health	Partial	publint, attw, size budgets and the consumer matrix run; engines.node is >=18; no sideEffects field; no Bun, Deno or browser matrix
Docs	Partial	README and guide examples are type-checked; the VitePress site in docs-site/ is not deployed (esi-06b)
Release	Partial	release-please, commitlint and the SBOM script exist; the release pipeline has open P1 defects (esi-l38.5)
Live health	Met	nightly-live-health.yml refreshes a maintained SSO token and calls /status and /characters/{id}/online through the real client every night, filing one issue while it fails; the three ESI_HEALTH_* secrets are the maintainer's to add, and the run says "not configured" until they exist

Transport rules from the plan

Rule	State
Send X-Compatibility-Date on every request	Done (src/core/requestPipeline/headers.ts)
Send X-Tenant	Missing: no request sets it
Descriptive User-Agent, refuse to build without one	Partial: X-User-Agent carries clientId, which defaults to esi-client and is never required
ETag, If-None-Match, 304 as a hit	Done (spec-aware TTL cache)
X-Pages pagination	Done (offset and cursor handlers); open defect esi-l38.1
Error-limit tracking	Done (src/core/rateLimiter/RateLimiter.ts)
Surface Warning headers	Done as warn logs; not yet a typed event