Task: Write temporal composite entity versioning architecture document

Table of Contents

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.

Emacs 29.3 (Org mode 9.6.15)