--- id: WF-CRM-DQ-005 title: 'Prepare, refresh and change a merge plan' trigger: >- An administrator with type-specific read and merge authority creates, opens, changes or validates a plan. product_area: crm module: data-quality revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 implements: - CAP-CRM-DQ-012 - CAP-CRM-DQ-013 - CAP-CRM-DQ-014 - CAP-CRM-DQ-015 - CAP-CRM-DQ-017 moves: - STATE-CRM-DQ-004 crosses: - SVC-CRM-DQ-merges - SVC-CRM-ENT-entities idempotency: >- Creating starts a fresh plan. Unchanged open-plan reads avoid writes, while changed recomputations update the stored preview with optimistic version protection. concurrency: >- Qualified administrators share workspace plans. Their edits and read-triggered writes compare versions, so merely refreshing a changed preview can invalidate another administrator’s pending edit. hops: - 'n': 1 actor_or_service: Merges route action: >- Require at least one complete planning permission pair, then look up an existing plan’s type and require that type’s pair. anchor: 'services-crm:modules/merges/aws/api/merges.routes.ts:requireAccessToPlan' seam: sync on_failure: >- Refuse unqualified callers before lookup; otherwise refuse missing authority for the discovered type. left_inconsistent: No plan values are changed by an access refusal. observer: caller. provenance: observed source: 'services-crm:modules/merges/aws/api/merges.routes.ts:requireAccessToPlan' - 'n': 2 actor_or_service: Merge planning action: >- Validate the selection, reject absorbed identities, read snapshots, recommend a survivor and construct the complete merge preview. anchor: 'services-crm:modules/merges/services/merges/merge-plans.ts:createMergePlan' seam: sync on_failure: 'Return validation, missing-record or absorbed-record refusal.' left_inconsistent: Planning refusal persists no new plan. observer: administrator. provenance: test source: >- services-crm:modules/merges/tests/integration/services/persistence/record-merge-plans.integration.spec.js#refuses more records than a merge takes - 'n': 3 actor_or_service: Other application plan functions action: >- Discover application-owned plan functions and ask them for their proposed changes inside the CRM transaction. anchor: 'services-crm:modules/merges/services/persistence/merge-participants.ts' seam: sync on_failure: >- Raised errors fail the request; missing required function pairs become blockers. left_inconsistent: No merge business changes are applied during planning. observer: administrator sees blockers. provenance: test source: >- services-crm:modules/merges/tests/integration/services/merges/required-participants.integration.spec.js#blocks it as a participant that is missing, naming the functions it could not call - 'n': 4 actor_or_service: Merge planning action: >- Recompute open-plan reads, edits and validation, retain valid answers and persist a changed preview, hash and status. anchor: 'services-crm:modules/merges/services/merges/merge-plans.ts:readMergePlan' seam: sync on_failure: Reject a version race without overwriting the later preview. left_inconsistent: The previous stored plan remains if this write fails. observer: 'administrator, through dropped answers and stale refusals.' provenance: test source: >- services-crm:modules/merges/tests/e2e/merges.e2e.spec.js#answers the validation with the plan as it is now, ready to execute - 'n': 5 actor_or_service: Merge planning action: >- Merge submitted answers by question, apply explicit clears and reject choices unavailable in the recomputed preview. anchor: 'services-crm:modules/merges/services/merges/merge-plans.ts:updateMergePlan' seam: sync on_failure: Return invalid-choice or stale refusal. left_inconsistent: Unaccepted decisions are not written. observer: administrator. provenance: test source: >- services-crm:modules/merges/tests/e2e/merges.e2e.spec.js#refuses it as an invalid resolution rather than storing a decision nobody can apply branches: - >- Executing, executed and expired plans return their stored preview without a new computation. - Organization previews include choices for linked employee detail slots. evidence: - >- services-crm at a8d1364f: modules/merges/aws/api/merges.routes.ts; services/merges/merge-plans.ts, merge-plan-objects.ts; services/planning/*.ts; services/persistence/merge-snapshots.ts, merge-participants.ts, record-merge-plans.ts. controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-IAM-001, TC-IAM-005, TC-IAM-006, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003] --- # Prepare, Refresh And Change A Merge Plan ## What It Does Planning produces proposed survivor values, required choices, omissions and application reference changes before execution. Open plans are recomputed when requested; the displayed result describes that computation rather than guaranteeing it stays current after the response. ## The Flow ```mermaid flowchart TD H1["Require at least one complete planning permission pair, then look up an existing plan’s type and require that type’s pair."] H2["Validate the selection, reject absorbed identities, read snapshots, recommend a survivor and construct the complete merge preview."] H1 --> H2 H3["Discover application-owned plan functions and ask them for their proposed changes inside the CRM transaction."] H2 --> H3 H4["Recompute open-plan reads, edits and validation, retain valid answers and persist a changed preview, hash and status."] H3 --> H4 H5["Merge submitted answers by question, apply explicit clears and reject choices unavailable in the recomputed preview."] H4 --> H5 ``` ## When Something Fails Plan writes are version-guarded. A changed read stores a new approval boundary, so another authorized administrator opening the plan can both renew its hash and make an existing editor stale. ## Open Design Questions Product needs to resolve shared editing and cross-user approval renewal. The unfinished-plan API is present but has no corresponding mounted console list.