<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/reference/optional-lamport-clock-consumers/">
  <id>https://docs.spec-kitty.ai/development/reference/optional-lamport-clock-consumers/</id>
  <title>Consumers of the optional Lamport clock</title>
  <updated>2026-10-31T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/reference/optional-lamport-clock-consumers/"/>
  <summary>Every core site that reads or writes Event.lamport_clock or the spec-kitty-events ordering keys, with a verdict and the test that pins it, following spec-kitty-events 11.0.</summary>
  <content type="html">&lt;span id=&quot;consumers-of-the-optional-lamport-clock&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; 11.0.0 made &lt;code dir=&quot;auto&quot;&gt;Event.lamport_clock&lt;/code&gt; optional and changed the status
ordering key. This page records what core does with both, so the next contract move does
not have to re-run the audit from scratch. Tracking issue: #6414 (parent epic #6411).&lt;/p&gt;
&lt;h2 id=&quot;the-contract-this-page-is-written-against&quot;&gt;The contract this page is written against&lt;/h2&gt;
&lt;p&gt;Pinned floor: &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&gt;=11.3.0,&amp;#x3C;12&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;). Read from the installed
package, not from the issue that requested the audit:&lt;/p&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Surface&lt;/th&gt;&lt;th&gt;Behaviour&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events/models.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;Event.lamport_clock&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;Optional[int]&lt;/code&gt;. The field description says it plainly: “An envelope without it is unclocked and orders &lt;strong&gt;before&lt;/strong&gt; clocked ones.” &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; is a &lt;em&gt;real&lt;/em&gt; clocked position, not “no clock”.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events/ordering.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;canonical_order_key&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;(1 if clocked else 0, clock or 0, utc_timestamp_iso, event_id)&lt;/code&gt; — the one mixed-stream key. &lt;code dir=&quot;auto&quot;&gt;node_order_key&lt;/code&gt; is the storage-adapter sibling keyed on &lt;code dir=&quot;auto&quot;&gt;(clocked, clock, node_id, event_id)&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events/status.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;status_event_sort_key&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Delegates to &lt;code dir=&quot;auto&quot;&gt;canonical_order_key&lt;/code&gt;. It is a &lt;strong&gt;4-tuple&lt;/strong&gt;, not the 3-tuple older integrations unpack.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events/merge.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;work_replay.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; raises on an unclocked event; &lt;code dir=&quot;auto&quot;&gt;work_replay&lt;/code&gt; refuses one (&lt;code dir=&quot;auto&quot;&gt;work replay requires lamport_clock&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events/status.py&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;reduce_status_events&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The only consumer that sorts with the 4-tuple key &lt;em&gt;and&lt;/em&gt; groups by &lt;code dir=&quot;auto&quot;&gt;(wp_id, lamport_clock)&lt;/code&gt;, treating an unclocked event as its own singleton group.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events/strict.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The strict 14-key envelope requires every key present, nullable ones as an explicit &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;strong&gt;Direction note.&lt;/strong&gt; The issue that prompted this audit states that unclocked envelopes
sort &lt;em&gt;after&lt;/em&gt; clocked ones. The released contract sorts them &lt;em&gt;before&lt;/em&gt;: the leading
component is &lt;code dir=&quot;auto&quot;&gt;1&lt;/code&gt; only when the event is clocked. Where the two disagree, this page and the
code follow the installed package.&lt;/p&gt;
&lt;h2 id=&quot;what-core-does-not-do&quot;&gt;What core does not do&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;No caller of the ordering surface.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;status_event_sort_key&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;canonical_order_key&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;node_order_key&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;total_order_key&lt;/code&gt; have no call site in &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;; the only mention of
&lt;code dir=&quot;auto&quot;&gt;canonical_order_key&lt;/code&gt; in core is the migration docstring that explains &lt;em&gt;why&lt;/em&gt; the
migration emits an unclocked row (below). The Java read API names
&lt;code dir=&quot;auto&quot;&gt;status_event_sort_key&lt;/code&gt; in a comment recording that it is not ported.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;No &lt;code dir=&quot;auto&quot;&gt;merge&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;work_replay&lt;/code&gt; use.&lt;/strong&gt; Core never imports &lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.merge&lt;/code&gt; or
&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.work_replay&lt;/code&gt;, so the two functions that &lt;em&gt;reject&lt;/em&gt; unclocked input are
unreachable from the CLI.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The CLI’s lane readers are wall-clock.&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt; and the lane-state
reads fold events through the diary reducer (&lt;code dir=&quot;auto&quot;&gt;spec_kitty_events.diary.reduce_parsed&lt;/code&gt;),
ordered by &lt;code dir=&quot;auto&quot;&gt;(at, event_id)&lt;/code&gt;. Room to make the status log Lamport-primary belongs to
#6609 (parked post-GA) and is deliberately out of scope here.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;consumers-and-why-each-one-is-safe&quot;&gt;Consumers, and why each one is safe&lt;/h2&gt;
&lt;p&gt;Proofs live in &lt;code dir=&quot;auto&quot;&gt;tests/status/test_optional_lamport_clock_consumers.py&lt;/code&gt; unless a path is
named.&lt;/p&gt;







































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Site&lt;/th&gt;&lt;th&gt;Kind&lt;/th&gt;&lt;th&gt;Verdict&lt;/th&gt;&lt;th&gt;Proof&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/lifecycle_events.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Producer (&lt;code dir=&quot;auto&quot;&gt;_build_envelope&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Already unclocked. The live lifecycle appender writes no &lt;code dir=&quot;auto&quot;&gt;lamport_clock&lt;/code&gt; key at all, which under 11.x reads as unclocked — the contract’s “no causal order recorded”.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;test_live_lifecycle_envelope_carries_no_clock&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/migrate_lifecycle_envelope.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Producer (upgrade migration)&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Was the defect.&lt;/strong&gt; It stamped &lt;code dir=&quot;auto&quot;&gt;lamport_clock: 0&lt;/code&gt;, a clocked position the legacy row never recorded, so the row sorted after every never-migrated row of the same log. It now writes an explicit &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;. The live appender omits the key while the migration writes &lt;code dir=&quot;auto&quot;&gt;&quot;lamport_clock&quot;: null&lt;/code&gt;; both mean unclocked under &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; &gt;= 11. The migration writes the key explicitly because &lt;code dir=&quot;auto&quot;&gt;lamport_clock&lt;/code&gt; is one of the strict-envelope keys it synthesizes (&lt;code dir=&quot;auto&quot;&gt;_SYNTHESIZED_KEYS&lt;/code&gt;), and its re-run check treats a row as already migrated only when every synthesized key is present. See &lt;a href=&quot;/changelog/CHANGELOG/&quot;&gt;the changelog&lt;/a&gt;.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tests/status/test_optional_lamport_clock_migration.py&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/reducer.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reader (&lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;reduce&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Unaffected. &lt;code dir=&quot;auto&quot;&gt;materialize_snapshot&lt;/code&gt; reduces through the diary reducer, which orders by &lt;code dir=&quot;auto&quot;&gt;(at, event_id)&lt;/code&gt; and never reads a clock; &lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt; has no &lt;code dir=&quot;auto&quot;&gt;lamport_clock&lt;/code&gt; field, so a foreign clock on a row is ignored rather than promoted.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;test_mixed_stream_materializes_identically&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/event_log_merge.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reader/rewriter (&lt;code dir=&quot;auto&quot;&gt;merge_event_payloads&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Unaffected. It orders by &lt;code dir=&quot;auto&quot;&gt;(at or timestamp, event_id)&lt;/code&gt; and keeps whole row dicts, so it neither reinterprets nor drops a clock.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;test_merge_event_payloads_ignores_clock&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/status/store.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reader (&lt;code dir=&quot;auto&quot;&gt;read_events&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;read_events_raw&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Unaffected. Rows become &lt;code dir=&quot;auto&quot;&gt;StatusEvent&lt;/code&gt;, which has no clock field; raw rows are handed to the dependency unchanged.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;test_mixed_stream_materializes_identically&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/state/contract.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;On-disk path inventory&lt;/td&gt;&lt;td&gt;Unaffected. The &lt;code dir=&quot;auto&quot;&gt;lamport_clock&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;legacy_lamport_clock&lt;/code&gt; surfaces it declares are the retired hosted-sync files &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/clock.json&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty/events/lamport_clock.json&lt;/code&gt; (#114), not the envelope field.&lt;/td&gt;&lt;td&gt;None: a path inventory, not behaviour; read &lt;code dir=&quot;auto&quot;&gt;STATE_SURFACES&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/lifecycle_events.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Producer (separate local clock)&lt;/td&gt;&lt;td&gt;Unaffected. The retrospective log’s own &lt;code dir=&quot;auto&quot;&gt;lamport&lt;/code&gt; field (default &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt;) is not &lt;code dir=&quot;auto&quot;&gt;Event.lamport_clock&lt;/code&gt;; &lt;code dir=&quot;auto&quot;&gt;_next_lamport&lt;/code&gt; already guards with &lt;code dir=&quot;auto&quot;&gt;isinstance(lp, int)&lt;/code&gt;.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;test_retrospective_clock_reads_tolerate_null&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/retrospective/summary.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Reader (separate local clock)&lt;/td&gt;&lt;td&gt;Handles &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt;. Every read is &lt;code dir=&quot;auto&quot;&gt;obj.get(&quot;lamport&quot;, 0)&lt;/code&gt; followed by an &lt;code dir=&quot;auto&quot;&gt;isinstance(..., int)&lt;/code&gt; guard, so an explicit &lt;code dir=&quot;auto&quot;&gt;null&lt;/code&gt; behaves as absent.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;test_retrospective_clock_reads_tolerate_null&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/decisions/models.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;decisions/service.py&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;orchestrator_api/decision_verbs.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Response field &lt;code dir=&quot;auto&quot;&gt;event_lamport&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Unaffected. Typed `int&lt;/td&gt;&lt;td&gt;None`, only serialized, never compared or unpacked.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;tests/_factories/coord_mission.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Test probe (&lt;code dir=&quot;auto&quot;&gt;_row_lamport&lt;/code&gt;)&lt;/td&gt;&lt;td&gt;Already tolerant. Returns &lt;code dir=&quot;auto&quot;&gt;None&lt;/code&gt; for an absent or non-integer clock.&lt;/td&gt;&lt;td&gt;None: a test helper, not core behaviour&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;residual&quot;&gt;Residual&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A project that ran an older release of the migration already carries
&lt;code dir=&quot;auto&quot;&gt;lamport_clock: 0&lt;/code&gt; rows. The migration deliberately does &lt;strong&gt;not&lt;/strong&gt; rewrite them: re-running
it must stay a byte-identical no-op on an already-migrated file, and no core reader uses
the key for ordering. A future Lamport-primary reader (#6609) has to decide what an
already-stamped &lt;code dir=&quot;auto&quot;&gt;0&lt;/code&gt; means; #6414 does not.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;keeping-this-page-honest&quot;&gt;Keeping this page honest&lt;/h2&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;tests/status/test_optional_lamport_clock_consumers.py&lt;/code&gt; scans &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; for
&lt;code dir=&quot;auto&quot;&gt;lamport_clock&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;status_event_sort_key&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;canonical_order_key&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;node_order_key&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;total_order_key&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;work_replay&lt;/code&gt;. Every file it finds must appear in the table above; a
new consumer therefore fails the suite until it is audited and added here. A moved line
does not fail it.&lt;/p&gt;</content>
</entry>
