Ledger and lims now both hand-write a base-version precondition check, with diverging shapes — extract a shared vocabulary or document the divergence

[Yaraslaut]

The re-entry trigger has fired

This issue was filed deliberately parked-shaped, with an explicit re-entry
condition: "A second rung independently hand-writes a base-version (or
equivalent precondition) comparison against a queued write." That condition
is now satisfied, and by an implementation that predates this issue's own
filing:

• examples/ledger (rung 5), RuleModel::execute(UpdateRule)
  (examples/ledger/src/models/rule_model.cpp:88-96) and
  UpdateRule::expectedVersion
  (examples/ledger/include/ledger/dto/rule_dto.hpp:26-39): an optional
  client-supplied version compared against the stored row's version, refusing
  with a typed VersionConflict on mismatch and applying unconditionally when
  disengaged. Landed via commit 75a485a2, merged to master via PR ledger: rung 5 of the application ladder (Tasks 1-16 of 26) #132 on
  2026-08-21 — two days before this issue was even filed
  (2026-08-23T21:16). The original "one rung, unmerged" premise was already
  stale at the moment of filing.
• examples/lims (rung 6), SampleModel::execute()
  (examples/lims/src/models/sample_model.cpp:586-646) and
  QueuedCapture::baseVersion / ConflictInfo::{baseVersion,serverVersion}
  (examples/lims/include/lims/dto/offline_dto.hpp:125-189): the mechanism
  this issue originally documented, at the time via unmerged PR lims: rung 6 — a LIMS, and the forms subsystem at full depth #177. That PR
  has since merged, so the "unmerged" half of the original premise is
  doubly gone.

Both are genuinely independent implementations, not copies of a shared idea:
ledger's version pinning traces to #144 / SYNC-BENCHMARK.md §10 (Scenario
B), with no reference to lims or #203; lims's traces to its own README's
self-posed question. Two different authors-in-time, two different shapes,
same underlying idea — and that divergence is itself the signal that
justifies extracting a real vocabulary now rather than continuing to wait:

	ledger UpdateRule	lims SampleModel
precondition field	expectedVersion (optional int32, std::nullopt = unconditional)	baseVersion (required SampleVersion)
granularity	whole row (one rule)	whole entity (one sample)
on mismatch	throws typed VersionConflict	returns a ConflictInfo{baseVersion, serverVersion} outcome, no throw
ledger/table	none — checked inline against the live row	separate OfflineConflictRecord conflict table + ResolveConflict actions

Scope check: still a 2-occurrence pattern, not a 6-occurrence one

A broad sweep of examples/*/include/*/{models,dto}/** and
examples/*/src/models/** for baseVersion|expectedVersion|VersionConflict| checkPrecondition|assumedMasterState and near-spellings found no third rung
implementing this shape. kanban's and bookmarks' version/opId-shaped hits
are the separate exactly-once / op-id-ledger pattern, already tracked as
#226 — not a precondition/base-version check. So this remains a
genuine 2-occurrence pattern (not #226's 6-occurrence situation), but two
independently-arrived-at, already-shipped, already-diverging implementations
is real material for a design decision — the same bar that justified
splitting #226 (replay-time exactly-once) out of #203 after kanban and lims
converged there.

#226 and this issue are related but distinct: #226 is about the
op-id/exactly-once replay ledger (has this write already been applied?);
this issue is about base-version precondition checking (does this write's
assumption about server state still hold?). Both share the shape "extract a
shared vocabulary from divergent rung implementations," but they are
different subsystems and different subject matter — do not conflate them.

What needs deciding

Should ledger and lims converge on one shared precondition vocabulary — and
if so, whose shape wins, or is a synthesis needed — or is the divergence
itself acceptable/intentional given the two domains (financial ledger vs.
lab sample tracking)? Concretely, whoever designs this should resolve:

• Field shape: a typed action field per DTO (as both rungs do today) vs.
  a generic envelope/metadata slot the framework provides.
• Mismatch handling: throw a typed error (ledger's VersionConflict) vs.
  report a conflict outcome for the model to reconcile (lims's
  ConflictInfo). Note docs/spec/offline/offline.md's existing
  onBackendChanged() conflict-checker/resolver hooks ("Conflict resolution
  on replay") already cover the model-driven merge/discard half of this —
  what's missing is the field-level precondition-assertion half, which is
  application code in RuleModel/SampleModel today.
• Granularity: ledger is row-level, lims is whole-entity. ODK's own
  baseVersion (cited below) is also per-entity; per-field granularity is
  not attested anywhere in this codebase yet.
• Required vs. optional: ledger's field is optional (unconditional apply
  when absent); lims's is required.

Background: comparable offline-first sync engines

morph's conflict checker (the onBackendChanged() replay path,
docs/spec/offline/offline.md) sees an opaque std::string payload and
nothing else — no framework notion of a base version, a precondition, a
revision, or a per-field change set. Every comparable offline-first sync
engine supplies at least a vocabulary for this even when it delegates the
merge policy: ODK's baseVersion, RxDB's assumedMasterState, Watermelon's
lastPulledAt, CouchDB's _rev are the same idea in four shapes — the queued
write states what it assumed, and the server checks it. lims's own
divergences from ODK's actual design (client-side prediction of server
version arithmetic rather than a server-issued branchId/trunkVersion; no
held-submission window for out-of-order arrival; whole-entity rather than
per-property conflict granularity) remain relevant prior art for whoever
designs the shared vocabulary.

Origin

Split out of #203 (gap 2), part of the offline-vs-sync-engines survey. See
#203 for the full comparative document and the ODK/RxDB/Watermelon/CouchDB
precondition-vocabulary examples in fuller detail.

[Yaraslaut]

Triage: parked, area: offline

What was verified

Ledger side — examples/ledger/include/ledger/dto/rule_dto.hpp:26-39
(UpdateRule::expectedVersion) and examples/ledger/src/models/rule_model.cpp:88-96
(RuleModel::execute(UpdateRule)) confirmed exactly as cited: an optional
std::int32_t, disengaged = apply unconditionally, engaged + mismatched =
throw VersionConflict{}, checked inline against the live row with no separate
ledger/table. Landed in commit 75a485a2 ("ledger: implement optimistic
concurrency, making SYNC-BENCHMARK's Scenario B real"), merged via PR #132 at
2026-08-22T08:06:11Z.

Lims side — examples/lims/include/lims/dto/offline_dto.hpp:125 (QueuedCapture::baseVersion,
type SampleVersion, non-optional) and :165-189 (ReplayCaptureResult/ConflictView
carrying baseVersion + serverVersion), with the check itself in
examples/lims/src/models/sample_model.cpp:598-634: mismatch produces a
ConflictReason, writes an OfflineConflictRecord row in its own conflict
table, and returns a Conflicted outcome — no throw. Merged via PR #177 at
2026-08-23T18:34:06Z.

Both merges predate this issue's filing (2026-08-23T21:16), which the issue
itself already notes — confirmed by direct PR/commit timestamp lookup rather
than taking the issue's word for it.

Divergence is real and matches the issue's table: optional vs. required
field, throw vs. outcome-record, inline-only vs. separate conflict table,
row-level vs. whole-entity granularity. Traced independently (ledger →
SYNC-BENCHMARK.md §10 Scenario B / #144, no reference to lims or #203; lims →
its own README) — not a copy-paste divergence, a convergent one.

Occurrence count: swept examples/*/include/*/{models,dto}/** and
examples/*/src/models/** for baseVersion|base_version|expectedVersion| VersionConflict|checkPrecondition|assumedMasterState. No third rung found.
This is genuinely a 2-occurrence pattern, distinct from #226's
6-occurrence/4-rung op-id-ledger pattern (confirmed separately — #226 is
triage: rescope / area: core, about replay-dedup via operationKey, not
about this issue's base-version optimistic-concurrency check; lims::QueuedCapture
carrying both fields as the shared evidence point stands, and the two remain
un-conflated here).

Rule-of-three check (examples/IMPLEMENTATION.md:13-21)

"an app-built answer to a framework gap... may be built twice in
examples/. The moment a third rung consumes it, it must either be
promoted... or explicitly dispositioned..."

At 2 occurrences, this pattern sits inside the explicitly-permitted
"built twice" allowance — not past the threshold that forces a promotion
decision. This is the load-bearing fact this triage turned up: the issue's
own framing ("two independently-arrived-at... implementations is real
material for a design decision") reads the same two data points as already
justifying action, but the project's own written threshold for forced
action is three. Two occurrences is exactly the situation the rule anticipates
staying app-layer without a disposition being owed yet.

Invariant check

Invariant 6 (a guarantee reimplemented per call site belongs in one
place, rule-of-three trigger) — the trigger has not fired yet by the
project's own numeric bar (2 of 3). Real precedent (#163) promoted at 3
independent rungs; this is 2.

Invariant 3 (value type reports fact, layer decides policy) — cuts
against a clean extraction even if/when a third occurrence appears.
docs/spec/offline/offline.md's "Conflict resolution on replay" section
already states the framework's design intent explicitly: "Conflict
detection and merge/discard are the model's responsibility" — the framework
seam (onBackendChanged(), a conflict-checker/resolver pair) deliberately
stops at opaque payloads and a plain bool, leaving mismatch handling to the
model. Ledger's hard throw vs. lims's queryable ConflictInfo record are
not two implementations groping toward the same answer — they're two
different, legitimate policies (financial ledger refuses; lab tracking
records-and-defers-to-a-human) that the spec already anticipates living in
the model layer. Any future shared vocabulary could standardize the fact
(what version was assumed vs. what the server holds — a baseVersion-shaped
struct) but not the policy (throw vs. record, required vs. optional,
row vs. entity granularity) without violating this invariant. That's a
real design cost the issue's own "What needs deciding" section already
half-acknowledges but doesn't resolve.

Valid-vs-rescope test

The issue's own title poses the choice as an explicit either/or: "extract
a shared vocabulary or document the divergence." The body's "What needs
deciding" section restates the same unresolved fork and then lists four
further open sub-questions (field shape, mismatch handling, granularity,
required-vs-optional) without picking an answer to any of them. This is a
menu, not a plan — it does not commit to one buildable direction, so valid
doesn't fit as filed.

Two different thresholds, not one — reconciling "the trigger has fired" with parked

#203's own disposition comment already described this issue at filing time:
"filed parked-shaped with an explicit re-entry condition (a second rung
independently needing base-version comparison). Correctly not filed as
valid/actionable-now." That narrower trigger — does a second occurrence
exist at all, enough to justify writing this up as a real, evidenced issue
rather than a footnote in #203 — has indeed fired, which is exactly why this
issue exists in its current well-evidenced form instead of staying buried.

That is a different threshold from examples/IMPLEMENTATION.md's
rule-of-three promotion rule (a third rung forces a promote-or-disposition
decision), which is the threshold that would justify a valid verdict
("extract now, here's the shape"). That one has not fired: this sweep found
exactly 2 occurrences, not 3. So both things are true at once: the issue was
right to surface now (2-rung trigger fired), and it is not yet actionable as
an extraction (3-rung trigger has not).

Verdict

triage: parked, not valid/rescope/wrong-layer. The observation is
real, correctly evidenced, and not mis-framed — but the issue's own title and
"What needs deciding" section leave the fork ("extract... or document...")
and four downstream design questions all open rather than committing to one
buildable direction, and the project's own numeric bar for forcing that
decision (rule-of-three) sits one occurrence away. Re-parking with a sharper
trigger:

Re-open when either:

1. A third rung independently hand-writes a base-version/precondition
   check against a queued or optimistic write (the literal rule-of-three
   line), at which point examples/IMPLEMENTATION.md's promotion rule makes
   this a forced decision, not a discretionary one; or
2. Someone is about to design the vocabulary anyway (e.g. driven by a new
   rung's need) — in which case invariant 3 above should shape the design
   from the start: standardize the fact (assumed-vs-actual version), not the
   policy (throw vs. record).

Labels applied: triage: parked, area: offline (kept alongside the
existing enhancement).