dual-edition-module-migration

# Dual Edition Module Migration

## When to apply

- A module must exist in both open-source and enterprise editions
- The user mentions `src/opensource`, `enterprise/`, Vite overlay, or edition-specific behavior
- A shared module needs to stay under `src/opensource/...`, but enterprise behavior must override it
- Old `src/variant/...` or `src/opensource/variant/...` facades need to be removed
- A migration must preserve the `src/opensource` import boundary

## Core invariants

### 1. `src/opensource` is the shared source of truth

- Code under `src/opensource/` is the default implementation
- `src/opensource/` must not import commercial code
- If open-source needs a dependency, migrate that dependency too or degrade the feature
- If a file under `src/opensource/` or `enterprise/src/opensource/` imports a module outside the `opensource` tree, move that dependency into the current `opensource` closure instead of keeping a shim
- Do not pull private infrastructure such as `keewoodClient` or `teamshareClient` into `src/opensource`

### 2. `enterprise/` is an overlay, not a second app

- Keep the same relative path under `enterprise/` as the shared file under `src/`
- Runtime resolution priority is `enterprise/**` first, then `src/**`
- Enterprise files should be as thin as possible
- Prefer a re-export shim in `enterprise/...` when it preserves behavior without duplication
- Do not use re-export shims when the stable caller path is already `@/opensource/...` and the shim would import from outside the `opensource` tree
- If a dependency chain is truly enterprise-only, keep the whole chain in `enterprise/...`
- Do not leave enterprise-only stores or services in `src` just because enterprise files import them
- Do not create an enterprise overlay file that re-imports the same logical `@/opensource/...` path it overrides
- If the stable caller path is `@/opensource/...`, the enterprise implementation must live under `enterprise/src/opensource/...`
- Do not move a dual-edition module into `enterprise/components/...` or another non-mirrored path unless the user explicitly wants a commercial-only module

### 3. Open-source callers should import the real shared path

- Files under `src/opensource/` should import `@/opensource/...` directly
- Do not keep `@/variant/...` in open-source code
- If enterprise needs different behavior for that shared path, add an overlay file under `enterprise/src/opensource/...`

### 4. Choose extension point by artifact type

Use this rule first:

| Artifact                                                       | Preferred mechanism                                                                                                                                               |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| React view/component rendered through factory                  | `ComponentFactory` default in `src/opensource` plus enterprise or premium override where still needed                                                             |
| Hook / service / preload helper imported from open-source code | Direct `@/opensource/...` import plus `enterprise/src/opensource/...` overlay when behavior differs                                                               |
| Shared implementation used by both editions                    | Move to `src/opensource/...`; if callers already target `@/opensource/...`, migrate the real code and delete the old file instead of leaving a compatibility shim |
| Legacy `src/components/...` module becoming dual-edition       | Migrate to `src/opensource/...` plus mirrored `enterprise/src/opensource/...`; then switch callers to `@/opensource/...`                                          |
| Runtime-only indirection                                       | `src/runtime/<domain>/` only when direct imports and overlay cannot express the binding                                                                           |

## Architecture patterns

### Pattern A: Shared baseline plus enterprise overlay

Use this for hooks, services, helpers, and other non-visual modules.

1. Keep the default implementation in `src/opensource/...`
2. Update callers to import that `@/opensource/...` path directly
3. If enterprise behavior differs, add the same path under `enterprise/src/opensource/...`
4. Let Vite resolve the enterprise file first at runtime
5. Remove the old `variant` facade after callers are switched

Minimal example:

```ts
// src/opensource/components/business/RecordingSummary/hooks/useCancelRecord.tsx
export default function useCancelRecord() {
	// shared implementation
}
```

```ts
// enterprise/src/opensource/components/business/RecordingSummary/hooks/useCancelRecord.tsx
export default function useCancelRecord() {
	// enterprise implementation
}
```

```ts
import useCancelRecord from "@/opensource/components/business/RecordingSummary/hooks/useCancelRecord"
```

### Pattern B: Component override

Use this when a UI component needs edition-specific rendering.

1. Keep the default implementation in `src/opensource/...`
2. Register it in `src/opensource/components/ComponentRender/config/defaultComponents.tsx`
3. Keep commercial-only UI in `src/...` only when it owns real delta
4. Register premium overrides only where the factory still needs explicit component replacement
5. For helper imports such as preload code, prefer direct `@/opensource/...` imports plus enterprise overlay

This keeps render-time switching and non-render imports aligned.

### Pattern B.5: Shared facade plus enterprise child override

Use this when the only edition difference is a small injected block inside a much larger shared page or layout.

Rules:

1. Extract the changing block into the smallest possible shared child component or hook under `src/opensource/...`
2. Keep the shared