Migrating Deprecated @lumenflow/core Subpaths

@lumenflow/core exposes 141 subpath exports for fine-grained imports (e.g. import { ... } from '@lumenflow/core/wu-paths'). In v5.8.11 — the boundary-cleanup release — 23 of those subpaths were audited and found to have zero internal or external consumers.

They are marked deprecated: true in the tools/baselines/enforcement/core-subpath-exports-baseline.json ratchet and will be removed in a future major release. They still resolve in v5.8.11 — there is no runtime break — but new code should not import them.

Why this matters

Every subpath export is part of the public API surface. Subpaths that exist but no one imports are dead weight: they make the boundary larger than it needs to be, and they prevent us from refactoring internals freely. Removing unused subpaths shrinks the public contract to what is actually load-bearing.

Migration strategy

Pick the right replacement for your call site:

1. First preference — root barrel. If the symbol you need is re-exported from @lumenflow/core directly, import it from the root:

   // Before
   import { foo } from '@lumenflow/core/active-wu-detector';
   
   // After
   import { foo } from '@lumenflow/core';

2. Internal callers (inside this monorepo) — relative import. If you are inside packages/@lumenflow/core or another @lumenflow/* package, prefer a relative import that bypasses the public surface entirely:

   import { foo } from '../active-wu-detector';

3. External consumers. If the symbol is not on the root barrel and you are an external consumer, please open an issue — the symbol is on the deprecation list because we believed it was unused outside the kernel.

Deprecated subpaths

The 23 subpaths below are deprecated in v5.8.11. Each entry shows the canonical replacement.

Deprecated subpath	Replacement
@lumenflow/core/active-wu-detector	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/backlog-editor	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/constants/gate-constants	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/constants/linter-constants	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/delegation-escalation	@lumenflow/core/delegation (delegation barrel)
@lumenflow/core/delegation-recovery	@lumenflow/core/delegation (delegation barrel)
@lumenflow/core/dependency-guard	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/domain/orchestration.constants	@lumenflow/core/domain (domain barrel)
@lumenflow/core/generate-traceability	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/hardcoded-strings	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/lane-validator	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/logs-lib	@lumenflow/core/logging (logging barrel)
@lumenflow/core/orchestration-di	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/prompt-linter	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/retry-strategy	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/spawn-prompt-schema	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/stamp-status-validator	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/test-baseline	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/validators/claim-validation	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/worktree-scanner	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/wu-done-messages	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/wu-duplicate-id-detector	@lumenflow/core root barrel (or internal relative)
@lumenflow/core/wu-rename-projection	@lumenflow/core root barrel (or internal relative)

The authoritative list lives in tools/baselines/enforcement/core-subpath-exports-baseline.json — the deprecated: true flag is the source of truth.

Timeline

Release	Status
v5.8.11	Marked deprecated: true in baseline; still resolve.
Next major (TBD)	Removed. Imports will fail with MODULE_NOT_FOUND.

No firm removal date — removal happens once external consumer telemetry confirms the deprecated subpaths are no longer in use. Audit any pinned imports now and replace at your own pace.

Spotting the deprecation in TypeScript

A future tooling pass will add a JSDoc @deprecated tag on each deprecated subpath, so editors and the TypeScript compiler will surface a strikethrough and a quick-fix hint:

// Hover in VS Code / typecheck output:
// '@lumenflow/core/active-wu-detector' is deprecated — import from
// '@lumenflow/core' instead.
import { foo } from '@lumenflow/core/active-wu-detector';
//                  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Until the JSDoc pass lands, the canonical signal is the baseline file — treat any entry with deprecated: true as “do not add new imports”.

Why now

LumenFlow’s public surface should match what consumers actually load. Every subpath we declare is a contract we have to honour across major versions. Trimming 23 unused subpaths (about 16% of the surface) lets us refactor those modules freely without coordinating breaks with imaginary callers.

This is part of the kernel-boundary cleanup that also brought hex ports, branded path types, and the writes-to-main containment. See the v5.8.11 changelog entry for the full architectural narrative.

Related

• Narrative changelog