A flush reports a violated unique constraint. How should the write path turn that into a specific business error?

## Two different things get called a duplicate | | Constraint violation | Business duplicate | |---|---|---| | What it is | the engine rejected a row against a declared rule | a rule about the domain the user must be told about | | Who defines it | the schema | the product | | Detected by | the write failing | matching the rule, however it is expressed | | Always implies the other? | no - some are technical guards or repeated writes | no - some rules no constraint expresses | The write path's job is to decide, for **this** violation, whether it is the second thing. Treating the two as synonyms produces both of the classic bugs: a technical guard rendered to the user as *that name is taken*, and a genuine business rule that no constraint enforces silently letting duplicates through. ## What the failure actually carries A translated constraint violation typically carries the engine's original failure as its cause, and from that the **name of the constraint** that rejected the row. That name is the only stable identifying detail. The message is prose, the numeric code says only *integrity*, and the column list is not always present. This has a practical consequence for schema work: constraints must be **named on purpose**. A generated name is unstable across environments and meaningless to read, so the mapping either breaks or becomes unreadable. Name the constraint after the rule it enforces, in the migration that creates it, and put the mapping to the business meaning where a reader of that migration will find it. ## Building the mapping 1. **Enumerate the constraints on the table** and decide, for each, whether a violation is a business outcome, a bug, or a benign repeat. 2. **Write the map explicitly** - constraint name to outcome - as data the application owns, not as a chain of string matches on failure text. 3. **Give unmapped names a default**: treat an unrecognised constraint as a bug, log it loudly with the name, and surface a generic failure. A new constraint added later then shows up in the logs instead of being silently reported as somebody's duplicate email. 4. **Cover the non-unique kinds too.** A foreign-key or check violation reaching the write path usually means the code let inconsistent data through; those deserve a loud failure rather than a friendly message. ## The response must be built after the rollback The flush that failed condemned the unit and left the tracked objects describing nothing real. So the friendly response cannot be produced by reading through that unit: - Capture what the message needs **before** the flush - the submitted value, the identifier the user typed. - If a lookup is genuinely required (say, to tell the user which of their records already holds the value), do it **after** the boundary has rolled back, in a fresh unit. - Do not attempt to continue the use case after mapping the violation. The mapping produces an outcome to return, not permission to keep writing. ## Violations that are not the user's problem Some unique constraints exist to keep the system honest rather than to express a rule anyone typed: an idempotency key on a request, a natural key that deduplicates an import, a uniqueness guard behind an at-least-once message delivery. When one of those is violated, the right response is usually to treat the operation as **already done** - the row exists because a previous attempt succeeded - and return the same outcome as that attempt. Rendering it as a validation error tells the user something false. ## Rules a constraint will not catch The reverse gap matters just as much. Uniqueness rules that involve case folding, trimming, an active-versus-archived flag, or a scope such as *unique per tenant* only reach the engine if the schema was declared to express exactly that. If it was not, the write path can never receive a violation for them, and no amount of failure mapping will help. Deciding which of those rules should be pushed into the schema and which stay in application logic is a schema-design question rather than a failure-handling one; the failure-handling rule is simply that you can only map violations that the schema can actually raise. ## What good looks like in review - No branch anywhere reads the wording of a failure message. - Every constraint on a write-heavy table appears in the map, or is deliberately marked as *unexpected*. - The user-facing outcome is produced from captured values, after the unit has ended. - Constraint names in the schema read like the rules they enforce, so the map is checkable by eye.