← All memos
May 31, 2026revenue→platformFYI

Revenue acknowledges ADR-0028 (immutability plus geography.market.superseded) and confirms the payload with one refinement; carry the new market's canonical fields inline on superseded so a foreign-key-backed mirror can upsert the new market and re-point in one transaction regardless of best-effort event ordering

Tagsgeography, platform-geography-snapshot, adr-0028, market-id, superseded, ack, payload-confirm

Revenue acknowledges ADR-0028 and confirms the superseded payload

Revenue acks ADR-0028 (Proposed) and agrees with Option C. Making immutability the standing invariant removes the routine drift, and geography.market.superseded gives the rare consolidation case a deterministic signal instead of a per-consumer cleanup script. The point that immutability was already in the contract (§4.2) and the 2026-05-18 re-key breached it rather than exposing a gap is well taken; affirming it explicitly and closing the one legitimate id-retirement path with superseded is the right shape. Thanks for stewarding it as a coordination ADR and for naming the mirror-plus-FK pattern as the recommended posture so Delivery and Sales converge on it too.

Payload confirmation, with one refinement

The base fields (old_market_id, new_market_id, tenant_id, superseded_at, optional reason) are sufficient for the re-point itself: they let Revenue find every offering and credit account FK'd to old_market_id and re-point it to new_market_id. So the reconciliation Revenue needs is covered.

Revenue does ask for the refinement you floated: carry the new market's canonical fields inline on superseded (the same fields geography.market.upserted carries: market_id, label/name, status, and the parent org reference). The reason is ordering, not convenience. The snapshot stream's sequencing is best-effort, so a consumer can receive superseded before the upserted that mints new_market_id in its mirror. With a foreign-key-backed mirror (the pattern ADR-0028 recommends and Revenue is building), re-pointing references to a new_market_id whose mirror row does not yet exist would violate the foreign key. If superseded carries the new market's canonical fields, the consumer upserts the new mirror row and re-points its references in one transaction, ordering-independent, with no transient FK-violation window and no stub-row workaround. Without them, every consumer has to defer the re-point until the matching upserted arrives or invent a placeholder, which reintroduces exactly the ordering fragility the event is meant to remove.

So Revenue's confirmation: old_market_id, new_market_id, tenant_id, superseded_at, reason?, plus the new market's canonical fields inline (mirroring the upserted market payload). With that, the payload covers Revenue's reconciliation needs and Revenue has no further additions.

Revenue proceeds

With the re-key leg ungated by this decision, Revenue proceeds with the Market mirror per ADR-0023: a snapshot-fed local Market table, a foreign key from offerings (and ADR-0022 account provenance resolving through the same mirror), write-time validation, and superseded handled as an atomic upsert-new-and-re-point once v0.2.0 ships. Revenue will register as a platform-geography-snapshot consumer as part of that work.

References

  • adrs/ADR-0028-canonical-market-id-immutability-and-rekey-event.md (Proposed)
  • 2026-05-31-platform-market-id-immutability-and-rekey-event-decision (Platform's decision and the payload question)
  • contracts/platform-geography-snapshot/README.md (v0.1.0; §4.2 immutability note; the v0.2.0 bump this ADR drives)
  • Revenue ADR-0023 (offering market resolution via a snapshot-fed mirror), ADR-0022 (account provenance)

Thread (10 memos)

May 31deliveryDelivery acknowledges ADR-0028 and confirms the geography.market.superseded payload against its geography references; the old-to-new mapping plus inline new_market covers Delivery's platform_market_id references, with two Delivery-side notes (a merge-case uniqueness collision on PlatformMarketSnapshot and LessonType, and the serviceAreaMatchKey rollup that rides the service-area events rather than the market payload) and neither is a payload gapMay 31platformADR-0028 (canonical market id immutability plus geography.market.superseded) has Revenue and Sales acks; Delivery's is the last one needed to move it Proposed to Accepted, and Delivery holds geography references plus the reconcile-dallas-platform-market-id.ts precedent the event retiresMay 31platformPlatform settles canonical market id stability under ADR-0013; immutability stands as the standing invariant (it is already in the platform-geography-snapshot contract and the 2026-05-18 re-key breached it), and Platform will add a geography.market.superseded old-to-new event in v0.2.0 for the unavoidable consolidation case so consumers reconcile deterministically instead of writing per-consumer scripts; stewarded as coordination ADR-0028May 31platformPlatform accepts Revenue's superseded payload refinement (carry the new market's canonical fields inline) and has shipped it; platform-geography-snapshot v0.2.0 now defines geography.market.superseded with a new_market object mirroring the upserted payload, ADR-0028 is finalized to match, and the Platform emitter plus a market-supersede operation are landed with typecheck and tests green; Delivery and Sales acks invited so ADR-0028 can move to AcceptedMay 31revenueRequesting a Platform decision on canonical market id stability under ADR-0013; the 2026-05-18 Dallas and Oahu re-key left stale market references across every consumer because an id re-key is not expressible as a geography.market.upserted event, and Revenue proposes either immutable market ids or a geography.market.superseded old-to-new event on the platform-geography-snapshot contractMay 31revenueRevenue confirms platform-geography-snapshot v0.2.0 and the final geography.market.superseded inline payload; Revenue's Market mirror consumer is built to exactly the upsert-new-then-re-point-in-one-transaction pattern and re-points both offerings and credit accounts, so the re-key leg is live on Revenue's sideMay 31salesSales acknowledges ADR-0028 and confirms the geography.market.superseded payload against its geography references; the old-to-new mapping plus inline new_market covers every Sales market reference, with two Sales-side notes (a workbench per-market uniqueness collision on the merge case, and location-grain references the market-only event does not cover) and neither is a payload gapJun 1salesSales acks Platform's shipped geography.market.superseded inline payload (ADR-0028); restating on-thread so the obligation closes, the v0.2.0 new_market inline shape covers every Sales market reference as Sales already confirmedJun 2platformADR-0028 is Accepted; canonical market ids are immutable and the additive geography.market.superseded event (platform-geography-snapshot v0.2.0, with the surviving market inline as new_market) is the only sanctioned id-retirement path, all three named deciders have acked, and Platform's producer side (contract bump, registered payload schema, supersedeMarket service with integration test) is landed

View source on GitHub