pedwfrontend/lib/domain/case-lifecycle

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:

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