--- id: STATE-CRM-ACT-001 title: Activity status object: DOM-CRM-ACT-001 product_area: crm module: activities-tasks revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f states: - name: scheduled meaning: >- An interaction is planned and appears among upcoming items; passing its instant marks it overdue. provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:updateActivity' - name: completed meaning: >- The interaction is finished and appears in history, with completion-specific entry requirements applied. provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:updateActivity' - name: cancelled meaning: The interaction will not proceed and remains in history as a cancelled plan. provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:updateActivity' - name: deleted meaning: >- The live interaction and its owned associations and file entries have been removed; revision history is retained. provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:updateActivity' transitions: - from: scheduled to: completed trigger: An ordinary edit chooses completed as the interaction status. guard: >- The read version matches, updates are unlocked, and the proposed values satisfy the type’s field requirements. side_effects: - >- The database refreshes status on the interaction’s links and captures the committed revision. - >- The interaction appears in history and must satisfy any required completion duration and result. who: 'A caller authorized to update activities, including the delegated import path.' provenance: observed source: 'services-crm:modules/activities/services/activities/field-modes.ts:fieldModeProblems' - from: scheduled to: cancelled trigger: An ordinary edit chooses cancelled as the interaction status. guard: >- The read version matches, updates are unlocked, and the proposed values satisfy the type’s field requirements. side_effects: - >- The database refreshes status on the interaction’s links and captures the committed revision. - The interaction appears in history without completion-only requirements. who: 'A caller authorized to update activities, including the delegated import path.' provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:updateActivity' - from: completed to: scheduled trigger: An ordinary edit chooses scheduled as the interaction status. guard: >- The read version matches, updates are unlocked, and the proposed values satisfy the type’s field requirements. side_effects: - >- The database refreshes status on the interaction’s links and captures the committed revision. - >- The interaction appears in upcoming items; completion-only requirements no longer apply. who: 'A caller authorized to update activities, including the delegated import path.' provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:updateActivity' - from: completed to: cancelled trigger: An ordinary edit chooses cancelled as the interaction status. guard: >- The read version matches, updates are unlocked, and the proposed values satisfy the type’s field requirements. side_effects: - >- The database refreshes status on the interaction’s links and captures the committed revision. - The interaction appears in history without completion-only requirements. who: 'A caller authorized to update activities, including the delegated import path.' provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:updateActivity' - from: cancelled to: scheduled trigger: An ordinary edit chooses scheduled as the interaction status. guard: >- The read version matches, updates are unlocked, and the proposed values satisfy the type’s field requirements. side_effects: - >- The database refreshes status on the interaction’s links and captures the committed revision. - >- The interaction appears in upcoming items; completion-only requirements no longer apply. who: 'A caller authorized to update activities, including the delegated import path.' provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:updateActivity' - from: cancelled to: completed trigger: An ordinary edit chooses completed as the interaction status. guard: >- The read version matches, updates are unlocked, and the proposed values satisfy the type’s field requirements. side_effects: - >- The database refreshes status on the interaction’s links and captures the committed revision. - >- The interaction appears in history and must satisfy any required completion duration and result. who: 'A caller authorized to update activities, including the delegated import path.' provenance: observed source: 'services-crm:modules/activities/services/activities/field-modes.ts:fieldModeProblems' - from: scheduled to: deleted trigger: A caller requests removal. guard: >- Neither deletion nor update-and-deletion protection is set; deletion does not require a read version. side_effects: - >- The interaction’s owned links and file entries are removed, and released files are submitted for cleanup. - >- Import matching references are dropped and the committed deletion is captured in history. who: A caller authorized to delete activities. provenance: test source: >- services-crm:modules/activities/tests/integration/services/persistence/activities.integration.spec.js#removes the activity and its links - from: completed to: deleted trigger: A caller requests removal. guard: >- Neither deletion nor update-and-deletion protection is set; deletion does not require a read version. side_effects: - >- The interaction’s owned links and file entries are removed, and released files are submitted for cleanup. - >- Import matching references are dropped and the committed deletion is captured in history. who: A caller authorized to delete activities. provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:deleteActivity' - from: cancelled to: deleted trigger: A caller requests removal. guard: >- Neither deletion nor update-and-deletion protection is set; deletion does not require a read version. side_effects: - >- The interaction’s owned links and file entries are removed, and released files are submitted for cleanup. - >- Import matching references are dropped and the committed deletion is captured in history. who: A caller authorized to delete activities. provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:deleteActivity' invalid: - from: deleted to: scheduled why: >- Deletion cannot be reversed through a restore action. Its live creation digest is also removed, so a later accepted creation using an available identifier is a new operation. source: >- services-crm:modules/activities/services/persistence/activities.ts:replayActivityCreate provenance: observed - from: scheduled to: completed why: >- An update lock or missing completion-required duration or result prevents this save. Field-mode validation returns its collected problems together. provenance: observed source: 'services-crm:modules/activities/services/persistence/activities.ts:updateActivity' concurrency: >- Ordinary edits lock the live record and compare the supplied read version; only the first conflicting edit can commit from the same version. Deletion is serialized without a version argument. Link status copies change within the activity transaction. invariants: - INV-DOM-CRM-ACT-001-04 - INV-DOM-CRM-ACT-001-07 - INV-DOM-CRM-ACT-001-10 - INV-DOM-CRM-ACT-001-11 evidence: - >- services-crm at a8d1364f: modules/activities/db/activities.table.ts (ACTIVITY_STATUSES), activity-links.table.ts (copies); services/persistence/activities.ts; services/activities/field-modes.ts. - >- react-console at baf6dae3: lib/activities/form-rules.ts and schedule-status.test.ts (future-dated entries default to Scheduled). --- # Activity Status ## The Lifecycle ```mermaid stateDiagram-v2 scheduled --> completed: save status scheduled --> cancelled: save status completed --> scheduled: save status completed --> cancelled: save status cancelled --> scheduled: save status cancelled --> completed: save status scheduled --> deleted: remove completed --> deleted: remove cancelled --> deleted: remove ``` The three persisted statuses describe an interaction’s progress, while Deleted describes absence of its live row. Creation accepts a selected status or uses the type’s default. The console proposes a scheduled entry for a future instant unless the user has already selected a status. ## Transitions Explained Any persisted status can be changed to either other status through an ordinary edit. Activities have no separate completion or cancellation command. The structured transition rows give save requirements, timeline placement and revision effects. ## What Cannot Happen A removed interaction cannot be restored through the API. Write locks and field requirements can prevent an otherwise supported status change. Passing the scheduled instant changes its computed overdue display without updating the stored status. ## Concurrency and Timing Read versions protect ordinary edits from overwriting a newer save. Status copies and revision capture share the transaction. Deletion uses locking but takes no read version, so it has a different conflict contract.