@luckystack/devkit 0.1.0

package/docs/loader-pipeline.md

@@ -0,0 +1,324 @@
+# Loader Pipeline (`initializeAll`, `initializeApis`, `initializeSyncs`, `initializeFunctions`, upsert/remove)
+
+> Dev-only. `@luckystack/devkit` is published as a `devDependency`. Nothing in this document runs in a production bundle — the prod runtime maps loader in `@luckystack/server` reads from in-memory `devApis`/`devSyncs`/`devFunctions` only when `NODE_ENV !== 'production'`, and from the on-disk generated maps otherwise.
+
+The loader pipeline is the dev-time mirror of the production route registry. It walks the configured `srcDir` (from `getProjectConfig().paths`) and each `serverFunctionDirs` root (legacy singular `serverFunctionsDir` still honored when set), evaluates each route file via dynamic `import()`, and populates three in-memory maps:
+
+| Map | Shape | Mirror of |
+|---|---|---|
+| `devApis` | `Record<string, { main, auth, rateLimit, httpMethod, schema, inputType, inputTypeFilePath }>` keyed by `api/<page-location\|'system'>/<name>/v<n>` | every `_api/<name>_v<n>.ts` |
+| `devSyncs` | `Record<string, { main, auth, inputType, inputTypeFilePath } \| Function>` keyed by `sync/<page-location>/<name>/v<n>_<server\|client>` | every `_sync/<name>_(server\|client)_v<n>.ts` |
+| `devFunctions` | nested `Record<string, unknown>` mirror of the on-disk tree, leaves are merged named + default exports per file | every `<root>/**/*.ts` under each `serverFunctionDirs` root (legacy singular `serverFunctionsDir` still honored when set) |
+
+All three maps are mutated in place. Consumers (the dev server boot path, the prod runtime maps loader's dev branch) hold a stable reference to the exported objects and read them on every request.
+
+---
+
+## `initializeAll()`
+
+```typescript
+export const initializeAll = async () => {
+  assertValidRouteNaming({
+    srcDir: getSrcDir(),
+    context: 'starting dev server (npm run server)',
+  });
+
+  await Promise.all([initializeApis(), initializeSyncs(), initializeFunctions()]);
+};
+```
+
+Order matters:
+
+1. **Route naming validation first.** `assertValidRouteNaming` walks the file tree once and throws if any `_api/` or `_sync/` file doesn't match the version regex (e.g. `_v1.ts`, `_server_v2.ts`). Aborting before any file evaluates means a typo can't produce half-loaded state.
+2. **Three initializers in parallel** via `Promise.all`. They share the TypeScript program cache (see `ts-program-cache.md`) — running them sequentially would not be faster, since the cache only gets built on first access from inside the extractors.
+
+After `initializeAll()` returns, the dev server should call `setupWatchers()` exactly once (see `hot-reload.md`) so subsequent file changes incrementally mutate the same maps.
+
+---
+
+## `initializeApis()`
+
+```typescript
+export const initializeApis = async () => {
+  for (const key of Object.keys(devApis)) delete devApis[key];
+  //? No invalidateProgramCache() here — cachedProgram starts as null on
+  //? module-load (tsProgram.ts), so the first getServerProgram() call
+  //? builds it from scratch. With initializeApis + initializeSyncs running
+  //? in parallel via Promise.all, invalidating here forced a redundant
+  //? double-build (~3-4s waste). Hot-reload paths (upsertApiFromFile,
+  //? removeApiFromFile etc.) DO invalidate — that's where it's needed.
+  clearRuntimeTypeResolverCache();
+  const srcFolder = fs.readdirSync(getSrcDir());
+
+  for (const file of srcFolder) {
+    await scanApiFolder(file);
+  }
+};
+```
+
+Flow:
+
+1. Empty `devApis` by deleting every key. The exported reference stays stable.
+2. **Deliberately skip `invalidateProgramCache()`.** Module-load init in `tsProgram.ts` starts with `cachedProgram = null`, so the first `getServerProgram()` call from inside the extractors will build it from scratch. Calling `invalidateProgramCache()` here used to force a redundant ~3-4s double-build because `initializeApis` and `initializeSyncs` run concurrently and would each invalidate after the other had warmed the cache. The hot-reload upsert/remove paths DO invalidate, because there the cache really is stale.
+3. Clear the runtime type resolver cache (`clearRuntimeTypeResolverCache()`) so any string-based identifier resolution starts fresh.
+4. Recurse the project's `srcDir` via `scanApiFolder`. The walker descends through every directory looking for one whose lowercase name ends in `api` (the resolved `apiMarker` from `getRoutingRules()` — default `_api`).
+5. For each `<name>_v<n>.ts` inside that folder, parse the version with `apiVersionRegex`, import the file, extract `main` / `auth` / `rateLimit` / `httpMethod` / `schema`, derive the inline `inputType` text via `getInputTypeFromFile()`, and store the entry under `api/<pageLocation>/<name>/v<n>`. `pageLocation` is `''` when the API lives at `src/_api/` and is mapped to `'system'` by `mapApiPageLocation()`; otherwise it's the slash-joined path segments above the marker.
+
+`auth` is normalized at load time:
+
+```typescript
+auth: {
+  login: auth.login || false,
+  additional: auth.additional || [],
+}
+```
+
+Missing `main` (or non-function `main`) silently skips the file — the entry is removed and the route key is absent from `devApis`. Filename parse failures log in red to `[loader][api]` and continue.
+
+---
+
+## `initializeSyncs()`
+
+Same shape as `initializeApis()`, keyed on folders whose lowercase name ends in `sync` (the resolved `syncMarker`). Each `_sync/<name>_(server|client)_v<n>.ts` is matched by `syncVersionRegex`, yielding the `kind` (`server` or `client`) and version. The route base key is:
+
+- `sync/<pageLocation>/<syncName>/v<n>` (when `pageLocation` is non-empty)
+- `sync/<syncName>/v<n>` (root-level sync)
+
+Final entry key appends `_server` or `_client`. Storage differs by kind:
+
+- **Server kind** stores a record:
+  ```typescript
+  devSyncs[`${routeBaseKey}_server`] = {
+    main: resolvedSyncModule.main,
+    auth: resolvedSyncModule.auth || {},
+    inputType,             // derived via getSyncClientDataType()
+    inputTypeFilePath: filePath,
+  };
+  ```
+- **Client kind** stores the bare `main` callback (the request dispatcher calls it directly with `{ clientOutput, serverOutput }`):
+  ```typescript
+  devSyncs[`${routeBaseKey}_client`] = resolvedSyncModule.main;
+  ```
+
+Like `initializeApis()`, the boot path skips `invalidateProgramCache()` and only clears the runtime type resolver cache.
+
+---
+
+## `initializeFunctions()`
+
+```typescript
+export const initializeFunctions = async () => {
+  for (const key of Object.keys(devFunctions)) delete devFunctions[key];
+
+  for (const serverFunctionsDir of getServerFunctionDirs()) {
+    if (fs.existsSync(serverFunctionsDir)) {
+      await scanFunctionsFolder(serverFunctionsDir);
+    }
+  }
+};
+```
+
+> `getServerFunctionDirs()` returns the array from `projectConfig.paths.serverFunctionDirs`. The legacy singular `serverFunctionsDir` form is still honored — when set it is merged into the array at config load.
+
+Walks every configured root recursively. Per `.ts` file:
+
+1. Import via `importFile()` (see below).
+2. Run `resolveFunctionModule(module, fileName)`:
+   - Module with only named exports -> the named exports object (default merged in only if it's the sole export).
+   - Module with no named exports but a default export -> `{ [fileName]: defaultExport }`. This lets `import functionName from './function'` show up at `devFunctions[folder]?.[functionName]?.[functionName]`.
+   - Module that is itself a function -> returned as-is so it can be merged.
+3. Walk into the `devFunctions` tree along the `basePath` segments, creating nested `Record<string, unknown>` subtrees on demand. Each level is structurally a record but typed as `unknown` after one level of indexing — `resolveFunctionModule` re-narrows before descent.
+4. If a previous scan left a node at the same leaf path, `Object.assign(resolvedFunctionModule, existingAtFileName)` merges them. This is what lets two files in the same folder contribute to the same logical bag of helpers.
+
+Failure modes are logged with `[loader][function]` and the file is skipped.
+
+---
+
+## Per-file import strategy
+
+```typescript
+const importFile = async (absolutePath: string) => {
+  const url = `${pathToFileURL(absolutePath).href}?v=${Date.now()}`;
+  return import(url);
+};
+```
+
+- `pathToFileURL` converts Windows-style paths and special characters into a proper `file://` URL.
+- The `?v=<timestamp>` query is a cachebust that forces the ESM loader to return a fresh evaluation each call. Without it, `import()` is memoized and a saved file would not re-evaluate.
+- Switching from CommonJS `require()` to dynamic `import()` also stops module evaluation from blocking the event loop. With CJS, evaluating a single ~50 ms file held the Socket.io thread; with ESM the evaluation yields and Socket.io stays responsive during a save burst.
+
+The `tryCatch` wrapper from `@luckystack/core` captures evaluation errors:
+
+```typescript
+const [err, module] = await tryCatch(async () => importFile(routeMeta.absolutePath));
+if (err) {
+  console.log(`[loader][api] failed to import ${routeMeta.routeKey} from ${routeMeta.absolutePath}:`, err, 'red');
+  return;
+}
+```
+
+A failed import leaves the existing `devApis` / `devSyncs` entry untouched (no partial replacement).
+
+---
+
+## Route key shape
+
+API key:
+
+```
+api/<pageLocation|'system'>/<apiName>/v<n>
+```
+
+`pageLocation` is the slash-joined path segments BEFORE the `_api` marker. `system` is used when the API sits at the project root (e.g. `src/_api/healthCheck_v1.ts` -> `api/system/healthCheck/v1`).
+
+Sync key:
+
+```
+sync/<pageLocation>/<syncName>/v<n>_<server|client>
+```
+
+If the sync lives at the project root (no page above the `_sync` marker), the key drops the page segment: `sync/<syncName>/v<n>_<server|client>`.
+
+These shapes match the route keys produced by the production runtime maps loader in `@luckystack/server`. Switching between dev and prod is a matter of which map the request dispatcher reads from.
+
+---
+
+## Filename validation regexes
+
+```typescript
+export const API_VERSION_TOKEN_REGEX = /_v(\d+)$/;
+export const SYNC_VERSION_TOKEN_REGEX = /_(server|client)_v(\d+)$/;
+```
+
+Re-exported from `routeConventions.ts` for consumers (e.g. the docs UI) that need to parse filenames.
+
+`assertValidRouteNaming({ srcDir, context })` walks the tree and throws an `Error` whose message includes:
+
+- The `context` string passed in (e.g. `'starting dev server (npm run server)'` or `'generating API/sync type maps'`).
+- Every offending file path with the expected pattern.
+
+`assertNoDuplicateNormalizedRouteKeys({ srcDir, context })` is called only by the type-map generator. It catches the case where two differently-cased files (`getSettings_v1.ts` vs `getsettings_v1.ts`) normalize to the same route key on case-insensitive filesystems.
+
+---
+
+## Routing rules registry
+
+```typescript
+export interface RoutingRules {
+  apiMarker: string;       // default '_api'
+  syncMarker: string;      // default '_sync'
+  apiVersionRegex: RegExp; // default API_VERSION_TOKEN_REGEX
+  syncVersionRegex: RegExp;// default SYNC_VERSION_TOKEN_REGEX
+}
+
+export const registerRoutingRules = (rules: Partial<RoutingRules>): void;
+export const getRoutingRules = (): RoutingRules;
+```
+
+Defaults are exported from `routingRules.ts` and consumed by every walker (`scanApiFolder`, `scanSyncFolder`, `resolveApiRouteMetaFromPath`, `resolveSyncRouteMetaFromPath`, the watcher) plus the filename predicates:
+
+```typescript
+export const apiMarkerSegment = (): string;
+export const syncMarkerSegment = (): string;
+export const isApiFileName = (name: string): boolean;
+export const isSyncFileName = (name: string): boolean;
+export const isSyncServerFileName = (name: string): boolean;
+export const isSyncClientFileName = (name: string): boolean;
+```
+
+A consumer registering custom markers (`{ apiMarker: 'api', syncMarker: 'live' }`) sees them flow through to the watcher segment computation in `setupWatchers()` (see `hot-reload.md`) and the loader scans, so non-default layouts work without forking the package.
+
+---
+
+## Hot-reload single-file paths
+
+All four hot-reload functions follow the same shape:
+
+```typescript
+export const upsertApiFromFile = async (filePath: string): Promise<void> => {
+  const routeMeta = resolveApiRouteMetaFromPath(filePath);
+  if (!routeMeta) {
+    // log + return — filename rejection
+    return;
+  }
+
+  invalidateProgramCache();
+  clearRuntimeTypeResolverCache();
+
+  const [err, module] = await tryCatch(async () => importFile(routeMeta.absolutePath));
+  if (err) { /* log + return */ return; }
+
+  const resolvedModule = module?.default ? { ...module.default, ...module } : module;
+  const { auth = {}, main, rateLimit, httpMethod, schema } = resolvedModule;
+
+  if (!main || typeof main !== 'function') {
+    delete devApis[routeMeta.routeKey];
+    return;
+  }
+
+  const inputType = getInputTypeFromFile(routeMeta.absolutePath);
+
+  devApis[routeMeta.routeKey] = { main, auth: { ... }, rateLimit, httpMethod, schema, inputType, inputTypeFilePath: routeMeta.absolutePath };
+};
+```
+
+Key differences from the boot initializers:
+
+| Step | Boot (`initializeApis`/`initializeSyncs`) | Hot reload (`upsert*`/`remove*`) |
+|---|---|---|
+| `invalidateProgramCache()` | Skipped — cache is null on module load | Always called — file content changed |
+| `clearRuntimeTypeResolverCache()` | Called | Called |
+| Resolve filename via marker walk | Recursive tree scan | `resolveApiRouteMetaFromPath` / `resolveSyncRouteMetaFromPath` on the single path |
+| Missing `main` | Silently skip | Explicit `delete devApis[key]` to keep table in sync with file state |
+
+`removeApiFromFile` / `removeSyncFromFile` follow the same skeleton minus the import: they invalidate caches and `delete` the matching entry. If the file path doesn't normalize to a route key (wrong marker segment, wrong extension), the call is a no-op — the watcher fan-out from `enqueueAffectedRoutesFromDependency` may enqueue paths that aren't routes, and silently dropping them is the right behavior.
+
+Sync kind handling in `upsertSyncFromFile`:
+
+- `kind === 'server'`: store `{ main, auth, inputType, inputTypeFilePath }` if `main` is a function, otherwise delete the entry.
+- `kind === 'client'`: store the bare `main` callback if it's a function, otherwise delete the entry.
+
+---
+
+## Consumer contract
+
+Dev server boot:
+
+```typescript
+import { initializeAll, setupWatchers } from '@luckystack/devkit';
+
+await initializeAll();
+setupWatchers();
+// then start HTTP server / Socket.io
+```
+
+Production runtime maps loader (`packages/server/src/runtimeMapsLoader.ts`):
+
+```typescript
+if (process.env.NODE_ENV !== 'production') {
+  const devkit = await import('@luckystack/devkit');
+  return {
+    apis: devkit.devApis,
+    syncs: devkit.devSyncs,
+    functions: devkit.devFunctions,
+  };
+}
+
+// prod: read from generated maps on disk
+```
+
+The dev loader is never invoked under `NODE_ENV=production`; the generated `apiTypes.generated.ts` / `apiInputSchemas.generated.ts` (see `type-map-generation.md`) drive the prod path instead.
+
+---
+
+## Failure modes (summary)
+
+| Symptom | Cause | What happens |
+|---|---|---|
+| `[loader][api] invalid filename: ...` | filename doesn't match `apiVersionRegex` | file skipped, route key absent from `devApis` |
+| `[loader][sync] invalid filename: ...` | filename doesn't match `syncVersionRegex` | file skipped, route key absent from `devSyncs` |
+| `[loader][api] failed to import ...` | runtime error during `import()` | previous entry left untouched, error logged |
+| `[loader][function] failed to import ...` | runtime error in a server-functions file | previous nested node left untouched |
+| `assertValidRouteNaming` throw at startup | any `_api/`/`_sync/` file fails the regex | dev server boot aborts before any file evaluates |
+| Missing `main` after a save | consumer removed the export | `delete devApis[key]` (or `devSyncs[key]`) keeps the table consistent with disk state |
+| Hot reload picks up a typo, then the next save fixes it | `upsertApiFromFile` runs twice | second run replaces the entry; no orphans |

package/docs/runtime-type-resolver.md

@@ -0,0 +1,258 @@
+# Runtime Type Resolver (`runtimeTypeResolver.ts`)
+
+> Dev-only. Lives in `@luckystack/devkit` and is consumed exclusively by `@luckystack/core/src/runtimeTypeValidation.ts` via a lazy `await import('@luckystack/devkit')` that fires only when `NODE_ENV !== 'production'`. Production servers never load this module — runtime input validation in prod uses the pre-generated Zod schemas in `apiInputSchemas.generated.ts`, not the deep resolver.
+
+The resolver bridges two worlds:
+
+1. **What the loader stored.** When the dev loader (`loader.ts`) imports an API or sync file, it calls `getInputTypeFromFile(filePath)` (a public extractor) and stashes the result on `devApis[routeKey].inputType` along with `inputTypeFilePath`. The stored text is what the extractor produced at import time — usually a fully-expanded inline form, occasionally a named alias that the extractor could not expand standalone.
+2. **What the runtime validator needs.** Each incoming request is type-checked against the stored `inputType`. If the stored text still contains identifiers (e.g. `UserInput`, `Partial<RegisterPayload>`, `Pick<Prisma.User, 'id' | 'name'>`), the validator cannot match payload keys to type members until those identifiers are recursively expanded into a structural shape.
+
+The resolver takes the stored text + the original file path, follows imports across the project via the cached `ts.Program`, applies a handful of TypeScript utility types (`Partial`, `Required`, `Pick`, `Omit`, `Record`, `Array`), and returns a self-contained inline type string. The result is cached so a hot request path does not redo work.
+
+---
+
+## Module surface
+
+```typescript
+type ResolveResult =
+  | { status: 'success'; typeText: string }
+  | { status: 'error'; message: string };
+
+export const resolveRuntimeTypeText = ({
+  typeText,
+  filePath,
+}: {
+  typeText: string;
+  filePath?: string;
+}): ResolveResult;
+
+export const clearRuntimeTypeResolverCache = (): void;
+export const isUnresolvedTypeMarker = (value: string): boolean;
+export const getUnresolvedTypeMessage = (value: string): string;
+```
+
+Internal-only:
+
+- `resolveExpression(typeText, filePath, depth, state)` — recursive worker.
+- `resolveIdentifier(identifier, filePath)` — TypeChecker-backed identifier lookup, follows local declarations + import statements.
+- `applyUtilityType({ utilityName, utilityArgs, filePath, depth, state })` — `Partial`, `Required`, `Pick`, `Omit`, `Record`.
+- `parseObjectFields(typeText)` / `serializeObjectFields({ fields, indexSignatures })` — round-trip an object literal type through a typed AST.
+- `splitTopLevel(value, '|' | '&' | ',')` — depth-aware splitter (respects `(`, `{`, `[`, `<`).
+- `parseLiteralUnionKeys(value)` — extract `'a' | 'b'` into `['a', 'b']` for `Pick` / `Omit` / `Record` key lists.
+- Constants: `MAX_DEPTH = 20`, `PRIMITIVE_TYPES`, `SKIP_EXPANSION`, `unresolvedPrefix = '__RUNTIME_UNRESOLVED__::'`.
+- Types: `ObjectField`, `ObjectIndexSignature`, `ResolveState`.
+
+---
+
+## `resolveRuntimeTypeText(...)` flow
+
+```typescript
+export const resolveRuntimeTypeText = ({ typeText, filePath }) => {
+  const cleanType = typeText.trim();
+  if (!cleanType || !filePath) {
+    return { status: 'success', typeText: cleanType };
+  }
+
+  const cacheKey = `${filePath}::${cleanType}`;
+  const cached = resolvedTypeCache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+
+  const resolved = resolveExpression(cleanType, filePath, 0, { stack: new Set() });
+  const result: ResolveResult = isUnresolvedTypeMarker(resolved)
+    ? { status: 'error', message: getUnresolvedTypeMessage(resolved) }
+    : { status: 'success', typeText: resolved };
+
+  resolvedTypeCache.set(cacheKey, result);
+  return result;
+};
+```
+
+1. **No-op short-circuit.** Empty input or missing `filePath` — return as-is. The validator passes an empty string for routes with `{ [key: string]: never }` "no input" syntax that the extractor reduced to nothing; callers expect a success in that case.
+2. **Cache hit.** `resolvedTypeCache: Map<string, ResolveResult>` keyed by `${filePath}::${typeText}`. The path is part of the key because `import { Foo } from './a'` and `import { Foo } from './b'` resolve to different `Foo`s.
+3. **Recursive resolve.** `resolveExpression(...)` walks the type expression text and returns either a fully expanded form or a string prefixed with `__RUNTIME_UNRESOLVED__::<reason>`.
+4. **Result shape.** Unresolved-marker prefix is mapped to `{ status: 'error', message }`; clean text is mapped to `{ status: 'success', typeText }`. Both branches are cached.
+
+---
+
+## `resolveExpression(...)` — the recursive worker
+
+The worker tracks two pieces of state:
+
+- `state.stack: Set<string>` — visited `(filePath, typeText)` pairs in the current resolution. Re-entering one returns `__RUNTIME_UNRESOLVED__::cyclic type reference <type>`.
+- `depth: number` — bumped on every recursion. When it exceeds `MAX_DEPTH = 20`, the worker returns `__RUNTIME_UNRESOLVED__::resolution depth exceeded for <type>`.
+
+The decision tree (in order):
+
+1. **Already unresolved.** If `type.startsWith('__RUNTIME_UNRESOLVED__::')`, return it as-is.
+2. **Parenthesized group.** `(T)` — strip outer parens, recurse, re-wrap on success.
+3. **Top-level union.** `splitTopLevel(type, '|')` returns more than one part — recurse on each, propagate the first unresolved marker found, otherwise join with ` | `.
+4. **Top-level intersection.** Same pattern with `&`.
+5. **Array suffix.** `T[]` — recurse on `T`, wrap result with `[]`.
+6. **Object literal.** Starts with `{` and ends with `}` — parse via `parseObjectFields`, recurse on every field type and every index signature key/value type, serialize back via `serializeObjectFields`.
+7. **Generic application.** Matches `^([A-Za-z_][A-Za-z0-9_]*)<(.+)>$` — split args at top-level commas, then:
+   - `Array<T>` (single arg) — same as `T[]`.
+   - `Partial`, `Required`, `Pick`, `Omit`, `Record` — delegate to `applyUtilityType`.
+   - Anything else — recurse on every type argument and re-render as `Name<arg1, arg2>`. The generic name is preserved verbatim; the validator can decide what to do with it.
+8. **Bare identifier.** Matches `^[A-Za-z_][A-Za-z0-9_]*$` — delegate to `resolveIdentifier`.
+9. **Everything else.** Returned as-is. This covers literal types (`'foo'`, `42`, `true`), already-primitive forms, and anything the regex set above does not classify.
+
+`splitTopLevel(value, splitter)` is the depth-aware splitter used by steps 3, 4, 7. It tracks `(`, `{`, `[`, `<` depth counters and only splits when all four are zero. This is what lets the worker safely split `Pick<User, 'a' | 'b'>` on commas without trimming the inner union.
+
+---
+
+## `resolveIdentifier(identifier, filePath)`
+
+```typescript
+const resolveIdentifier = (identifier: string, filePath: string): string => {
+  if (PRIMITIVE_TYPES.has(identifier.toLowerCase())) return identifier.toLowerCase();
+  if (SKIP_EXPANSION.has(identifier)) return identifier;
+
+  const program = getServerProgram();
+  const sourceFile = program.getSourceFile(filePath);
+  if (!sourceFile) return toUnresolved(`unresolved type ${identifier}`);
+
+  const checker = program.getTypeChecker();
+
+  for (const stmt of sourceFile.statements) {
+    // 1. Local interface / type alias / enum
+    if (
+      (ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt) || ts.isEnumDeclaration(stmt))
+      && stmt.name.text === identifier
+    ) {
+      const symbol = checker.getSymbolAtLocation(stmt.name);
+      if (symbol) {
+        return expandType(checker.getDeclaredTypeOfSymbol(symbol), checker);
+      }
+    }
+
+    // 2. Import declarations — follow aliases
+    if (ts.isImportDeclaration(stmt) && stmt.importClause) {
+      // namedBindings: { Foo, Bar } — match Foo or Bar
+      // defaultName:   Foo from '...'
+      // For matches: getSymbolAtLocation -> getAliasedSymbol -> getDeclaredTypeOfSymbol -> expandType
+    }
+  }
+
+  return toUnresolved(`unresolved type ${identifier}`);
+};
+```
+
+Two short-circuit lists:
+
+- `PRIMITIVE_TYPES` — `string`, `number`, `boolean`, `true`, `false`, `null`, `undefined`, `any`, `unknown`, `void`, `never`. Returned lowercased; covers the case where the extractor emitted `String` instead of `string`.
+- `SKIP_EXPANSION` — `Date`, `Promise`, `Array`, `Record`, `Partial`, `Required`, `Pick`, `Omit`, `Function`, `Map`, `Set`, `Buffer`, `Uint8Array`, `Object`, `WeakMap`, `WeakSet`. Structurally opaque; the validator treats them as "any value of this name".
+
+For everything else, the worker walks the file's top-level statements and looks for:
+
+1. A local `interface`, `type`, or `enum` declaration matching the identifier. If found, resolve the symbol, fetch its declared type, and recursively expand via `expandType` from `tsProgram.ts`.
+2. An import declaration whose named or default binding matches the identifier. If found, resolve the symbol, hop through `getAliasedSymbol` to reach the original declaration, then expand.
+
+If neither path produces a result, return the unresolved marker. The `try { ... } catch { ... }` wrapper around the body ensures any TypeChecker exception (rare, but possible on partially-typed sources) degrades to `__RUNTIME_UNRESOLVED__::unresolved type <identifier>` rather than crashing the request.
+
+`getServerProgram()` is shared with the type-map emitter. The resolver does not call `invalidateProgramCache()` — that's the loader's job on hot-reload. Resolver-side, `clearRuntimeTypeResolverCache()` is the matching reset.
+
+---
+
+## `applyUtilityType(...)`
+
+Handles five utility types. Each requires its target type to resolve to an object literal first; if the target resolves to a non-object form, the utility returns an unresolved marker.
+
+- **`Partial<T>`** — resolve `T` to an object, mark every field optional via `{ ...field, optional: true }`, preserve index signatures. Pure-additive utility, no field filtering.
+- **`Required<T>`** — symmetric; mark every field non-optional.
+- **`Pick<T, K>`** — resolve `T` to an object, parse `K` via `parseLiteralUnionKeys` into a string set, drop every field whose key is not in the set. Preserves index signatures.
+- **`Omit<T, K>`** — same as `Pick` with inverted membership test.
+- **`Record<K, V>`** — resolve `K` and `V` first. If `K` resolves to a literal-string union, materialize each literal as a concrete field with type `V` (renders as a closed object). Otherwise leave as `Record<K, V>` (treated as an opaque container at runtime).
+
+If any argument to a utility resolves to an unresolved marker, that marker is propagated unchanged.
+
+If an argument list does not have the expected arity (e.g. `Partial<A, B>`), the utility returns `__RUNTIME_UNRESOLVED__::unresolved utility <Name><...>`.
+
+---
+
+## Object literal round-trip
+
+`parseObjectFields(typeText)` and `serializeObjectFields({ fields, indexSignatures })` are the small AST-like helpers that let the worker rewrite an object body.
+
+`parseObjectFields(typeText)`:
+
+- Strips outer braces.
+- Walks the inner text character by character, tracking nesting depth for `{`, `[`, `(`, `<`.
+- Splits on `;` at depth 0.
+- For each segment, runs two regexes:
+  - Field regex: `^("']?[A-Za-z_][A-Za-z0-9_]*["']?)(\?)?\s*:\s*([\s\S]+)$` — captures key, optional flag, and type. Strips surrounding quotes from the key.
+  - Index signature regex: `^\[\s*([A-Za-z_][A-Za-z0-9_]*)\s*:\s*([^\]]+)\]\s*:\s*([\s\S]+)$` — captures the key name (e.g. `key`), the key type (e.g. `string`), and the value type.
+
+`serializeObjectFields`:
+
+- Renders each field as `${name}${optional ? '?' : ''}: ${type}` and each index signature as `[${keyName}: ${keyType}]: ${type}`.
+- Joins with `; ` and wraps with `{ ... }`. Returns `{ }` for an empty body (matches the extractor's "no input" form).
+
+---
+
+## Unresolved-marker protocol
+
+```typescript
+const unresolvedPrefix = '__RUNTIME_UNRESOLVED__::';
+
+const toUnresolved = (message: string): string => `${unresolvedPrefix}${message}`;
+export const isUnresolvedTypeMarker = (value: string): boolean => value.startsWith(unresolvedPrefix);
+export const getUnresolvedTypeMessage = (value: string): string => value.slice(unresolvedPrefix.length).trim();
+```
+
+The worker uses marker strings — not exceptions — to propagate failure. The reason:
+
+- One unresolved leaf inside a deep object should not abort the whole resolve; the validator wants to know which symbol failed.
+- Throw-based propagation forces every call site to wrap in try/catch; marker-based propagation lets the worker fall through identical code paths for success and failure (the worker only needs to check the result of each recursion).
+
+Callers (`@luckystack/core/src/runtimeTypeValidation.ts`) inspect `result.status`. On `'error'`, they log the `message` and degrade to a soft-pass for the request rather than refusing it — the deep resolver is informational, not a hard gate.
+
+---
+
+## Cache lifecycle
+
+```typescript
+const resolvedTypeCache = new Map<string, ResolveResult>();
+
+export const clearRuntimeTypeResolverCache = () => {
+  resolvedTypeCache.clear();
+};
+```
+
+The cache is keyed by `${filePath}::${typeText}`. It survives across requests but must be cleared whenever the underlying source files change.
+
+Invalidation points (all in `loader.ts`):
+
+- `initializeApis()` and `initializeSyncs()` — `clearRuntimeTypeResolverCache()` is called before re-scanning the source tree.
+- `upsertApiFromFile(filePath)`, `removeApiFromFile(filePath)`, `upsertSyncFromFile(filePath)`, `removeSyncFromFile(filePath)` — every per-file mutation clears the whole cache (not just the entry for the changed file). Selective invalidation would require tracking transitive imports; whole-cache flush is the simpler, safer choice and the resolver is not on the hot path of a steady-state running app.
+
+The cache must always be flushed alongside `invalidateProgramCache()` from `tsProgram.ts`. The two are paired in every invalidation site.
+
+---
+
+## Consumer contract
+
+- **Only `@luckystack/core` may import this module.** The lazy import lives in `@luckystack/core/src/runtimeTypeValidation.ts` and fires only when `process.env.NODE_ENV !== 'production'`. Consumers must not introduce any additional callers.
+- **Do not call from production code paths.** The resolver depends on `getServerProgram()`, which needs `tsconfig.server.json` and the consumer's source tree on disk. Production tarballs have neither.
+- **Treat results as ephemeral.** A cached success may turn into an error after the next hot reload (or vice versa). Always re-call `resolveRuntimeTypeText({ typeText, filePath })` rather than memoizing on the consumer side.
+- **Markers are strings, not exceptions.** Callers must check `status` before assuming success.
+
+---
+
+## Failure modes
+
+- **Cycle detected.** Returns `{ status: 'error', message: 'cyclic type reference <type>' }`. Happens for self-referential aliases that the type-map emitter could not flatten (e.g. recursive tree types whose Prisma client form was elided).
+- **Depth exceeded.** Returns `{ status: 'error', message: 'resolution depth exceeded for <type>' }`. `MAX_DEPTH = 20` is well above the depth limit in `tsProgram.ts` (`DEPTH_LIMIT = 12`), so this only fires when a type chains many import hops in addition to deep nesting.
+- **Identifier not found.** Returns `{ status: 'error', message: 'unresolved type <name>' }`. The file in question may not exist in the cached `ts.Program` (recently deleted, or outside the `tsconfig.server.json` `include` glob).
+- **Utility-arity mismatch.** Returns `{ status: 'error', message: 'unresolved utility <Name><...>' }`. The validator falls back to a soft-pass.
+- **Program rebuild during a resolve.** A concurrent hot-reload event could call `invalidateProgramCache()` mid-resolution. The next `getServerProgram()` call inside `resolveIdentifier` rebuilds; results from before and after the rebuild may differ. This is a tolerated race — the next steady-state request will see consistent state.
+
+---
+
+## Constants
+
+- `MAX_DEPTH = 20` — recursion cap for `resolveExpression`. Distinct from `DEPTH_LIMIT = 12` in `tsProgram.ts`; the resolver allows deeper recursion because each step crosses at most one file boundary.
+- `PRIMITIVE_TYPES` — 11 entries, lowercased on return.
+- `SKIP_EXPANSION` — 17 entries; passes through opaque containers and utility names that are themselves the subject of recursion elsewhere.
+- `unresolvedPrefix = '__RUNTIME_UNRESOLVED__::'` — sentinel string used by `toUnresolved` / `isUnresolvedTypeMarker` / `getUnresolvedTypeMessage`.