Edit-Draft-Publish Lifecycle

Reference Data in Arda is edited directly by users. Its values feed into other Reference Data entities and into transactional workflows. To protect data integrity while still supporting iterative editing, all Reference Data follows a consistent Edit-Draft-Publish lifecycle.

Key Behaviors

Reference Data entities have two cross-cutting behaviors:

Bitemporality

Every Reference Data entity maintains a history along two time dimensions:

• recordedAt — when the value was recorded in the system (transaction time).
• effectiveAt — when the value is effective for use by other processes (valid time).

The value at any pair of these TimeCoordinates is immutable. Creations, updates, and deletions each produce a new bitemporal record — old records are never overwritten. Consumer processes can retrieve the active value at any past or future time coordinates.

Published vs. Draft

When a user creates or modifies a Reference Data entity, they can save it as either Draft or Published:

• Published — a new bitemporal record is inserted into the entity’s permanent history. Other processes can immediately use this value.
• Draft — a temporary record is held by the system. The entity’s history is unchanged. The draft can be edited further, then published or discarded. Only one draft per entity is supported at any time.

Lifecycle State Machine

Start --> Creating --> Published (via publish [validateOK])
                   --> Discarded (via discard)
                   --> Creating (via publish [validateError])

Published --> Editing (via edit)
Editing   --> Published (via publish [validateOK])
Editing   --> Editing (via save draft)
Editing   --> Editing (via publish [validateError])
Editing   --> Published (via discard -- reverts to last published)
Editing   --> Deleted (via delete)
Published --> Deleted (via delete)

States

State	Description
Creating	Ephemeral UI state while the user is entering data for a new entity. No backend record exists yet.
Editing	User is actively changing a published entity. The system retains the current draft.
Published	A record is saved and entered into the entity’s bitemporal history.
Deleted	The entity is marked deleted. Bitemporal history is preserved.

Transitions

From	To	Trigger	Notes
Start	Creating	create	System presents the creation form.
Creating	Published	publish [validateOK]	First record created in history.
Creating	Creating	publish [validateError]	Validation failed; user corrects and retries.
Creating	End	discard	User cancels; no backend record kept.
Published	Editing	edit	Draft initialized from the current published record.
Editing	Editing	save draft	Updated draft saved; no validation performed.
Editing	Editing	publish [validateError]	Validation failed; draft retained.
Editing	Published	publish [validateOK]	New bitemporal record created; draft discarded.
Editing	Published	discard	Draft deleted; entity stays at last published values.
Editing	Deleted	delete	Entity marked deleted; draft removed.
Published	Deleted	delete	New bitemporal deletion record created.

Notes and Edge Cases

• edit and delete actions may carry additional validations that prevent the transition.
• On publishing, the module that manages the entity emits notifications to subscribed modules.
• discard while in the Editing state may prompt the user for confirmation.