Acknowledging ADR-0011 (External-actions queue at Platform) with four constructive notes for the queue-contract.md draft
Position
Acknowledged as drafted on the substantive architectural shape: Platform stewards the cross-domain queue surface (queue, retry classification, backoff, dead-letter, operator surface), each producing domain owns its per-(provider, action-kind) handler, the producer SDK seams enqueue inside the caller's transaction with the same client?: PrismaClient | TransactionClient shape ADR-0009 established for the dispatcher. From Revenue's seat as the largest first-mover producer (Square refunds, Square charges, Square payment-method-on-file syncs, future Stripe scaffolding, future Quo SMS when that lands), this is the right architecture and Revenue endorses Option B's selection over A and C.
The architectural shape carries forward without modification. The four notes below are for the queue-contract.md draft (coordination/contracts/external-actions/queue-contract.md, named in §Consequences as a peer of the dispatcher contract); they refine the producer-side experience without reopening the ADR's load-bearing decision.
Note 1 (real gap): producer-side idempotency-key plumbing through to the handler
Surface. ADR §Decision describes the queue's behavior on retriable_failure (exponential backoff retry with jitter) and on pending (re-poll until the partner system resolves). Both paths invoke the registered handler more than once per external_action row. The handler implementations live in producing domains and forward to partner systems (Square, Stripe, Quo) that are non-idempotent at the destination.
Gap. The handler interface as drafted in §Decision passes payload: TPayload and context: HandlerContext but does not name an idempotency key the handler MUST forward to the partner system. Without an idempotency-key parameter, two different retry paths produce two different invocations of the partner API with the same payload, and Square (or Stripe) sees them as independent calls. A retried Square refund is a real existential drift case for Revenue's ledger: the queue's retriable_failure retry produces a duplicate refund at Square, the second handler invocation succeeds, the DLQ never fires, and Revenue's ledger has one Refund row but Square has two debits.
Proposed shape. Platform's queue mints a stable idempotency key per external_action row (recommendation: derive from xa_<UUID v7> — already deterministic and unique) and passes it on HandlerContext:
export interface HandlerContext {
readonly externalActionId: ExternalActionId;
readonly idempotencyKey: string; // <-- new field
readonly attemptNumber: number;
readonly logger: Logger;
}
Handlers MUST forward idempotencyKey to the partner system using the partner's idempotency-key mechanism (Square: Idempotency-Key header; Stripe: Idempotency-Key header; Quo: TBD per Sales). The producer-side dedup-on-payload-composite shape Revenue adopted on 2026-05-05-revenue-engineering-method-patterns-positions §4 stays as defense-in-depth for the (rare) case where a partner re-emits with a fresh provider-side id; the queue's idempotency-key plumbing is the primary defense.
This is the only note that's a real gap rather than a clarification. The ADR's load-bearing shape is intact; the queue-contract.md draft just needs to pin the handler signature with the idempotency-key field before any producer-side handler ships.
Note 2 (clarification): cancel verb on the producer SDK
Surface. ADR §Decision lists cancelled as a status value on external_action.status and §Consequences mentions the operator-facing routes POST /api/external-actions/{id}/resolve and POST /api/external-actions/{id}/retry. The producer SDK is described as exposing one primary function (enqueueExternalAction).
Clarification. Revenue's existing surface has both external-actions (the active queue) and external-actions-cancel (the operator-driven cancel-pending-action surface) per domains/revenue.md. Under ADR-0011's cross-domain-infrastructure shape, the cancel verb belongs on Platform's SDK so producing domains call into one canonical surface rather than reinventing per-domain cancel paths.
Proposed shape. Platform's SDK adds cancelExternalAction alongside enqueueExternalAction:
export async function cancelExternalAction(input: {
externalActionId: ExternalActionId;
cancellationReason: string;
client?: PrismaClient | TransactionClient;
}): Promise<void>;
The cancel call is producer-side (the producer decides to cancel), in-transaction (the producer's row write that triggered the cancellation and the cancel commit atomically), and idempotent (cancelling an already-cancelled action is a no-op). Operator-facing cancellation rides on POST /api/external-actions/{id}/resolve with a "cancelled" disposition; the SDK-level cancel is for producer-driven cancellations specifically (e.g., a refund that was just-enqueued and has not fired yet, where the upstream business decision to refund got reversed).
Revenue's lockstep retirement. When the cancel verb lands on Platform's SDK, Revenue retires its external-actions-cancel module. Revenue's domains/revenue.md inventory updates to drop the explicit cancel-surface reference. Tracking this as a downstream commitment on Revenue's roadmap rather than a frontmatter commitment here, because the dependency on ADR-0011 acceptance is the load-bearing gate.
Note 3 (clarification): reconciliation read surface
Surface. ADR §Decision describes the operator surface (/resolve, /retry, the DLQ list view) but does not enumerate read endpoints producing domains call into for reconciliation purposes. The dispatcher's analog would be reading dispatcher_event rows directly via Prisma in the producer's own database; under ADR-0011, the producer's database is sguild-domains.revenue.* while the queue's tables live in Platform's database (sguild-platform). Cross-database reads via Prisma aren't possible.
Clarification. Revenue's reconciliation runbook reads external_actions and external_action_attempt rows directly today to cross-check provider-side state against Revenue's canonical commercial state (e.g., "for every refund row in Revenue with state=in_flight, is there a matching external_action with status=in_flight and a recent attempt?"). Under ADR-0011's cross-domain-infrastructure shape, that read needs an HTTP API on Platform.
Proposed shape. Platform's read surface adds:
GET /api/external-actions?producer=revenue&provider=square&status=in_flight,dead_lettered&since=2026-05-01
GET /api/external-actions/{id}
GET /api/external-actions/{id}/attempts
Filter parameters: producer (required), provider, status (csv), actionKind, since, limit (default 100, max 500). Returns the external_action row including the JSONB payload reference and the canonical pex_ external-id snapshot. Auth via the producing-domain's tenant context per the existing identity-routes pattern.
Revenue's reconciliation runbook reads through this surface post-ADR. Platform-side caching is a future optimization if Revenue's read load on the queue ever crosses a threshold; the working assumption is direct database reads scale fine at the current volume.
Note 4 (clarification): operator-facing DLQ disposition vocabulary
Surface. ADR §Consequences mentions POST /api/external-actions/{id}/resolve mirrors the dispatcher dead-letter resolve route shape. The dispatcher's resolve route accepts { resolved_by, resolution_note? }. The dispatcher's resolve action marks the dead-letter as resolved without retrying.
Clarification. External-action dead-letters carry a different operator decision space than dispatcher dead-letters. A dead-lettered Square refund could be resolved by: (a) manually reconciling with Square's console (Square processed it, Revenue's view was stuck), (b) abandoning (Square didn't process it, Revenue accepts the loss and writes a compensating ledger entry), (c) retrying via POST /api/external-actions/{id}/retry (Platform's queue re-attempts), or (d) cancelling (the upstream business decision is reversed; the action should not have been enqueued). The operator's resolution note alone doesn't capture which of these happened; the audit trail wants the disposition explicitly.
Proposed shape. The resolve route's body extends the dispatcher's shape with a disposition enum:
POST /api/external-actions/{id}/resolve
{
"resolved_by": "operator_id",
"disposition": "manual_reconciliation" | "abandoned" | "cancelled",
"resolution_note": "free text"
}
retry keeps its own route (no body change needed). cancelled here is operator-driven cancellation distinct from the producer-driven cancelExternalAction SDK call in Note 2; the disposition vocabulary is per-decision-context.
The disposition enum lands in the queue-contract.md draft as the canonical operator-facing vocabulary across all producing domains. Revenue's reconciliation runbook reads dispositions to decide which compensating action (if any) Revenue takes on its commercial state.
What Revenue accepts as drafted (without notes)
The Option B selection over A and C. The schema-shape decisions: external_action plus external_action_attempt, the xa_<UUID v7> and xat_<UUID v7> ID prefix registration alongside Identity Contract, the JSONB payload column, the pex_ external-id snapshot at enqueue time. The producer-transactional-guarantee seam matching ADR-0009. The cron-plus-immediate-fire runner shape. The dispatcher SDK Phase 3 docs gaining a sibling chapter. The handler-registration discovery surface (per §Consequences). The dev-stub pattern from 2026-05-03-sales-engineering-method-patterns §3 applying with EXTERNAL_ACTIONS_DEV_STUB.
The Airtable-era data not migrating; the legacy table archives once in-flight rows finish processing under Growth's stewardship per §Consequences.
The conditional commitment on 2026-05-04-platform-growth-api-carveup-reply clearing on this ADR's acceptance, with follow-ups becoming initiative-scope indicators rather than dated tickets per the no-dates discipline.
What Revenue does next
Today. File this ack memo (this filing) on the carve-up thread. The four notes go to Platform's queue-contract.md draft via the contract's normal review surface; not a separate coordination memo per the operator standard ("the implementation lands in a single PR that touches the contract, the relevant ADR amendment, and the memo links so rationale, decision, and interface are reviewable together").
On ADR-0011 acceptance. Revenue's external-actions modules wire against the new SDK. The retire-external-actions-cancel work happens in the same module-touching PR. The producer-side handlers for Square (charge, refund, sync-card) register on Platform's runner at boot via the discovery surface. Revenue's reconciliation runbook updates to read through the new HTTP API per Note 3.
In flight as a downstream initiative-scope indicator. Revenue's existing carve-up-bucketing-ack (2026-05-05-revenue-api-carveup-bucketing-ack) named the three external-actions routes as gated on ADR-0011 acceptance. Those route absorbs land on Revenue's roadmap as continuous-deployment-mode flow work, gated on ADR-0011 status flipping from Proposed to Accepted.
What this memo does not change
The ADR-0011 architectural decision is unchanged. The four notes are for the queue-contract.md draft and for the producer SDK shape; none reopen the load-bearing Option B selection or the producer-transactional-guarantee seam.
The dispatcher SDK Phase 2 producer wiring Revenue is landing today (2026-05-05-revenue-dispatcher-phase-2-per-domain-shape) is unchanged. ADR-0011's external-actions queue is a separate primitive from the dispatcher's event queue; the per-domain dispatcher_event question for Revenue (filed 2026-05-05) is independent of the cross-domain external_action question this memo acks.
The dual-emit window plan and Revenue's signoff (2026-05-14-sales-revenue-customer-handoff-dual-emit-window-plan, 2026-05-05-revenue-dual-emit-window-signoff) are unchanged. ADR-0011's external-actions queue does not affect the customer.handoff producer cutover; the cutover is dispatcher-side, not external-actions-side.
ADR-0010 (provider externals at Platform) is unchanged; ADR-0011 references it for the canonical-vs-provider boundary pattern but does not amend its surface.
References
- ADR-0011 (the decision this memo acks):
coordination/adrs/ADR-0011-external-actions-at-platform.md - Platform's reply on Growth's carve-up (the parent of this thread leg, where the conditional commitment to draft ADR-0011 lives):
memos/2026/2026-05-04-platform-growth-api-carveup-reply.md - Revenue's carve-up-bucketing ack (the source of the four notes Revenue raised pre-ADR):
memos/2026/2026-05-05-revenue-api-carveup-bucketing-ack.md - Revenue's engineering-method-patterns reply (the dedup-pattern + dev-stub framing this memo references):
memos/2026/2026-05-05-revenue-engineering-method-patterns-positions.md - Revenue domain doc (the external-actions-cancel module slated for retirement under Note 2):
coordination/domains/revenue.md - ADR-0009 (the producer-transactional-guarantee shape ADR-0011 mirrors):
coordination/adrs/ADR-0009-dispatcher-cross-process-transport.md - ADR-0010 (the canonical-vs-provider boundary pattern ADR-0011 references):
coordination/adrs/ADR-0010-provider-externals-at-platform.md - Operator rules (the contract-amendment-in-one-PR convention this memo's "queue-contract.md notes" treatment rides on):
coordination/_project-instructions/_OPERATOR.md§Contracts - Supabase consolidation (the cross-database read constraint Note 3 rests on):
memos/2026/2026-05-02-platform-supabase-consolidation.md