No hard delete

Status: Accepted, stated in the project's written engineering rules. This record covers the rule that no record of Cluster ERP is removed by a user action. A delete becomes a deactivation with a reason, every deactivation is kept in core_change_history, and only a retention purge removes rows for good. The columns and routes are explained on soft delete and deactivation.

Context¶

The project's written engineering rules forbid physical deletion and list three deliberate exceptions: dependent child rows that are renewed wholesale with their owner, derived summary cells that are rebuilt, and event rows removed by the retention purge. An earlier mechanism, a database-trigger vault, was removed in July 2026. The migration that removed it states the reason: deactivations are recorded in the permanent change history, and the only physical deletion is the retention purge (migrations/versions/dropvault_0001_remove_deletion_vault.py:1-11).

Decision¶

• A record is active while deleted_at is empty and deactivated when it holds a time. deleted_by, deactivation_reason, and deactivation_note record who and why (src/cluster_erp/core/models.py:49-72).
• A user's delete deactivates; the record can be listed among passive records and reactivated (src/cluster_erp/modules/records/lifecycle_routes.py:115-133, src/cluster_erp/modules/records/lifecycle_routes.py:225-249).
• Every deactivation and every change is recorded automatically by the change-history listener.
• The retention purge is the only general physical deletion (src/cluster_erp/modules/records/retention/purge.py:1-6).

The flowchart shows the life of a record.

flowchart TD
 del["user deletes a record"] --> deact["deleted_at set, reason and note stamped"]
 deact --> hist["before_flush writes a deactivate row to core_change_history"]
 deact --> passive["record listed among passive records"]
 passive -->|activate| live["deleted_at cleared, activate row written"]
 passive -->|retention window passed| purge["purge_expired removes the row"]

In prose: when deleted_at moves from empty to a value, the listener stamps the actor, reason, and note on the row and writes a deactivate history row (src/cluster_erp/core/change_history.py:331-342). Activation clears deleted_at and writes an activate row. After the configured number of years, purge_expired deletes deactivated rows and old history (src/cluster_erp/modules/records/retention/purge.py:33-45).

Consequences¶

• Bulk deactivation loads each object and sets deleted_at through the ORM, so the history and the reason stamp apply to every row (src/cluster_erp/core/bulk_operations.py:20-55).
• Uniqueness applies only to live rows, through partial indexes with WHERE deleted_at IS NULL, so a deactivated value can be used again. Example: uq_core_deactivation_reasons_code_live (src/cluster_erp/modules/records/deactivation_reasons/models.py:18-25).
• Queries over business data filter out deactivated rows; analytics tests state this as a consequence of the rule (tests/test_analytics_gates.py:423).
• The deliberate exceptions go through the ORM so the history still records each removal:

orm_delete_where is the shared helper for the child-row cases (src/cluster_erp/core/bulk_operations.py:58-75).

Where the code enforces it¶

Not determined from code: a repository-wide test that rejects DELETE statements outside the purge and the listed exceptions. None was found in tests/.

Related pages¶

• Decision records
• Soft delete and deactivation
• Change history
• Records module (records)

Verified against commit 92f8051 on 2026-11-13.