<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/post-merge-partition-authority/">
  <id>https://docs.spec-kitty.ai/architecture/post-merge-partition-authority/</id>
  <title>Post-Merge Partition Authority</title>
  <updated>2026-09-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/post-merge-partition-authority/"/>
  <summary>One model for post-merge partition authority — the write half (which bytes win per artifact) and the read half (which surface a reader trusts).</summary>
  <content type="html">&lt;span id=&quot;post-merge-partition-authority&quot;&gt;&lt;/span&gt;
&lt;p&gt;After lane consolidation, two things have to be settled for every mission artifact:
&lt;strong&gt;which bytes win&lt;/strong&gt; when copies diverge, and &lt;strong&gt;which surface a reader trusts&lt;/strong&gt; for the
result. This page gives the one model that answers both. Where it came from is in
&lt;a href=&quot;#provenance&quot;&gt;Provenance&lt;/a&gt; at the end.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Terminology (per the &lt;code dir=&quot;auto&quot;&gt;primary&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; footgun canon).&lt;/strong&gt; “PRIMARY-partition”
below is the &lt;strong&gt;partition sense&lt;/strong&gt; — the stable planning artifacts (&lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;plan.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tasks/WP*.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;research/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt;) — never the
Primary-Branch (&lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;) sense. “Surface” is the read-resolution target (coord
branch vs primary), not a git branch instruction. See
&lt;a href=&quot;/context/orchestration/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/context/orchestration.md&lt;/code&gt;&lt;/a&gt; &lt;code dir=&quot;auto&quot;&gt;#primary-partition&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;the-one-question&quot;&gt;The one question&lt;/h2&gt;
&lt;p&gt;After a lane consolidation, &lt;strong&gt;what content is authoritative for each partition artifact,
and on which surface is that content read?&lt;/strong&gt; The mission split the question into
two halves that are facets of the same authority model:&lt;/p&gt;























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Half&lt;/th&gt;&lt;th&gt;Track&lt;/th&gt;&lt;th&gt;Authority decided&lt;/th&gt;&lt;th&gt;Failure it fixed&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Write&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;A (#3942)&lt;/td&gt;&lt;td&gt;Which &lt;em&gt;bytes&lt;/em&gt; win per artifact when a merge reconciles divergent &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; files&lt;/td&gt;&lt;td&gt;Older mission-branch planning copy silently clobbered a target-newer copy on squash&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Read&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;B (#4090)&lt;/td&gt;&lt;td&gt;Which &lt;em&gt;surface&lt;/em&gt; a post-merge reader trusts for WP lane state&lt;/td&gt;&lt;td&gt;A stale diverged coord husk was read as authoritative because the primary-wins guard was dormant&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Both halves are governed by the same partition classifier —
&lt;code dir=&quot;auto&quot;&gt;mission_runtime.kind_for_mission_file&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;is_primary_artifact_kind&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;src/mission_runtime/artifacts.py&lt;/code&gt;). Planning artifacts are
PRIMARY-partition-authoritative, so lanes must neither &lt;strong&gt;overwrite&lt;/strong&gt; them (write
half) nor be read as their post-merge &lt;strong&gt;home&lt;/strong&gt; (read half).&lt;/p&gt;
&lt;h2 id=&quot;track-a--the-write-seam-which-bytes-win&quot;&gt;Track A — the write seam (which bytes win)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Seam:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/lanes/consolidation.py::_merge_branch_into&lt;/code&gt; (the squash step)
plus the pure three-way recency helper
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/planning_recency.py::target_newer_primary_artifacts&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;The mission→target squash runs &lt;code dir=&quot;auto&quot;&gt;git merge --squash -X theirs &amp;#x3C;mission_branch&gt;&lt;/code&gt;.
&lt;code dir=&quot;auto&quot;&gt;-X theirs&lt;/code&gt; makes the &lt;strong&gt;source&lt;/strong&gt; (mission branch) win every add/add conflict.
That premise is correct for source-authored code and for the six driver-covered
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/**&lt;/code&gt; bookkeeping classes (reconciled by &lt;code dir=&quot;auto&quot;&gt;_MERGE_DRIVERS&lt;/code&gt;), but it is
&lt;strong&gt;false&lt;/strong&gt; for the PRIMARY-partition planning artifacts: those are authored on the
primary/target surface, so the target can legitimately carry a &lt;em&gt;newer&lt;/em&gt; copy than
the mission branch (#3942).&lt;/p&gt;
&lt;p&gt;A git merge driver cannot fix this. A driver sees only three blobs (base / ours /
theirs) and has no history access, so it cannot decide &lt;em&gt;which side is newer&lt;/em&gt; —
recency is a repository-history question. So the fix sits &lt;strong&gt;outside&lt;/strong&gt; the byte-
identical &lt;code dir=&quot;auto&quot;&gt;-X theirs&lt;/code&gt; block: after the squash,
&lt;code dir=&quot;auto&quot;&gt;_preserve_target_newer_planning_artifacts&lt;/code&gt; (in &lt;code dir=&quot;auto&quot;&gt;lanes/merge.py&lt;/code&gt;) calls the pure
helper, restores each target-owned path from the pre-advance &lt;code dir=&quot;auto&quot;&gt;target_branch&lt;/code&gt;
blob, and &lt;strong&gt;amends&lt;/strong&gt; the squash commit so the preserved content lands in the
single merge commit the ref-advance fast-forwards to. The preservation is
surfaced to the operator, never silent (FR-002).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;The three-way rule (D-A3).&lt;/strong&gt; “Newer” is a base/target/lane comparison, never
mtime: the target wins a path iff the target diverged from
&lt;code dir=&quot;auto&quot;&gt;merge-base(target, source)&lt;/code&gt; while the lane copy is base-or-ancestor (the target
evolved, the lane is stale). When both sides advanced the same path, the tiebreak
is the last-commit committer-date, with the target winning on a strictly-later
date &lt;strong&gt;or a tie&lt;/strong&gt; (the conservative “do not clobber the target” default). This is
topology-safe by construction: on &lt;code dir=&quot;auto&quot;&gt;LANES&lt;/code&gt; (lane ≠ base,
target = base) the lane correctly wins with no special case; a &lt;code dir=&quot;auto&quot;&gt;single_branch&lt;/code&gt;
mission has no lane branch, so there is no lane side to compare.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Note for epic #2907 (classifier-driven conflict taxonomy).&lt;/strong&gt; D-A1 drives squash
conflict resolution off &lt;code dir=&quot;auto&quot;&gt;mission_runtime.kind_for_mission_file&lt;/code&gt; — the #2709
“target-newer canonical state is &lt;em&gt;reconciled&lt;/em&gt;, not &lt;em&gt;replaced&lt;/em&gt;” principle extended
from meta &lt;strong&gt;fields&lt;/strong&gt; (the &lt;code dir=&quot;auto&quot;&gt;_TARGET_AUTHORITATIVE_META_FIELDS&lt;/code&gt; driver) to
primary-artifact-kind &lt;strong&gt;files&lt;/strong&gt;. This is the #2709 → #3942 lineage. It also
establishes the disposition of the dead module
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/conflict_resolver.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;ConflictType&lt;/code&gt; /
&lt;code dir=&quot;auto&quot;&gt;classify_conflict&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;resolve_owned_conflicts&lt;/code&gt;): it is a &lt;strong&gt;competing&lt;/strong&gt; conflict
taxonomy, reachable only through the &lt;code dir=&quot;auto&quot;&gt;merge/__init__.py&lt;/code&gt; re-export (the live
auto-rebase classifier is the different module &lt;code dir=&quot;auto&quot;&gt;merge/conflict_classifier.py&lt;/code&gt;).
The #3942 fix deliberately did &lt;strong&gt;not&lt;/strong&gt; wire into it. It should be &lt;strong&gt;retired&lt;/strong&gt; as
part of #2907’s taxonomy consolidation, so the classifier authority stays single.&lt;/p&gt;
&lt;h2 id=&quot;track-b--the-read-seam-which-surface-a-reader-trusts&quot;&gt;Track B — the read seam (which surface a reader trusts)&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Seam:&lt;/strong&gt; the &lt;code dir=&quot;auto&quot;&gt;merged_at&lt;/code&gt; completion marker, written by
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/consolidation/baseline.py::record_baseline_merge_commit&lt;/code&gt;, and consumed by
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/lifecycle.py::is_mission_merged&lt;/code&gt;, which the surface
resolver’s primary re-anchor (&lt;code dir=&quot;auto&quot;&gt;coordination/surface_resolver.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;_primary_mission_is_completed&lt;/code&gt;) and the runtime bootstrap short-circuit
(&lt;code dir=&quot;auto&quot;&gt;runtime_bridge.py&lt;/code&gt;) gate on.&lt;/p&gt;
&lt;p&gt;When a mission merges, a diverged coordination husk can survive. The primary-wins
guard is supposed to re-anchor reads to the PRIMARY surface once the mission is
merged — but it gates on &lt;code dir=&quot;auto&quot;&gt;meta[&quot;merged_at&quot;]&lt;/code&gt;, whose production writer had been
deleted in #2258 (&lt;code dir=&quot;auto&quot;&gt;6f46cf6bb6&lt;/code&gt;) and never re-added. The guard was &lt;strong&gt;dormant&lt;/strong&gt;, so
the divergence resurfaced: retrospect and doctor (which now share
&lt;code dir=&quot;auto&quot;&gt;resolve_status_surface&lt;/code&gt;) could still read the stale husk.&lt;/p&gt;
&lt;p&gt;The fix (D-B1) is &lt;strong&gt;one coupled change&lt;/strong&gt;:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Restore the writer&lt;/strong&gt; for &lt;code dir=&quot;auto&quot;&gt;meta[&quot;merged_at&quot;]&lt;/code&gt; (a UTC ISO datetime; plus
&lt;code dir=&quot;auto&quot;&gt;merged_commit&lt;/code&gt; for provenance) as a &lt;strong&gt;sibling of&lt;/strong&gt; the baseline-commit writer
in &lt;code dir=&quot;auto&quot;&gt;merge/baseline.py&lt;/code&gt; — the meta-write authority — &lt;em&gt;not&lt;/em&gt; in
&lt;code dir=&quot;auto&quot;&gt;done_bookkeeping.py&lt;/code&gt; (which writes nothing to &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;; a write there would
be a boundary leak). The executor is untouched. The driver’s
&lt;code dir=&quot;auto&quot;&gt;_TARGET_AUTHORITATIVE_META_FIELDS&lt;/code&gt; already declares &lt;code dir=&quot;auto&quot;&gt;merged_at&lt;/code&gt; as &lt;em&gt;the&lt;/em&gt;
marker, so this is canonical reuse, not a new authority.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Make the guard reopen-aware.&lt;/strong&gt; Because nothing today clears &lt;code dir=&quot;auto&quot;&gt;merged_at&lt;/code&gt; on
reopen and &lt;code dir=&quot;auto&quot;&gt;is_mission_merged&lt;/code&gt; was presence-only, simply restoring the writer
would make a &lt;em&gt;reopened&lt;/em&gt; mission read as merged forever across three consumers.
So &lt;code dir=&quot;auto&quot;&gt;is_mission_merged&lt;/code&gt; is now event-sourced: a mission is merged iff
&lt;code dir=&quot;auto&quot;&gt;merged_at&lt;/code&gt; is present &lt;strong&gt;AND&lt;/strong&gt; no &lt;code dir=&quot;auto&quot;&gt;MissionReopened&lt;/code&gt; event postdates it (reusing
the adjacent &lt;code dir=&quot;auto&quot;&gt;_last_reopen_at&lt;/code&gt; machinery — no meta-mutating clearer of its own).
A re-merge re-stamps a fresh &lt;code dir=&quot;auto&quot;&gt;merged_at&lt;/code&gt; that postdates the re-open, restoring
&lt;code dir=&quot;auto&quot;&gt;True&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Note for epic #2160 (single canonical post-merge authority).&lt;/strong&gt; D-B1 chose
&lt;strong&gt;“override the stale husk on primary”&lt;/strong&gt; over &lt;strong&gt;“freshen the husk”&lt;/strong&gt;. This keeps
the single canonical post-merge authority on the PRIMARY surface — the husk is
never re-blessed as a second read home; the guard re-anchors past it by data.
This is a &lt;strong&gt;coord-authority decision&lt;/strong&gt; for the #2160 owner to ratify.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;#4091 disposition (D-B2 — separable, verified-already-fixed).&lt;/strong&gt; #4090 is fixed
by the marker alone. #4091 is a &lt;em&gt;distinct&lt;/em&gt; measure mismatch: &lt;code dir=&quot;auto&quot;&gt;event_count&lt;/code&gt; is by
definition the count of unique &lt;code dir=&quot;auto&quot;&gt;WPStatusChanged&lt;/code&gt; transition events, which is
&lt;code dir=&quot;auto&quot;&gt;&amp;#x3C; len(status.events.jsonl)&lt;/code&gt; (annotations, lifecycle, and decision events are not
transitions). &lt;code dir=&quot;auto&quot;&gt;_project_status_bookkeeping_to_target&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;merge/bookkeeping_projection.py&lt;/code&gt;) already unions and re-reduces, and its union
branch runs only under a coord husk. WP05 stood up a &lt;strong&gt;red-first repro on a coord
fixture&lt;/strong&gt; and confirmed &lt;code dir=&quot;auto&quot;&gt;event_count&lt;/code&gt; is already correct on HEAD; #4091 is
therefore &lt;strong&gt;verify-and-close&lt;/strong&gt;, guarded by a characterization test (building a fix
test on already-green code would be the green-regression trap).&lt;/p&gt;
&lt;h2 id=&quot;shared-vs-disjoint-verdict&quot;&gt;Shared-vs-disjoint verdict&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Verdict: disjoint code seams, one thematic spine.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The two tracks are &lt;strong&gt;file-disjoint&lt;/strong&gt; and were implemented in parallel:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Track A writes: &lt;code dir=&quot;auto&quot;&gt;lanes/merge.py&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;merge/planning_recency.py&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Track B reads: &lt;code dir=&quot;auto&quot;&gt;merge/baseline.py&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;status/lifecycle.py&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;There is &lt;strong&gt;no single unifying code seam&lt;/strong&gt; that both fixes route through — the
squad’s finding, borne out by implementation. The write half amends a git commit;
the read half event-sources a lifecycle predicate. They share no call path.&lt;/p&gt;
&lt;p&gt;What they &lt;strong&gt;do&lt;/strong&gt; share is the &lt;strong&gt;partition doctrine and its classifier&lt;/strong&gt;. Both are
answers to “what is authoritative post-merge, and on which surface”:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Write half&lt;/strong&gt; — &lt;em&gt;which bytes win per artifact&lt;/em&gt;: PRIMARY-partition planning
files are target-authoritative when the target is newer; driver-covered
bookkeeping keeps its reconcilers.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Read half&lt;/strong&gt; — &lt;em&gt;which surface a reader trusts&lt;/em&gt;: once merged, reads re-anchor to
the PRIMARY surface; the diverged coord husk is overridden, not trusted.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;mission_runtime.kind_for_mission_file&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;is_primary_artifact_kind&lt;/code&gt; is the
&lt;strong&gt;candidate shared spine&lt;/strong&gt;: the same classifier that says a path is
PRIMARY-partition-authoritative is what tells Track A not to overwrite it and
Track B not to read a lane as its post-merge home. The spine is &lt;strong&gt;thematic and
doctrinal&lt;/strong&gt;, not a shared runtime seam. Calling the tracks “the same bug” would
overclaim; calling them unrelated would miss that a single partition authority
governs both. They are &lt;strong&gt;genuinely disjoint-but-thematically-shared&lt;/strong&gt;, unified by
the classifier + partition doctrine rather than by code.&lt;/p&gt;
&lt;h2 id=&quot;provenance&quot;&gt;Provenance&lt;/h2&gt;
&lt;p&gt;This page is the cross-track synthesis (FR-009) for mission
&lt;code dir=&quot;auto&quot;&gt;post-merge-partition-integrity-01M2FQ80&lt;/code&gt;: it maps the two tracks the mission delivered
(Track A, #3942, and Track B, #4090) onto one question and records the epic-owner notes and
the shared-vs-disjoint verdict the review squad reached.&lt;/p&gt;
&lt;h2 id=&quot;traceability&quot;&gt;Traceability&lt;/h2&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Requirement&lt;/th&gt;&lt;th&gt;Delivered by&lt;/th&gt;&lt;th&gt;Seam&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;FR-001/FR-002 (write authority + divergence report)&lt;/td&gt;&lt;td&gt;Track A / WP01–WP02 (#3942)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;lanes/merge.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;merge/planning_recency.py&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;FR-003 (preserve driver reconciliation)&lt;/td&gt;&lt;td&gt;Track A (unchanged &lt;code dir=&quot;auto&quot;&gt;_MERGE_DRIVERS&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;driver registry / gate artifacts&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;FR-004+ (read authority)&lt;/td&gt;&lt;td&gt;Track B / WP03–WP04 (#4090)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;merge/baseline.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status/lifecycle.py&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;#4091 verify-and-close&lt;/td&gt;&lt;td&gt;WP05 (D-B2)&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;merge/bookkeeping_projection.py&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;FR-009 (this synthesis)&lt;/td&gt;&lt;td&gt;WP06&lt;/td&gt;&lt;td&gt;this document&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Epic advances recorded here: &lt;strong&gt;#2907&lt;/strong&gt; (classifier-driven taxonomy; retire dead
&lt;code dir=&quot;auto&quot;&gt;conflict_resolver.py&lt;/code&gt;), &lt;strong&gt;#2160&lt;/strong&gt; (husk-override authority note to ratify).&lt;/p&gt;</content>
</entry>
