E6 ยท Publication Volume 28

Versioning Data and Interpretations

snapshots, validity, branching, approval and diff

*snapshots, validity, branching, approval and diff*

Immutable snapshots, interpretation branches, approval gates and semantic differences
Immutable snapshots, interpretation branches, approval gates and semantic differences

Learning objectives

This lesson is general and institution-neutral. It uses no real company, individual, property, project or identifiable place. Generic roles describe responsibilities only, and SYN-ARCH identifiers denote explicitly synthetic teaching evidence.

  • Frame the decision governed by snapshots, validity, branching, approval and diff.
  • Model the relevant boundaries, states and contracts before selecting an implementation.
  • Define measurable invariants, failure evidence and a safe release consequence.
  • Produce a data-and-interpretation version policy with semantic diff rules from synthetic evidence and defend its trade-offs.

Decision boundary

Version what a decision actually depends on: observations, corrections, classifications, interpretations, parameters, contracts, policy and approval state. Do not overwrite a prior assertion merely because a newer one exists. Distinguish valid time, when a statement applies in the described world, from system time, when the system recorded or superseded it. A snapshot fixes a coherent set for retrieval and replay. A branch permits alternative interpretation without claiming both are approved truth. Merge is a reviewed scientific decision with explicit conflicts, not an automatic file operation.

Core concepts

Identity, revision, version, snapshot and release serve different purposes. Identity answers what entity or interpretation is referenced. A revision records changed representation or assertion. A snapshot closes over dependencies at one reproducible boundary. A release adds review and publication status. Content-oriented version labels can communicate compatibility, but they do not replace data lineage, validity or scientific significance. Differences must be semantic: an attribute correction, reference change, geometry displacement, topology change, classification change and approval change have different consequences even when byte counts are similar.

System model and contracts

Maintain immutable assertion or artefact versions linked by derived-from, revises, supersedes, alternative-to and merged-from relations. Each records identity, version, valid interval, recorded interval, source evidence, transformation, authoring role, review state and digest. A snapshot manifest lists exact member versions and dependency closure. A branch names an evolving interpretation lineage; an approval points to one immutable snapshot rather than to a moving branch head. A semantic diff service returns added, removed, changed and unchanged identities plus domain-specific measures, unresolved conflicts and comparability warnings.

Invariants and acceptance criteria

| Invariant | Test evidence | Release consequence | |---|---|---| | No published observation or interpretation is overwritten in place. | contract test and recorded counterexample | block publication | | Every approval points to one complete immutable snapshot. | replay comparison and digest check | quarantine the artefact | | Valid time remains distinct from system recording time. | role-based acceptance trace | return the decision unresolved | | Semantic diffs declare identity, reference and tolerance rules. | failure injection and recovery record | retain the last verified version | | Branch conflicts remain explicit until a reviewed resolution is recorded. | domain review against declared evidence | record an explicit review finding |

Quantitative engineering

Report change by meaning as well as count. Geometry displacement may use declared horizontal and vertical distances; classification change uses a transition matrix; interval change reports overlap, gap and boundary movement; raster change reports valid-cell coverage and value distribution; model change reports volume or surface-distance summaries with uncertainty. Snapshot completeness is C_s=n_{resolved}/n_{declared} and must equal one for publication unless missing members are explicitly permitted. Diff thresholds select review attention but never redefine scientific equivalence without evidence.

Data quality, evidence and uncertainty

Version evidence includes the before and after manifests, reason for change, source observations, transformation or manual edit record, validation results, reviewer findings and approval action. Corrections preserve the incorrect historical assertion and mark its supersession so earlier decisions remain explainable. A branch conflict retains both alternatives and the evidence cited by each. Test diffs with unchanged re-encoding, reordered records, reference transformation, split and merge identities, null transitions and deleted evidence. Byte difference alone cannot tell whether meaning changed.

Interoperability and versioning

Every retrieval contract states whether it accepts an immutable version, snapshot, branch head, validity time or current approved alias. Current is resolved to a concrete snapshot in the response so a client can repeat the request. Version identifiers are opaque stable values; human-readable labels are metadata. Diff contracts declare comparison basis, reference normalization, tolerance, identity matching and unsupported cases. Exported packages retain version graph edges and approval evidence. A compatibility label applies to schema or interface behaviour and must not be used as a substitute for scientific change notes.

Security and professional responsibility

Historical visibility follows policy; retaining a version does not mean every role may retrieve it. Branch membership, review comments, rejected interpretations and sensitive extents can require narrower access than an approved release. Authorise diff endpoints against both sides because a difference can reveal hidden content. Approval and supersession are audited privileged transitions with separation of duties. Immutable history needs integrity and retention controls, while lawful or policy-driven removal uses a visible tombstone or restricted record so references fail explicitly rather than resolving to different content.

Operational workflow and observability

Observe branch age, unresolved conflicts, snapshot closure, approval queue, alias movement, diff cost, failed historical reads and dependency retention. Before moving an approved alias, validate the target snapshot, record the prior target and update atomically. Reconcile manifests with retained artefacts and alert when a dependency is missing or digest changes. Migration creates new versions and a mapping report; it never rewrites old members in place. Deprecation preserves a read path or documented export long enough to satisfy the declared evidence-retention policy.

Integration checkpoint

Connect the versioning data and interpretations artefact to the preceding volume architecture. Trace one synthetic object from source identity through the new boundary to a reviewed output, then trace one rejection or failure back to the earliest violated invariant. Update the architecture decision record with the chosen option, alternatives, assumptions, evidence, consequences, owner role, review state and triggers for reconsideration. A checkpoint passes only when another reviewer can reconstruct both the successful path and the blocked path without oral explanation.

Synthetic worked example

SYN-ARCH-08 initially stores only the latest interpreted boundary. A reference correction shifts two source intervals, but the updated surface overwrites the approved one and an earlier decision becomes irreproducible. The revised model preserves both observation revisions, creates two interpretation branches and compares them using identity changes, boundary displacement and affected volume. The review resolves one conflict, records another as open and approves an immutable snapshot. The current alias moves atomically, while the prior snapshot and its decision evidence remain retrievable under policy.

Practice and assessment

  1. Which identities, times and dependencies define a reproducible snapshot?
  2. What semantic change measures are meaningful for this evidence type?
  3. How are alternative interpretations represented without false consensus?
  4. What approval and retention evidence must survive alias movement?

Assessed artefact: a data-and-interpretation version policy with semantic diff rules. Submit the artefact with its source manifest, acceptance evidence, unresolved risks and a short explanation of why one plausible alternative was not selected.

Common failure modes

  • Keeping only the latest record and calling it version history.
  • Approving a moving branch head rather than an immutable snapshot.
  • Using one compatibility label to imply scientific significance.
  • Comparing bytes without normalizing reference and identity semantics.
  • Automatically merging competing interpretations without domain review.

Sources and further reading