# Runbook: Per-Library Typecheck Cleanup

Owner: shared infra Last reviewed: 2026-05-28

The repo-root `npx tsc --noEmit` is green. Per-library `tsc --noEmit` loops in
some libraries still fail because of patterns the root typecheck doesn't surface
(composite-mode rootDir violations, package-export drift, stale generated/
outputs).

Audit #60 framed this as "3 catastrophic + 14 high libs". The catastrophic ones
(lakshmi, tara/analytics, veritas/auth + 24 libs sharing the rootDir+composite
pattern across veritas + aphrodite + asase) were fixed in:

- 87b3da7 (lakshmi composite + receipts createHash import)
- 8e2a4f1 (tara/analytics declaration + veritas/auth lib + DOM)
- 0bac56e (24-lib rootDir+composite sweep)

The remaining lib-level failures fall into two patterns. Each is tracked as
follow-up; the per-library owner takes the fix as part of their next PR.

## Pattern A: Package-export drift (TS2305)

When an upstream package's `exports` field narrows under
`moduleResolution: "bundler"`, a named import that worked under `"node"` mode
stops resolving. The fix is to import from the explicit subpath the upstream
lib's `exports` allows.

Example landed: `libs/veritas/search/src/client.ts` imported `ClientOptions`
from `@elastic/elasticsearch` (its main index), which under bundler mode
resolves to the ESM index — which doesn't re-export `ClientOptions`. Fixed by
importing from `@elastic/elasticsearch/lib/client`.

Search for these with:

```bash
find libs -maxdepth 3 -name 'tsconfig.json' | while read tc; do
  d=$(dirname "$tc")
  cd "$d"
  npx tsc --noEmit 2>&1 | grep -E 'TS2305' && echo "  in $d"
  cd -
done
```

## Pattern B: Real type errors in implementation

A handful of libs have actual type errors in their source — not config issues.
Examples:

- `libs/veritas/expansion`: 16 errors, mostly missing properties on
  `ExpansionPlanSchema` types that drifted from the prisma model.
- `libs/veritas/business`: 28 errors — `decimal` precision conflict between
  drizzle-orm and the prisma client types.
- `libs/veritas/storage`: 59 errors — `S3Client` constructor signature changed
  in `@aws-sdk/client-s3` v3 → v4.
- `libs/veritas/content-auth`: 124 errors — biggest single offender; the
  `@c2pa-rs/wasm` package's type defs target a newer toolchain than this lib's
  tsconfig `target: ES2020`.
- `libs/veritas/risk`: 54 errors — `zod` v3 → v4 schema-output type shape
  changes ripple through every risk-rule type.
- `libs/aphrodite/avatar-physics`: 15 errors — `@rapier/rapier3d` type defs.
- `libs/asase/sota`: 23 errors — drift after the recent ML pipeline refactor
  that landed `BatchInferenceRequest` shape changes.

Each is a per-owner fix. The shared-infra team won't take blanket PRs here
because the right fix needs the lib's domain knowledge (which schema field is
canonical, which sdk version is intended, etc.).

## How to verify your lib

```bash
cd libs/<domain>/<package>
npx tsc --noEmit
```

If this fails:

1. Check whether the failure is a TS6059 / TS6307 rootDir issue. If so, remove
   `rootDir` and `composite` from the lib's `tsconfig.json` — the @nx/js:tsc
   executor handles cross-package builds via the workspace path map.
2. Check whether the failure is a TS2305 named-import miss. If so, import from
   the explicit subpath the upstream lib's `exports` field allows.
3. Otherwise, fix the underlying type error.

The repo-root `npx tsc --noEmit` from the workspace root is the canonical
typecheck; lib-level checks are convenience-only and don't gate CI directly. The
CI typecheck job runs the root command, plus @nx/js:tsc builds per-project, both
of which are green as of 2026-05-28.