merge: M3-W124 -- a synthetic shape's counter holds where a traffic counter adds

Author: stroland02

docs/superpowers/reports/2026-08-03-a-retried-replay-converges.md

@@ -12,11 +12,16 @@ and `src/sync/verify/mock_response.py`, wired as the `replay` node in
 `src/sync/remediate/graph.py:37`) and does not feed the shape store — deliberately, which
 withdraws this document's claim below that every replay run is also a `source='replay'` writer.
 A replay row is the published specification restated through the customer's code, not a response
-the customer's code received, and two consumers read this table as traffic: one replay row is
-enough to turn an uncorroborated divergence into a `breaking` finding, and a row at the floor
-outranks the specification in the mock the next replay is verified against.
-`docs/superpowers/reports/2026-07-30-replay-shapes-reach-the-store.md` carries the measurements
-and names what `src/sync/detect/` and `src/sync/graph/` have to change before replay can write.
+the customer's code received. Two consumers used to read this table as traffic with no way to say
+so, and both conditions that blocked the writer have since been answered:
+`GraphStore.observed_shapes` returns traffic alone unless a caller asks for every source, and
+`record_observed_shape` no longer accumulates `sample_count` for a synthetic source, so a replay
+retried or repeated converges instead of counting one synthesized body once per attempt.
+The writer is still not reinstated — that is its own task, and what it now owes is a consumer,
+since no caller in `src/` reads a `replay` row.
+`docs/superpowers/reports/2026-07-30-replay-shapes-reach-the-store.md` carries the measurements,
+`docs/superpowers/reports/2026-07-31-traffic-and-non-traffic-shapes.md` closed the first
+condition and `docs/superpowers/reports/2026-08-03-a-retried-replay-converges.md` the second.
 The interceptor SDK does not exist — see Sequencing.
 **Scope:** Detecting vendor changes no one published, and verifying patches against behavior rather than types
 alone. The design transposes Meticulous's record-replay-diff mechanism into the API-consumption domain.
@@ -205,7 +210,7 @@ number remains in engineering docs; the volume number is the one a customer sees
 | When | What | State |
 |---|---|---|
 | Now | This document. The `observed_shape` schema is binding on anything that later records shapes. | Built — `src/sync/graph/schema.sql:124`, `ObservedShape` in `src/sync/core/models.py` |
-| M1 (with the sandbox the threat model gates on) | The replay tier. Feeding the shape store as `source='replay'` was specified here and is withdrawn. | Built as a verification stage, and deliberately not a feeder — `src/sync/verify/replay.py`, between `static_verify` and `push_branch` in `src/sync/remediate/graph.py`. Its `source='replay'` rows reach `RunState` and no further, pinned by `tests/test_replay_shape_writeback.py`. Replay rows are synthesized from the specification, and `observed_shapes` has no `source` filter, so they would reach two consumers that read the table as traffic. Reinstating the writer is blocked on `src/sync/detect/` and `src/sync/graph/` — see the report of 2026-07-30 |
+| M1 (with the sandbox the threat model gates on) | The replay tier. Feeding the shape store as `source='replay'` was specified here and is withdrawn. | Built as a verification stage, and deliberately not a feeder — `src/sync/verify/replay.py`, between `static_verify` and `push_branch` in `src/sync/remediate/graph.py`. Its `source='replay'` rows reach `RunState` and no further, pinned by `tests/test_replay_shape_writeback.py`. Both conditions the report of 2026-07-30 set are answered: traffic and synthetic rows are kept apart on read (2026-07-31), and a synthetic row's `sample_count` no longer accumulates, so a retried replay converges (2026-08-03). Reinstating the writer is still its own task, and it owes a consumer for these rows — both readers now answer traffic alone |
 | M2 (signal sources) | Error-payload shapes from Sentry-class sources, `source='error-payload'`. The detector ships here, running on whatever baseline exists, with the sample floor keeping it silent where data is thin. | Built — `src/sync/signals/sentry/shapes.py`, `src/sync/signals/datadog/shapes.py`, and `src/sync/detect/observed_drift.py`, whose `MIN_SAMPLES` is the sample floor |
 | Post-M2, opt-in | The interceptor SDK, only for customers who want unpublished-change detection on live traffic. A separate adoption decision with its own trust conversation. | Not built |
 

docs/superpowers/specs/2026-07-26-sync-observed-contract-drift.md

@@ -242,6 +242,25 @@ CREATE INDEX IF NOT EXISTS migration_outcome_kind_idx
 -- column exists at all: a table that appended would make every presence rate a function of how
 -- often the ingest ran rather than of what the vendor sent.
 --
+-- **sample_count means one thing per source class and merges accordingly**, and it is the
+-- sentence above that forces the split rather than an exception to it. For a traffic source the
+-- write is a response somebody received, so a second write is a second sample and the counter
+-- adds. For a synthetic source -- `sync.graph.sources.SYNTHETIC_SOURCES`, the rows Sync
+-- constructed from a published specification -- a second write is the ingest running again over
+-- the same constructed body, so the counter holds: it is the largest single claim made about the
+-- row rather than the sum of the claims. One row still means one shape; for a synthetic source
+-- it also means one sample, at any repetition count.
+--
+-- The replay tier is what forces it. A failed replay re-enters `patch` and MAX_STATIC_ATTEMPTS
+-- is 3, so one finding offers the same synthesized body three times, and ten findings over one
+-- operation would carry it past the sample floor the drift detector reads. A run key on the row
+-- does not fix that -- it changes which row the addition lands in, and the retry writes the same
+-- key twice. Convergence under re-execution is a property of the merge.
+--
+-- Only the counter is held. Every other column merges identically for both classes, so a
+-- synthetic row still records that the shape was seen, that the field can be null, which
+-- published members were exercised, and over what window.
+--
 -- Values are never stored, only shape -- paths, types, nullability, counts. The single
 -- exception is an enum member the vendor's published specification names, because a vendor enum
 -- is public data. A string the specification does not name is a customer's data and is
@@ -272,6 +291,7 @@ CREATE TABLE IF NOT EXISTS observed_shape (
     -- and `GraphStore.observed_shapes` answers with traffic alone unless asked for everything.
     -- `sync.graph.sources` holds which is which and must be extended with this list.
     source           TEXT NOT NULL,
+    -- Samples, not writes. What that counts depends on the source class -- see the grain note.
     sample_count     INTEGER NOT NULL DEFAULT 1,
     first_seen       TIMESTAMPTZ NOT NULL DEFAULT now(),
     last_seen        TIMESTAMPTZ NOT NULL DEFAULT now(),

src/sync/graph/schema.sql

@@ -12,6 +12,13 @@
 name appears here and none may, which is what keeps this out of the reach of `CLAUDE.md`'s rule
 that vendor knowledge lives in adapters.
 
+The partition decides two things, and the second was added after the first. On read, which rows
+a caller asking for traffic receives. On write, whether `sample_count` accumulates: a second
+write of a traffic row is a second sample, and a second write of a synthetic row is this ingest
+running again over a body Sync built. Both live here because a row's merge and a row's audience
+are the same question about the mechanism, and answering them from two lists would let them
+disagree.
+
 **Membership is positive.** A source added to `ObservationSource` and forgotten here is then
 absent from every baseline rather than silently entering one -- and `ObservedDriftDetector` is
 the detector most able to violate precision-over-recall, so the failure that costs recall is the

src/sync/graph/sources.py

@@ -601,14 +601,31 @@ def record_observed_shape(self, shape: ObservedShape) -> None:
         widens at both ends rather than taking the last write, since sources do not arrive in
         order: an error-payload batch can be forwarded hours after a replay run observed the
         same shape.
+
+        `sample_count` is the one of them whose merge is not idempotent, and it adds only for a
+        source in `TRAFFIC_SOURCES`. A synthetic row is a body Sync constructed from a published
+        specification, so writing it again is this ingest running again rather than the shape
+        being seen again, and a counter that added would measure how often Sync ran against the
+        floor the detector reads. Held as a maximum rather than by holding the row still: taking
+        whichever value arrived first would make the counter the only column in this clause that
+        depends on arrival order, and taking the incoming one would rewrite counts written before
+        the clause was split.
+
+        The classification is read here rather than asserted by the caller. A row's merge is a
+        property of the mechanism that produced it, and `sync.graph.sources` is where that is
+        decided for the reader too.
         """
         placeholders = ", ".join(["%s"] * len(self._SHAPE_COLUMNS))
         self._connect().execute(
             f"""
             INSERT INTO observed_shape ({", ".join(self._SHAPE_COLUMNS)})
             VALUES ({placeholders})
             ON CONFLICT (vendor_id, operation_id, field_path, json_type, source) DO UPDATE SET
-                sample_count = observed_shape.sample_count + EXCLUDED.sample_count,
+                sample_count = CASE
+                    WHEN observed_shape.source = ANY(%s)
+                    THEN observed_shape.sample_count + EXCLUDED.sample_count
+                    ELSE GREATEST(observed_shape.sample_count, EXCLUDED.sample_count)
+                END,
                 nullable_seen = observed_shape.nullable_seen OR EXCLUDED.nullable_seen,
                 spec_enum_values = ARRAY(
                     SELECT DISTINCT unnest(observed_shape.spec_enum_values || EXCLUDED.spec_enum_values)
@@ -617,7 +634,10 @@ def record_observed_shape(self, shape: ObservedShape) -> None:
                 first_seen = LEAST(observed_shape.first_seen, EXCLUDED.first_seen),
                 last_seen = GREATEST(observed_shape.last_seen, EXCLUDED.last_seen)
             """,
-            [getattr(shape, name) for name in self._SHAPE_COLUMNS],
+            [
+                *(getattr(shape, name) for name in self._SHAPE_COLUMNS),
+                sorted(TRAFFIC_SOURCES),
+            ],
         )
 
     def record_observed_call(self, call: ObservedCall) -> None:

src/sync/graph/store.py

@@ -1,4 +1,4 @@
-"""Traffic and non-traffic rows are kept apart on read.
+"""Traffic and non-traffic rows are kept apart on read, and merged differently on write.
 
 `observed_shape.source` says which mechanism produced a row. Two consumers read the table as
 traffic -- `ObservedDriftDetector` and the baseline the mock builder is handed -- and until this
@@ -149,6 +149,98 @@ def test_no_source_is_both_traffic_and_synthetic():
     assert TRAFFIC_SOURCES & SYNTHETIC_SOURCES == frozenset()
 
 
+# --- what the store does with a row it already holds ---------------------------------
+#
+# The same partition, applied to the conflict clause. `sample_count` is the one column in that
+# clause whose merge is not idempotent, and idempotence is what `CLAUDE.md` requires of a stage
+# re-run on the same input. For traffic the addition is right and is the reason the column
+# exists: two error payloads carrying one shape are two samples. For a synthetic source the
+# second write is the same constructed body again, so adding would count how often Sync ran.
+#
+# Both directions are parametrised over the sets rather than over the values written here, so a
+# fourth source added to `sync.graph.sources` arrives with a merge assertion instead of taking
+# whichever branch it happens to fall into.
+
+
+@pytest.mark.parametrize("source", sorted(TRAFFIC_SOURCES))
+def test_a_traffic_row_written_again_counts_again(store: GraphStore, source: str):
+    """The counterpart that keeps the synthetic assertion below from reading as a frozen
+    counter. A clause that stopped counting for every source would satisfy that test and
+    destroy the sample floor, which is the failure mode this pair exists to separate.
+    """
+    for _ in range(3):
+        store.record_observed_shape(_shape(source=source))
+
+    rows = store.observed_shapes("stripe", "PostCharges", traffic_only=False)
+    assert [row.sample_count for row in rows] == [3]
+
+
+@pytest.mark.parametrize("source", sorted(SYNTHETIC_SOURCES))
+def test_a_synthetic_row_written_again_does_not_count_again(store: GraphStore, source: str):
+    """A synthetic row is a body Sync constructed, so writing it a second time is the ingest
+    running a second time and not the shape being seen a second time. The count is one sample
+    however many times the write happens.
+    """
+    for _ in range(3):
+        store.record_observed_shape(_shape(source=source))
+
+    rows = store.observed_shapes("stripe", "PostCharges", traffic_only=False)
+    assert [row.sample_count for row in rows] == [1]
+
+
+def test_a_synthetic_count_written_before_this_clause_is_not_rewritten(store: GraphStore):
+    """Rows already in a database were written under a clause that added, so some hold counts
+    above one. Taking the incoming value would rewrite that history on the next write, which is
+    a migration performed silently by a merge rather than a merge holding a counter still.
+    """
+    store.record_observed_shape(_shape(source="replay", sample_count=5))
+    store.record_observed_shape(_shape(source="replay", sample_count=1))
+
+    rows = store.observed_shapes("stripe", "PostCharges", traffic_only=False)
+    assert [row.sample_count for row in rows] == [5]
+
+
+def test_a_synthetic_rows_count_does_not_depend_on_arrival_order(store: GraphStore):
+    """Every other column in this clause merges the same way whichever write lands first --
+    `LEAST`, `GREATEST`, `OR`, a union -- because sources do not arrive in order. Keeping
+    whatever the row already held would make the counter the one column that reads the
+    sequence, which is the property `test_an_observation_arriving_out_of_order_does_not_rewind
+    _the_window` already refuses for the timestamps.
+    """
+    store.record_observed_shape(_shape(source="replay", field_path="/a", sample_count=5))
+    store.record_observed_shape(_shape(source="replay", field_path="/a", sample_count=1))
+    store.record_observed_shape(_shape(source="replay", field_path="/b", sample_count=1))
+    store.record_observed_shape(_shape(source="replay", field_path="/b", sample_count=5))
+
+    rows = store.observed_shapes("stripe", "PostCharges", traffic_only=False)
+    assert {row.field_path: row.sample_count for row in rows} == {"/a": 5, "/b": 5}
+
+
+def test_a_synthetic_row_written_again_still_gains_evidence_and_widens_its_window(
+    store: GraphStore,
+):
+    """Only the counter is held. `DO NOTHING` for synthetic sources would converge too, and
+    would throw away the rest of the merge: a later write proving the field can be null, or an
+    enum member an earlier specification did not name, or the window this row covers. The row
+    still records that the shape was seen and when -- it stops recording how many times the
+    write happened.
+    """
+    later = NOW + timedelta(days=1)
+    store.record_observed_shape(_shape(source="replay", nullable_seen=False))
+    store.record_observed_shape(
+        _shape(
+            source="replay", nullable_seen=True, spec_enum_values=["succeeded"],
+            first_seen=EARLIER, last_seen=later,
+        )
+    )
+
+    row = store.observed_shapes("stripe", "PostCharges", traffic_only=False)[0]
+    assert row.sample_count == 1
+    assert row.nullable_seen is True
+    assert row.spec_enum_values == ["succeeded"]
+    assert (row.first_seen, row.last_seen) == (EARLIER, later)
+
+
 # --- the two consumers, end to end --------------------------------------------------
 
 
@@ -287,6 +379,24 @@ def test_rows_written_before_the_filter_existed_survive_a_second_apply_schema(st
     ]
 
 
+def test_a_held_synthetic_count_survives_a_second_apply_schema_and_a_further_write(
+    store: GraphStore,
+):
+    """The same assertion for the clause rather than for the column list, because the clause is
+    what this task changed. A `replay` row at 5 was written under a clause that added, and it
+    has to come through both a re-applied schema and a further write intact -- neither reset to
+    1 nor advanced to 6.
+    """
+    store.record_observed_shape(_shape(source="replay", sample_count=5))
+
+    store.apply_schema()
+    store.apply_schema()
+    store.record_observed_shape(_shape(source="replay"))
+
+    rows = store.observed_shapes("stripe", "PostCharges", traffic_only=False)
+    assert [row.sample_count for row in rows] == [5]
+
+
 # --- the defect this task did not fix, fixed by M3-W122 -----------------------------