# Engine dynamic-import reconciliation design

**Date:** 2026-07-28

## Goal

Reconcile the overlapping engine dynamic-import changes from:

- `claude/hungry-edison-8bb1cd` at release commits `48ada48f` and `248bfe55`
- `claude/elegant-gates-e5275e` at `ef4cf7a8`

onto a fresh branch from current `origin/master`, without merging or cherry-picking either lineage wholesale and without adding a release/version bump.

## Established state

At investigation time:

- `origin/master` was `6136e139972a5449630b4f47f5ed7b4cbe5b811b`, version `0.42.67.0`.
- Upstream PR #3511 was still open, so trunk did not contain its two `chronicle/ontology.ts` hoists.
- Neither source branch was an ancestor of trunk.
- Trunk contained 17 dynamic imports in the three engine-path files:
  - 13 safe-hoist candidates: two ontology imports, nine engine helper/audit imports, and two migration imports.
  - Four `ai/gateway.ts` imports, all inside `try/catch` fallback paths.
- `git log -G` showed the separate ontology, helper, migration, and gateway histories. `git log -S` is not suitable for this dynamic-to-static replacement because the relevant token can remain present while its context changes.
- The guard from `ef4cf7a8` passed against that commit but failed against trunk. It also knew about only two gateway opt-outs because two `_upsertChunksOnce` gateway lookups landed later in trunk.

## Selected approach

Reconstruct the intended current state directly on fresh `origin/master`.

Do not merge or cherry-pick either old lineage. Selectively reproduce the desired source changes, adapt the guard to the current four gateway call sites, and write current-state documentation. This avoids importing stale release metadata, stale TODO claims, and unrelated lineage changes.

## Source changes

### Safe static imports

Hoist all 13 safe candidates:

- `src/core/pglite-engine.ts`
  - `valueHash`, `normalizeDimension`, `isNovelDimension` from `chronicle/ontology.ts`
  - `isRetryableConnError` through the existing `retry.ts` import
  - `resolveRecencyDecayMap`, `DEFAULT_FALLBACK` from `search/recency-decay.ts`
- `src/core/postgres-engine.ts`
  - the same ontology, retry, and recency helpers
  - `isConnectionEndedError` from `retry-matcher.ts`
  - `logDbDisconnect` from `audit/db-disconnect-audit.ts`
  - `logPoolRecovery` from `audit/pool-recovery-audit.ts`
- `src/core/migrate.ts`
  - `isStatementTimeoutError`, `isRetryableConnError` from `retry-matcher.ts`
  - `repairTimelineDedupIndex` from `timeline-dedup-repair.ts`

The implementation must keep the two engines in parity where the behavior is shared. Comments should describe current invariants, not repeat an unproven causal claim that these hoists fix the Windows test-runner crash.

### Deliberately lazy gateway imports

Keep all four `await import('./ai/gateway.ts')` call sites lazy:

- PGLite `initSchema`
- PGLite `_upsertChunksOnce`
- Postgres `initSchema`
- Postgres `_upsertChunksOnce`

Each line receives the explicit `engine-dynamic-import-ok` marker and a concise nearby rationale.

The rationale has two parts:

1. The gateway's static closure includes the AI SDK, provider packages, and validation/config machinery, so eager loading would tax engine startup paths that do not otherwise need it.
2. More importantly, each lookup is inside a `try/catch` that preserves a soft fallback (compiled defaults or the brain's stored embedding-model config). Hoisting the module would evaluate it before that catch can run and could convert a recoverable configuration/import failure into a module-load-time hard failure.

The guard must not allow unmarked gateway imports or a broad file-level exemption.

## Guard and wiring

Add `scripts/check-engine-dynamic-import.sh`, adapted from `ef4cf7a8`, with these properties:

- Default scan set:
  - `src/core/pglite-engine.ts`
  - `src/core/postgres-engine.ts`
  - `src/core/migrate.ts`
- Normalize trailing CR before matching so CRLF checkouts cannot bypass the check.
- Ignore comment-only lines.
- Ignore only lines carrying `engine-dynamic-import-ok`.
- Report every unmarked `await import(` with file and line.
- Explain that contributors should prefer a static import and must justify a real opt-out.
- Avoid asserting that every dynamic import deterministically crashes Windows; the measured evidence supports treating the pattern as an engine-path hardening invariant, while box-level commit exhaustion remained a confound in prior runs.

Wire it into:

- `package.json` as `check:engine-dynamic-import`
- `package.json` `check:all`
- `scripts/run-verify-parallel.sh`

Follow trunk's current rule that package scripts invoke repository shell scripts through `bash`.

## Regression coverage

Add an automated test for the guard. It must cover:

- A real dynamic import produces exit 1 and is reported.
- A line carrying `engine-dynamic-import-ok` is allowed.
- Line comments and block-comment lines do not produce findings.
- The same violation is caught with CRLF input.
- The default repository scan passes after the source reconciliation.

Use a temporary fixture rather than mutating tracked source files. Keep assertions path-portable.

The pre-fix red demonstration is the exact guard from `ef4cf7a8` run against current trunk: it exits 1 and reports the existing unmarked imports. The post-fix guard and test must pass.

## Documentation policy

Preserve current behavior, not either old release narrative:

- Do not modify `VERSION` or add a release `CHANGELOG.md` entry.
- Do not copy old version headings or completed release TODO blocks.
- Do not retain the old TODO claiming that extracting gateway accessors is necessarily the fix; the lazy imports are deliberately protected by their local soft-failure boundaries.
- Add the cross-cutting no-unmarked-dynamic-import invariant to `CLAUDE.md`.
- Update the current-state entries for `src/core/pglite-engine.ts`, `src/core/postgres-engine.ts`, and `src/core/migrate.ts` in `docs/architecture/KEY_FILES.md` where needed.
- Regenerate `llms.txt` and `llms-full.txt` after the documentation edits.
- Add a TODO only if implementation uncovers a real unresolved action.

Public documentation must use generic language and must not overstate the historical Windows crash causality.

## Verification

Capture full output to files before inspecting summaries. Run, at minimum:

1. The guard regression test.
2. `bash scripts/check-engine-dynamic-import.sh`.
3. Focused tests that exercise the touched engine, migration, retry, audit, and recency modules.
4. `bun run typecheck`.
5. `bun run verify`.
6. `bun run build:llms` followed by `bun test test/build-llms.test.ts`.
7. `git diff --check` and a final clean-status/diff review.

If platform contention or existing Windows suite defects block a broad test, report the exact command, exit code, and ownership classification rather than declaring success from a partial run.

## Git and publication boundary

- Work on `claude/kind-meitner-330c90`, reset locally to the exact investigated `origin/master` base.
- Preserve the previous worktree tip under `claude/kind-meitner-330c90-pre-reconcile`.
- Keep implementation and verification commits local.
- Do not push, create a PR, comment upstream, or otherwise publish without explicit user approval after the local result is complete.