Task: Write temporal composite entity versioning architecture document
This page documents a task in the Temporal composite entity versioning story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Write the target-state architecture document for versioning composite (parent + child) entities, so implementation stories have a single agreed design to work from.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Temporal composite entity versioning |
| Now | Nothing. |
| Waiting on | Sign-off on: child DELETE bumping the parent, flag names, mandatory reason-code stamping. |
| Next | Nothing. |
| Last touched | 2026-07-06 |
Acceptance
- Document written at Temporal composite entity versioning: target state under doc/knowledge/architecture, wired into the knowledge index.
- Covers: the target model (option A), SQL enforcement mechanism, as-of read-side composition, Qt composite history UX, rollout plan.
- Open decisions explicitly called out rather than silently assumed.
Plan
Surveyed the existing bitemporal conventions (Time and Timestamps) and
the codegen insert-trigger version-management block
(sql_schema_domain_entity_create.mustache) to ground the design in
what already exists, then the party_identifier FK model
(ores.refdata.party_identifier, its :list_by: flag) as the extension
point for the new mechanism. Confirmed via grep there is no existing
"bump parent version" or "cascade" precedent anywhere in
projects/ores.sql or projects/ores.codegen — this is genuinely
greenfield.
Notes
Key insight that shapes the whole design: because the parent bump
happens in the same transaction as the child write, the parent's
[valid_from, valid_to) windows end up exactly partitioning time into
"child-set-stable" epochs by construction. That means "compose parent
as of version N" is a plain temporal window join against the
children (interval overlap), not a separate version-mapping
mechanism — this generalises the existing single-table as-of point
query (valid_from < t and valid_to > t=, per Time and Timestamps) to a
window.
Flagged 3 open decisions rather than picking silently: whether child DELETE should also bump the parent (proposed yes), the actual codegen flag names, and whether reason-code stamping on the touch function is mandatory. Also explicitly scoped multi-level cascading (grandchild → child → parent) out of v1.
Reviewed with the author: the read-side design (fetch parent, note its
[valid_from, valid_to) window, fetch each child table as-of that
window) confirmed to match intent — "temporal window join" is
terminology for that two-step fetch, not a mandate for a single SQL
JOIN statement. Save-side design (bump parent in the same
transaction as the child write, standardized reason-code comment)
confirmed to match intent as originally proposed. Proceeding straight
to an implementation story.
PRs
| PR | Title |
|---|---|
| #1469 | [sql,codegen,qt] Temporal composite entity versioning |
Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|
Result
Document written and reviewed: Temporal composite entity versioning: target state. Target model (option A), SQL touch-function mechanism, as-of window-join composition, Qt composite history UX, and rollout plan all confirmed against intent. Open decisions (child delete, flag names, mandatory reason-code stamping) carried forward to the implementation story rather than blocking this task.