<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-09-3-event-log-merge-semantics/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-09-3-event-log-merge-semantics/</id>
  <title>Event-Log Merge Semantics for Concurrent Agents</title>
  <updated>2026-10-22T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-09-3-event-log-merge-semantics/"/>
  <summary>Reconciles divergent status logs by concatenating, deduplicating, and replaying events with rollback-aware precedence, so a reviewer&apos;s rejection is never overwritten.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;Multiple agents — human developers, AI agents (Claude, Codex), and CI systems — may concurrently modify WP status in different git branches. Each branch contains its own copy of the canonical event log (ADR 2026-02-09-1). When branches merge, the event logs must be reconciled into a single consistent state.&lt;/p&gt;
&lt;p&gt;The current system has no formal merge semantics for status. A naive “most done wins” strategy can override a valid review rollback. For example: Branch A’s reviewer moves a WP from &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; (changes requested), while Branch B concurrently moves the same WP from &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;. Naive merge: “done” wins — &lt;strong&gt;but the reviewer’s rollback is lost&lt;/strong&gt;.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Deterministic merge&lt;/strong&gt; — Same inputs must always produce the same merged state&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reviewer authority&lt;/strong&gt; — Review rollback must outrank concurrent forward progress&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Invalid transition detection&lt;/strong&gt; — Post-merge validation must flag illegal state sequences&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Agent-count agnostic&lt;/strong&gt; — Must scale from 2 branches to 20+&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Audit trail preservation&lt;/strong&gt; — All events from all branches must be retained&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; Last-writer-wins by timestamp&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; Monotonic “most-advanced-lane-wins”&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; Concatenate-dedupe-sort-reduce with rollback-aware precedence&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Manual conflict resolution (human decides)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Option 3: Concatenate-dedupe-sort-reduce with rollback-aware precedence”, because it provides deterministic merges, preserves reviewer authority, catches invalid transitions, and scales to any number of concurrent agents.&lt;/p&gt;
&lt;h3 id=&quot;implementation&quot;&gt;Implementation&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;4-step merge algorithm:&lt;/strong&gt;&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Concatenate&lt;/strong&gt;: Combine event logs from both branches into a single stream&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Deduplicate&lt;/strong&gt;: Remove duplicate events by &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt; (same event from common ancestor appears in both)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Sort&lt;/strong&gt;: Order by deterministic key — primary: &lt;code dir=&quot;auto&quot;&gt;logical_clock&lt;/code&gt; (Lamport), secondary: &lt;code dir=&quot;auto&quot;&gt;at&lt;/code&gt; (UTC timestamp), tertiary: &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt; (ULID, lexicographic tiebreaker)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reduce&lt;/strong&gt;: Replay sorted events through the state machine (ADR 2026-02-09-2) to compute current state; invalid transitions are flagged&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;strong&gt;Rollback-aware precedence:&lt;/strong&gt; An explicit reviewer rollback (&lt;code dir=&quot;auto&quot;&gt;for_review → in_progress&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;review_ref&lt;/code&gt; populated) outranks a concurrent forward progression (&lt;code dir=&quot;auto&quot;&gt;for_review → done&lt;/code&gt; without &lt;code dir=&quot;auto&quot;&gt;review_ref&lt;/code&gt;). This is a semantic rule: review feedback is authoritative.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Invalid transition handling:&lt;/strong&gt; Events producing invalid transitions after merge are flagged as validation errors, reported in CI output, and never silently ignored.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Explicit rejection:&lt;/strong&gt; The monotonic “most-advanced-lane-wins” strategy is explicitly rejected — PRD Section 2 identifies this as a failure mode, not a solution.&lt;/p&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Deterministic — same inputs always produce the same merged state, regardless of merge order&lt;/li&gt;
&lt;li&gt;Reviewer authority preserved — explicit rollback with &lt;code dir=&quot;auto&quot;&gt;review_ref&lt;/code&gt; outranks concurrent forward progress&lt;/li&gt;
&lt;li&gt;Invalid transitions caught — post-merge validation flags illegal state sequences in CI&lt;/li&gt;
&lt;li&gt;Scales to any number of agents — algorithm is agent-count-agnostic&lt;/li&gt;
&lt;li&gt;Audit trail preserved — all events from all branches retained in the merged log&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Algorithm complexity — concatenate-dedupe-sort-reduce is more complex than simple last-write-wins&lt;/li&gt;
&lt;li&gt;Requires sortable keys — all events must have logical clock or timestamp&lt;/li&gt;
&lt;li&gt;Post-merge validation adds CI time (linear in event count)&lt;/li&gt;
&lt;li&gt;Two conflicting forced transitions may still require manual resolution&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Sort is O(n log n), reduce is O(n) — manageable for typical event log sizes (&amp;#x3C; 1000 events per feature)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status emit&lt;/code&gt; ticks the logical clock on every event, so sortable keys are always present&lt;/li&gt;
&lt;li&gt;Manual fallback exists for truly unresolvable conflicts (the exception, not the rule)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;CI check: every merge triggers transition validity scan against the state machine&lt;/li&gt;
&lt;li&gt;CI check: materialized state must match reducer output&lt;/li&gt;
&lt;li&gt;Edge case: conflicting forced transitions flag for human resolution&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;last-writer-wins-by-timestamp&quot;&gt;Last-writer-wins by timestamp&lt;/h3&gt;
&lt;p&gt;When events conflict, the event with the latest timestamp wins. No semantic awareness.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Simple to implement — compare timestamps, keep latest&lt;/li&gt;
&lt;li&gt;No need to understand event semantics&lt;/li&gt;
&lt;li&gt;Works for any event type without special cases&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Timestamps can be skewed across machines (clock drift, timezone errors)&lt;/li&gt;
&lt;li&gt;Race conditions produce non-deterministic results&lt;/li&gt;
&lt;li&gt;No semantic awareness — review rollback and forward completion treated identically&lt;/li&gt;
&lt;li&gt;Reviewer authority lost when completion timestamp is later&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;monotonic-most-advanced-lane-wins&quot;&gt;Monotonic “most-advanced-lane-wins”&lt;/h3&gt;
&lt;p&gt;The event moving the WP to a “more advanced” lane wins. Lane ordering: planned &amp;#x3C; claimed &amp;#x3C; in_progress &amp;#x3C; for_review &amp;#x3C; done.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Deterministic — lane ordering is fixed&lt;/li&gt;
&lt;li&gt;Matches intuition that work should move toward completion&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;This IS the failure mode identified in PRD Section 2&lt;/strong&gt; — “monotonic conflict resolution: ‘most done wins’ can override valid review rollback”&lt;/li&gt;
&lt;li&gt;Destroys reviewer authority&lt;/li&gt;
&lt;li&gt;Hides regressions — quality issues surfaced in review are overwritten by forward progress&lt;/li&gt;
&lt;li&gt;Cannot represent legitimate state reversals&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;manual-conflict-resolution-human-decides&quot;&gt;Manual conflict resolution (human decides)&lt;/h3&gt;
&lt;p&gt;Present event log conflicts to a human for manual resolution, similar to git merge conflict markers.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Always correct when the human is attentive&lt;/li&gt;
&lt;li&gt;Handles edge cases no automated rule can cover&lt;/li&gt;
&lt;li&gt;Familiar pattern for developers&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Blocks CI and automation — merge cannot complete without human intervention&lt;/li&gt;
&lt;li&gt;Doesn’t scale to multi-agent workflows with frequent merges&lt;/li&gt;
&lt;li&gt;Requires human to understand event log semantics (high cognitive load)&lt;/li&gt;
&lt;li&gt;Introduces delays in integration velocity&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;reconciliation-note--terminus-mergereconciliation-gate-terminus-merge-integrity-2026-09&quot;&gt;Reconciliation note — terminus merge/reconciliation gate (terminus-merge-integrity, 2026-09)&lt;/h2&gt;
&lt;p&gt;The terminus reconciliation gate (&lt;code dir=&quot;auto&quot;&gt;merge/reconciliation.py::MergeOutcomeVerifier&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;build_approved_wp_set&lt;/code&gt;, mission &lt;em&gt;terminus-merge-integrity&lt;/em&gt;) sources its approved/canceled &lt;strong&gt;WP-membership&lt;/strong&gt; claim through the &lt;strong&gt;Lamport&lt;/strong&gt; reduction wrapper this ADR mandates (&lt;code dir=&quot;auto&quot;&gt;status.reducer.materialize&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;reduce_shared_state&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status/reducer.py:371&lt;/code&gt;) — never the wall-clock LWW &lt;code dir=&quot;auto&quot;&gt;reduce_parsed&lt;/code&gt;. This is what makes the gate’s own claim honor the reviewer-authority / causal-precedence guarantee above: a wall-clock-later approval cannot green-wash a causally-earlier committed rejection &lt;em&gt;in the gate’s claim&lt;/em&gt;.&lt;/p&gt;
&lt;p&gt;This ADR’s chosen algorithm (Option 3, Lamport-primary) is therefore honored by the &lt;strong&gt;Lamport&lt;/strong&gt; reducer only. A &lt;strong&gt;second&lt;/strong&gt;, non-conformant reducer still ships in the codebase — the wall-clock LWW &lt;code dir=&quot;auto&quot;&gt;reduce_parsed&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.diary&lt;/code&gt;, sorts &lt;code dir=&quot;auto&quot;&gt;(at, event_id)&lt;/code&gt;) — and its split-brain (a later wall-clock event overriding a causally-earlier one, exactly the “Last-writer-wins by timestamp” failure mode this ADR &lt;strong&gt;rejected&lt;/strong&gt;) is &lt;strong&gt;not&lt;/strong&gt; resolved by the terminus-merge-integrity mission. It is tracked as a &lt;strong&gt;separate, open&lt;/strong&gt; sibling mission, &lt;strong&gt;#4990&lt;/strong&gt;, which requires a &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events&lt;/code&gt; change (the shared-package boundary / C-002 keeps it out of the terminus scope). Until #4990 lands, do not treat this ADR as fully enforced across &lt;em&gt;both&lt;/em&gt; reducers — only the Lamport &lt;code dir=&quot;auto&quot;&gt;materialize&lt;/code&gt; path and the terminus gate that consumes it conform.&lt;/p&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Related ADRs:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;ADR 2026-02-09-1 (Canonical WP Status Model) — event log format this algorithm operates on&lt;/li&gt;
&lt;li&gt;ADR 2026-02-09-2 (WP Lifecycle State Machine) — state machine used for the reduce step&lt;/li&gt;
&lt;li&gt;ADR 2026-02-09-4 (Cross-Repo Evidence Completion) — reconciliation events appended to the same log&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;References:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;CRDTs and Convergent Replicated Data Types — &lt;a href=&quot;https://crdt.tech/&quot;&gt;https://crdt.tech/&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Lamport Clocks — &lt;a href=&quot;https://lamport.azurewebsites.net/pubs/time-clocks.pdf&quot;&gt;https://lamport.azurewebsites.net/pubs/time-clocks.pdf&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;Git Merge Strategies — &lt;a href=&quot;https://git-scm.com/docs/merge-strategies&quot;&gt;https://git-scm.com/docs/merge-strategies&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;PRD: Feature Status State Model Remediation (Sections 2, 9, 12.1.2, 12.1.4)&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-10-22-accepted-the-ordering-is-wall-clock-now-lamport-primary-is-a-post-ga-direction&quot;&gt;Amendment 2026-10-22 (Accepted): the ordering is wall clock now; Lamport-primary is a post-GA direction&lt;/h2&gt;
&lt;p&gt;Operator ruling, 2026-10-22: amend this record to what the code does, and pursue Lamport-primary ordering after 4.0.0 GA (#6609).&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Step 3 (Sort), as implemented.&lt;/strong&gt; The CLI writes no &lt;code dir=&quot;auto&quot;&gt;logical_clock&lt;/code&gt; on status rows, so the “primary: &lt;code dir=&quot;auto&quot;&gt;logical_clock&lt;/code&gt;” key does not apply. Every CLI status read reduces through the &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; wall-clock fold, &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.diary.reduce_parsed&lt;/code&gt;:
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;status.reducer.reduce&lt;/code&gt; calls it directly (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/reducer.py:205&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt; reaches it through &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.status.reduce&lt;/code&gt;, a re-export of &lt;code dir=&quot;auto&quot;&gt;diary.reduce&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;:401&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;It orders transitions by the writer’s &lt;code dir=&quot;auto&quot;&gt;at&lt;/code&gt;, then by &lt;code dir=&quot;auto&quot;&gt;event_id&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The ordering decision for 4.0.0&lt;/strong&gt; is that wall-clock order, together with two rules:
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;From-lane continuity:&lt;/strong&gt; a stale approval cannot override a committed rejection (#4990, &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; 10.4.0).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The approved-departure lift:&lt;/strong&gt; a non-seed departure from &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; sorts after the approval it followed (#4941, 10.5.1).&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Reviewer-authority precedence is kept&lt;/strong&gt;, and so are the concatenate, deduplicate and reduce steps.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Residual, named:&lt;/strong&gt; a non-approval transition minted on a clock behind the event it follows still sorts before that event.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The Neutral consequence “&lt;code dir=&quot;auto&quot;&gt;status emit&lt;/code&gt; ticks the logical clock on every event”&lt;/strong&gt; is not true of the CLI and is withdrawn.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The 2026-09 reconciliation note above is superseded.&lt;/strong&gt; The consolidation gate reads WP membership through &lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt;, which is the same wall-clock fold as &lt;code dir=&quot;auto&quot;&gt;reduce&lt;/code&gt;. There is no separate Lamport wrapper, and #4990 is closed.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Lamport-primary ordering&lt;/strong&gt; (a clock stamped on every row by the canonical writer, a clock-first reducer in &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt;, re-pinned goldens) is the post-GA direction in #6609. It needs its own ADR before it is built. #6117 decision 1, which recommends Lamport with a &lt;code dir=&quot;auto&quot;&gt;(time, id)&lt;/code&gt; tiebreak, is held to that direction and does not apply to 4.0.0.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
