# Query Profile Compatibility Contract

## Purpose

This document records the current compatibility contract around:

- `actions/selectQueryTypes.js`

That file is primarily:

- **CRM/OData query-shape configuration**
- **CRM compatibility handling**

It is **not primarily business-rule logic**.

Its main job today is to ensure the portal requests the fields that each CRM entity actually exposes so downstream case-summary, representation, status, lifecycle, and infrastructure views continue to function.

---

## Source of Truth

The **CRM field names are the source of truth**.

The website must query the fields that actually exist on each CRM entity.

This includes preserving:

- historic naming differences
- spelling mistakes
- singular/plural variants
- entity-specific field names
- legislation-specific field models

Future work must treat field selection as a **compatibility-sensitive integration concern first**.

The goal is not to make the query profiles look tidy.

The goal is to preserve the fields that the live system currently depends on.

---

## Appeal-Type Differences

Different appeal types legitimately require different fields because they support different:

- legislation
- workflows
- representation windows
- event models
- authority models
- infrastructure/project processes

This means:

- similar-looking appeal types must **not automatically be treated as identical**
- near-duplicate field bundles must **not automatically be collapsed**
- infrastructure-style entities must **not automatically be forced into planning-style shapes**
- minimal profiles must **not automatically be expanded to match richer bundles**

Bundle-by-bundle evaluation is required.

---

## CRM Compatibility Variants

The current compatibility contract includes representative field variants that must be preserved.

### Specialist-process variants

- `pinswg_specialistcaseprocess`
- `pinswg_speacialistcaseprocess`

These are not interchangeable in the current query profiles.

Representative characterization showed:

- ROW uses `pinswg_specialistcaseprocess`
- Adverts uses `pinswg_speacialistcaseprocess`

### Start-date variants

- `pinswg_startdate`
- `pinswg_startdates`
- `pinswg_applicationacceptedasvalid`

These reflect different representation-window and process models across entities.

### Statement-date variants

- `pinswg_statementduedate`
- `pinswg_statementsduedate`

These must not be normalized away.

### Project description variants

- `pinswg_projectdescription`
- `pinswg_projectdiscription`

Harbour Revision Orders currently preserve the misspelled variant.

### Decision variant

- `pinswg_dicision`

Planning S78 currently preserves this field name in its query profile.

### Other representative compatibility-sensitive variants

- `pinswg_otherpartiesstatement`
- `pinswg_otherpartiesstatements`
- `pinswg_otherpartiesstmt`

- `pinswg_suspensionstartdates`
- `pinswg_suspensionstartdate`

- `pinswg_startdateofevent`
- `pinswg_startdateoftheevent`
- `pinswg_starttimeofevent`
- `pinswg_starttimeoftheevent`
- `pinswg_startdatetimeiftheevent`

These variants must be preserved until characterization-based extraction or change work explicitly proves otherwise.

---

## Characterized Field Families

The current characterization work identifies the following conceptual families already present inside `selectQueryTypes.js`.

### 1. Planning-style fields

Representative concerns include:

- base case identity fields
- planning-style address fields
- decision/date/status fields
- event support fields

These appear across many planning and enforcement-style entities, but not always with identical field names.

### 2. Representation-window fields

Representative fields include:

- `pinswg_startdate`
- `pinswg_startdates`
- `pinswg_applicationacceptedasvalid`
- `pinswg_statementduedate`
- `pinswg_statementsduedate`
- `pinswg_finalcommentsduedate`
- `pinswg_endofrepresentationperiod`

These coexist today and reflect different entity models.

### 3. Specialist-process fields

Representative fields include:

- `pinswg_specialistcaseprocess`
- `pinswg_speacialistcaseprocess`

These must not be silently unified.

### 4. Infrastructure / project fields

Representative concerns include:

- project description
- project location
- submission / publication milestones
- recommendation / report fields
- suspension dates
- grid-reference fields

These are particularly important in DNS / Harbour / Transport / Electricity style bundles.

### 5. Authority / LPA fields

Representative fields include:

- `_pinswg_localplanningauthority_value`
- `_pinswg_associatedlpa_value`
- `pinswg_relevantauthorityname`

These represent different authority models across bundles.

### 6. Consultation fields

Representative fields include:

- `pinswg_consultationopen`
- `pinswg_consultationclose`

These are currently characteristic of SIPS-style profiles.

### 7. Minimal-profile bundles

Representative examples include:

- `pinswg_nonvalidations`
- `pinswg_ldps`

These are intentionally smaller than richer planning and infrastructure bundles.

---

## Characterized Divergences

Characterization work also confirmed that some similar bundles intentionally differ.

Representative examples:

### Advert vs ROW specialist-process fields

- Advert preserves `pinswg_speacialistcaseprocess`
- ROW preserves `pinswg_specialistcaseprocess`

These must not be accidentally collapsed into one shared field choice.

### Harbour vs DNS project-description fields

- Harbour preserves `pinswg_projectdiscription`
- DNS preserves `pinswg_projectdescription`

### Suspension-start variants

- DNS preserves `pinswg_suspensionstartdates`
- Harbour and Transport preserve `pinswg_suspensionstartdate`

### Authority / LPA model differences

- S78 preserves `_pinswg_localplanningauthority_value`
- ROW preserves `_pinswg_associatedlpa_value` plus `pinswg_relevantauthorityname`
- DNS preserves `_pinswg_associatedlpa_value` without the planning-style relevant-authority field

### Event-date and event-time variants

Representative coexistence includes:

- `pinswg_startdateofevent`
- `pinswg_startdateoftheevent`
- `pinswg_starttimeofevent`
- `pinswg_starttimeoftheevent`
- `pinswg_startdatetimeiftheevent`

### Representation-support differences in similar bundles

Representative differences include:

- singular vs plural other-parties fields
- singular vs plural statement-due-date fields
- bundle-specific combinations of proof/questionnaire/final-comments fields

These differences must be treated as compatibility-sensitive unless explicitly re-characterized.

---

## Future Guidance

Future work in this area should follow these rules:

1. **Characterize first**
    - prove current behaviour before changing structure

2. **Extract later**
    - do not extract shared bundles or constants until the current compatibility contract is protected

3. **Preserve compatibility**
    - CRM field variants are not “cleanup noise”; they are part of the current live contract

4. **Evaluate bundle-by-bundle**
    - each bundle should be assessed on its own actual field requirements

5. **Avoid broad normalization**
    - do not assume similar names mean safe consolidation

6. **Protect intentional differences**
    - especially for:
        - specialist-process fields
        - representation-window fields
        - project-description fields
        - suspension-start fields
        - authority/LPA fields
        - event-date/time fields

The safest sequence remains:

- characterize current bundles
- characterize current families
- characterize duplicated clusters and divergences
- only then consider bounded extraction work

---

## Explicit Non-Goals

This characterization and documentation work does **not**:

- rename CRM fields
- remove typo fields
- redesign CRM entities
- standardize legislation-specific data
- force appeal types into identical query profiles
- introduce a query DSL
- move this concern into a broader business-rule domain boundary

Any future cleanup or extraction must preserve the documented compatibility contract unless an explicit behaviour-change decision is made.