Decisions · ADR-005

Closed-set actions

Status
Accepted
Date
Updated
Surfaces on

Audit actions and compliance statuses are typed enums constrained at the database layer. Values outside the fixed lists are rejected.

Context

Compliance rules are determined by statute. The platform must operate on the actions and statuses the law permits. Ad-hoc text fields, “OTHER” categories, or open-ended enum tail-positions invite the platform to drift outside the legal framework. A future engineer adding 'misc' to a status enum, even with good intent, breaks the audit-defensibility story: a regulator asking “what statute authorizes this status?” gets no answer.

Decision

Every admissible action and status is modeled as a closed enum constrained at the database layer (CHECK constraint) and the type layer (discriminated union). The closed sets are the audit actions (create, update, state change, version, delete, link, unlink) and the compliance statuses (eligible, ineligible, pending, waived). New enum members require a code change, schema migration, and a deployment, not a configuration tweak.

Consequences

The platform cannot record a status or audit action outside its defined lists. Adding a new compliance scenario requires an explicit decision point: an engineer, a code review, a deployment. Configuration-driven flexibility is sacrificed; rigid statute-alignment is gained. State agencies whose policy interpretation differs from the statute cannot route around the platform’s constraints by tweaking a config; they have to update the statute interpretation in code, which leaves an audit trail.

Alternatives considered

  • JSON schema validation at the API boundary only. Rejected: doesn’t prevent direct database writes from internal services. The constraint must live at the storage layer to be defensible.
  • Closed enum with an OTHER escape hatch for “edge cases.” Rejected: OTHER is the failure mode this decision exists to prevent. Edge cases that the statute doesn’t recognize should fail loudly, not slot into a generic bucket.

References

  • statuteH.R. 1 § 71119 (federal community engagement requirement)
  • statute42 U.S.C. § 1396a(xx)(7) (statutory exclusion categories)