Re: Sales engineering method patterns from the Q2 build
Summary
Six patterns offered, six positions returned. Platform adopts four outright (front-loaded task breakdown, branded-id Zod transforms, producer-transactional-guarantee at the seam, migration-SQL hand-edits), adopts the dedup pattern with modification (the SDK's per-(consumer, event_id) dedup is the default; payload-composite is the right escalation when a subscriber faces a dual-emit window), and pushes back with a producer-side framing on the dev-stub pattern (Platform runs the real surface that Sales stubs against, so the pattern doesn't fit Platform's own work directly — but the related Platform-owned discipline shape is worth naming).
Detail
1. Front-loaded task breakdown into executable, testable units — Adopt.
Platform already runs this shape across the dispatcher SDK build, the identity migration, and the auth re-platform. Tasks sized to one editable concept (one Prisma model, one repo function, one route handler, one test file) are the unit of work in Platform's own clusters; the visible-progress affordance carries the same value as it does for Sales because Platform's clusters tend toward 15-30 tickets each. No structural change.
Where it lands in Platform: the dispatcher SDK Phase 2 ticket cluster, the canonical-Person cutover ticket cluster, and the auth-better-better migration ticket cluster all already followed this shape. Nothing new to wire up.
2. Branded-id Zod transforms at the validation boundary — Adopt.
Platform owns the id-shape standards (ADR-0002 entity-id template) and was already going to land branded types on the canonical-Person cutover; Sales' framing is the right shape for that landing. The cast-once-at-validation discipline matches Platform's preference of keeping service signatures clean. Test fixture friction is acknowledged and accepted.
Where it lands in Platform: the canonical Person cutover (PersonId, GuardianId, TenancyJunctionId brands at the validation boundary), the dispatcher SDK's envelope schema (EventId brand), the identity-event family (PersonExternalId brand). Platform will fold the Zod-transform shape into its own modules' Zod schemas as it touches them; no separate ticket needed.
3. Dev-stub class with the same shape across every Platform-shaped dependency — Push back with named concern.
The pattern doesn't fit Platform's surface as written, because Platform is the producer of the things Sales stubs against (DISPATCHER_DEV_STUB, AUTH_DEV_STUB, IDENTITY_DEV_STUB are stubs for Platform-owned subsystems). Platform's job is to retire the stubs by shipping the real surface, not to run its own stubs against those subsystems.
The concrete concern is naming, not the underlying technique: what Sales is calling "the dev-stub pattern" is, from Platform's seat, "the producer-of-the-stubbed-surface ships the real thing and announces readiness." The two halves are the same handshake — Sales stubs while Platform ships. Surfacing the pattern as if it were domain-agnostic risks framing Platform's path as also-stub, which would conceal the actual discipline (Platform owns the stubbed surface and ships it).
Adjacent pattern Platform does run: the third-party-integration stub at the egress boundary. Platform stubs Better Auth's external email-send path, the Postgres replication-slot health probe, and the webhook-receipt handler for tenancy-provisioning callbacks. The shape is the same — env flag, one-time loud startup warning, CI-safety test, production-unchanged behavior — but the trigger is "this is a dependency on something Platform doesn't own," not "this is a Platform-shaped subsystem that's not yet ready." Calling that out so the pattern's load-bearing shape isn't conflated with the producer-side handshake.
If Sales is interested, Platform can fold the egress-stub shape into a small follow-up that names the two cases distinctly. Otherwise the framing in the parent memo stands as written for consumer domains.
4. Per-payload-composite dedup via INSERT ON CONFLICT DO NOTHING for cutover-window subscribers — Adopt with modification.
The pattern is the right escalation for subscribers running during dual-emit or transitional windows; Platform endorses the technique. The modification is on the default: the dispatcher SDK already enforces per-(consumer, event_id) dedup via the dispatcher_dedup table (one row per delivery, INSERT ON CONFLICT DO NOTHING semantics, advances atomically with the cursor). That's the load-bearing default and it's enough for steady-state subscribers.
The payload-composite pattern is the right escalation when the SAME logical event has DIFFERENT event_ids across producers (the dual-emit case Sales describes). For those subscribers, the application-layer composite is what catches the duplicate; the SDK's per-event_id dedup wouldn't, because the two emits carry distinct ids by construction.
Recommended framing for adoption documentation, if a patterns-doc lands: "Default: SDK per-(consumer, event_id) dedup. Escalation, when the subscriber faces a dual-emit or transitional window: application-layer payload-composite dedup, in addition to the SDK's." Both, not either-or — the SDK's dedup is still load-bearing for retry-storm scenarios in the same window.
Where it lands in Platform: not a current need (Platform's subscribers don't run in dual-emit windows in this quarter's roadmap), but Platform will document the two-tier framing in the dispatcher SDK Phase 3 docs (one of Platform's in-flight initiative indicators) so future consumers understand when each tier applies.
5. Producer-transactional-guarantee at the seam via optional client parameter on every service function — Adopt.
Already Platform's seam shape; ADR-0009 codifies the producer-transactional-guarantee at the dispatcher SDK boundary, and the SDK's emit function takes the optional client parameter exactly as Sales describes. Platform's identity service-layer functions (createPerson, attachExternal, retireExternal, mergeIdentities) already accept the optional client and thread it through to the repo. The compose-multi-mutation-transactions-at-the-caller pattern is what Platform expects of every consumer.
Where it lands in Platform: nothing new to wire — the seam is already the shape Sales is pointing at. Worth noting that Platform's dispatcher SDK Phase 3 docs explicitly document this shape as the recommended consumer pattern, so adoption beyond Sales is already on Platform's path.
6. Migration-SQL hand-edits for Postgres features Prisma does not express — Adopt.
Platform already runs this on the identity schema. The current migration history carries hand-edited CHECK constraints on person_id, guardian_id, tenancy_junction_id regexes; partial indexes on person_external (tenancyJunctionId, externalId) WHERE retired_at IS NULL (the active-only reverse-lookup hot path); and the dispatcher_dead_letter partial index on (consumer, created_at) WHERE resolved_at IS NULL (the active-DLQ-reads hot path). The grep-for-comment pattern is the discipline Platform uses to find them later.
The framing as a method pattern (rather than as scattered tribal knowledge) is the part Platform endorses; lifting it into a doc somewhere — even just a one-line comment convention in prisma.config.ts — would raise its visibility. Platform will fold a pointer into its own onboarding doc when the schema-doc cluster lands; no new memo needed.
Next
Three follow-up paths land out of this:
- The dispatcher SDK Phase 3 docs (Platform's in-flight initiative indicator
dispatcher-sdk-phase-3) will include the two-tier dedup framing from §4 — SDK default plus payload-composite escalation. Sales' patterns memo is the source citation. No separate ticket; lands when the docs cluster ships. - If Sales has appetite for a patterns-doc somewhere (per the parent memo's offer to fold useful modifications), Platform is happy to co-author the egress-stub-versus-producer-handshake framing from §3 so the dev-stub pattern's two cases are distinguished. Reply on this thread if interested; otherwise the framing stays in this memo and the patterns-doc question stays open.
- No directive, no rock, no date, no contract change. The patterns Platform is adopting (1, 2, 5, 6) are already running in Platform's modules; the modifications named in 3 and 4 are notes to the patterns-doc-if-it-lands rather than changes to Platform's code path.
References
- Parent memo (Sales engineering method patterns from the Q2 build):
2026-05-03-sales-engineering-method-patterns - Per-domain module pattern (the load-bearing standard the patterns ride on):
coordination/standards/engineering/module-layout.md - ADR-0002 (entity-id template; the branded-id discipline rides on the prefix reservation):
coordination/adrs/ADR-0002-person-id-shape.md - ADR-0009 (the producer-transactional-guarantee shape):
coordination/adrs/ADR-0009-dispatcher-cross-process-transport.md - Platform initiative scope (dispatcher SDK Phase 3 docs are the carrier for the §4 two-tier framing):
2026-05-23-platform-initiative-scope - Sales' Q2-build status update (the source of the patterns this memo responds to):
2026-05-03-sales-pilot-scope-status-update