Auction Buy Now — payment finality consumer (Phase 3B-iii)

Purpose

svc-tenders runs an optional Kafka consumer that subscribes to payments.finality events emitted by svc-payments and records idempotent rows in auction_buy_now_fills when a Buy Now sale settles.

The consumer is disabled by default. It is wired into svc-tenders startup but performs zero Kafka work unless explicitly enabled.

Environment contract

| Variable | Default | Notes | | --- | --- | --- | | TENDERS_PAYMENT_FINALITY_CONSUMER_ENABLED | false | Master switch. When not true, no Kafka client is constructed and no broker connection is attempted. | | TENDERS_PAYMENT_FINALITY_CONSUMER_STRICT | false | When true and the consumer fails to start (e.g. brokers empty or connect() rejects), startup crashes. When false, the failure is logged and svc-tenders keeps running. | | TENDERS_PAYMENT_FINALITY_KAFKA_BROKERS | "" (empty) | Comma-separated. Required when enabled. | | TENDERS_PAYMENT_FINALITY_KAFKA_TOPIC | payments.finality | | | TENDERS_PAYMENT_FINALITY_KAFKA_GROUP_ID | kvary-tenders-payment-finality | | | TENDERS_PAYMENT_FINALITY_KAFKA_CLIENT_ID | kvary-tenders-payment-finality | | | TENDERS_PAYMENT_FINALITY_KAFKA_FROM_BEGINNING | false | |

Required migrations

Both already shipped in earlier phases — re-confirm they are applied on the target database before enabling:

• 0059_auction_buy_now_fills.sql (Phase 3A)
• 0060_auctions_approved_quantity.sql (Phase 3A)

Enable sequence

1. Verify the two migrations above are applied.
2. Confirm svc-payments is on Phase 3B-ii or later (so finality events carry metadata.kind="BUY_NOW").
3. Set the env vars on the svc-tenders process:

   TENDERS_PAYMENT_FINALITY_CONSUMER_ENABLED=true
   TENDERS_PAYMENT_FINALITY_KAFKA_BROKERS=broker-1:9092,broker-2:9092
   

4. Restart svc-tenders.
5. Tail logs for payment_finality_consumer_started topic=….

Verification

# expect: 23/23 tests pass, no broker required
npm --prefix services/svc-tenders run test:auction:payment-finality-consumer

# spot-check on the live process
grep payment_finality_consumer /var/log/svc-tenders/app.log

Rollback

TENDERS_PAYMENT_FINALITY_CONSUMER_ENABLED=false
# restart svc-tenders

The consumer will log payment_finality_consumer_disabled and skip all Kafka work. No data is rolled back; idempotency keys remain in auction_buy_now_fills.

What this consumer does NOT do

• Does not call Keepz, Algorand, or any open-banking provider.
• Does not decrement auctions.sold_quantity or any remaining-quantity projection (Phase 3C).
• Does not update canonicalContext (Phase 3C).
• Does not record durable auction outcomes (Phase 3D).
• Does not trigger on-chain (ASA) finality (Phase 3D).