# Case Lifecycle Domain Boundary

## Purpose

This directory contains a narrow **case lifecycle decision boundary**, not a full domain model.

Its current purpose is to centralise **behaviour-preserving interpretation logic** that was previously embedded in UI-adjacent helpers, while keeping live behaviour unchanged during refactor.

This boundary should be treated as an incremental extraction seam for read-only lifecycle interpretation, not as a place to redesign lifecycle behaviour.

## Current ownership

### `getLifecycleStagesForCase(...)`

- thin wrapper around the existing stage/progress helper
- preserves existing output shape for current consumers
- does not define new lifecycle semantics

### `normalizeSpecialistProcess(...)`

- raw CRM field fallback only
- preserves current canonical and misspelled field fallback behaviour
- does not validate or reinterpret CRM values

### `mapAppealType(...)`

- current appeal-type-to-case-type mapping
- current alias handling
- current unknown input behaviour

### `mapSpecialistProcessStageType(...)`

- specialist-process stage override mapping
- preserves current placeholder-like CRM specialist process values
- preserves current override target keys and fallback behaviour

### `getStageCaseTypeKey(...)`

- current stage case-type resolution decision
- combines:
    - appeal type mapping
    - specialist-process stage override mapping
    - alias normalization
    - current fallback behaviour

### `getStagesForCaseTypeKey(...)`

- current stage catalogue lookup only
- preserves:
    - direct key lookup
    - string indirection resolution
    - fallback to `[]`
- does not own stage catalogue contents

## Stage catalogue ownership and lookup

Stage catalogue arrays still live in:

- `components/case/summary/utils/caseStagesByAppealType.js`

The domain boundary currently owns **lookup behaviour only**:

- direct key lookup
- string indirection resolution
- fallback to `[]`

`getStagesForCaseTypeKey(...)` must not be treated as stage catalogue ownership yet.

Lazy access in `getStagesForCaseTypeKey(...)` is intentional:

- it avoids circular dependency issues while stage arrays remain in the legacy helper
- the domain helper must not eagerly import catalogue contents while ownership remains outside the domain boundary

Any future catalogue migration must be a separate, explicitly scoped slice.

Until catalogue ownership moves:

- stage array contents remain the source of truth in the legacy helper
- the domain lookup helper must preserve reference identity
- the domain lookup helper must preserve current fallback behaviour

## Explicit non-goals

This boundary does **not** currently own:

- stage catalogue arrays
- progress/status calculation
- closed-case handling
- representation eligibility
- dashboard layout or calculations
- translations / EN-CY labels
- CRM/OData query construction
- API routes
- Redux state shape
- upload, submit, finalisation, or notification logic

## Behaviour-preservation invariants

Future slices must preserve:

- current stage IDs
- translation keys
- alias behaviour
- unknown input behaviour
- current fallback semantics
- current specialist-process override semantics
- status-vs-stage ambiguity
- current closed-case behaviour

## Known oddities to preserve

1. `statuscode` is currently passed into stage/progress logic.
    - Do not rename or reinterpret this without a separate behaviour-change decision.

2. Specialist-process overrides are intentionally narrow.
    - They currently apply only through the existing appeal-type-based resolution path.
    - Do not broaden this behaviour during refactor.

3. Some specialist process values appear placeholder-like.
    - Do not “correct” them without CRM/product confirmation.

4. Some ROW inputs currently produce non-intuitive stage output.
    - Preserve characterized behaviour unless explicitly changing business rules.

5. The test harnesses are VM-based and import-sensitive.
    - Future extractions must update harness injections carefully and avoid broad rewrites.

## Testing expectations

Future slices should run:

```bash
node tests/phase22/case-lifecycle-stage-case-type-resolution.test.cjs
node tests/phase22/case-lifecycle-specialist-process-stage-mapping.test.cjs
node tests/phase22/case-lifecycle-appeal-type-mapping.test.cjs
node tests/phase22/case-lifecycle-specialist-process-normalization.test.cjs
node tests/phase22/case-lifecycle-stage-wrapper.test.cjs
node tests/phase22/representation-build-reps-arr-rules.test.cjs
npm run lint
```

## Future extraction order

Recommended future order:

1. stage catalogue lookup helper
2. stage catalogue ownership only after enough characterization coverage
3. progress/status calculation extraction
4. additional read-only consumers
5. representation eligibility only as a separate policy slice after characterization