MVP Dry-Run / Sandbox Pilot Readiness Checklist

Status: docs-only readiness checklist Baseline: grounded in origin/main at or after commit 60806766 Scope: Buy Now dry-run/readiness pilot only

Current repo state summary

This checklist is based on read-only inspection of origin/main at or after commit 60806766, after the PR template cleanup, Algorand vault-first custody/claim model, Buy Now idempotency hardening, and Buy Now quantity forwarding to payment metadata were merged.

The current merged Buy Now path is preview-first and server-resolved:

• apps/web/src/app/api/auctions/[id]/buy-now-payment/preview/route.ts accepts only quantity, resolves canonical auction context, and calls the payments preview endpoint.
• apps/web/src/app/api/auctions/[id]/buy-now-payment/route.ts builds a deterministic Buy Now request id and forwards quantity internally to payments metadata.
• apps/web/src/server/buyNow/ contains the canonical context resolver, preview parser, preview gate, and idempotency helper.
• services/svc-payments/src/buyNowFinalityMetadata.ts defines the sanitized Buy Now finality metadata contract.
• services/svc-tenders/src/kafka/paymentFinalityConsumer.ts can consume payment finality events and record Buy Now fills, but is disabled by default.
• services/svc-tenders/migrations/0059_auction_buy_now_fills.sql and services/svc-tenders/migrations/0060_auctions_approved_quantity.sql provide the storage foundation when explicitly applied.

The Keepz sandbox/live contract is not confirmed. Weekend work must stay dry-run/readiness-only and must not depend on external Keepz replies. Keepz live must remain disabled. Algorand live/user-wallet transfer must remain disabled.

Dry-run pilot flow map

1. Buyer selects a whole-number Buy Now quantity on an auction detail page.
2. Web preview receives { quantity } only, fetches canonical auction detail through the API gateway, and resolves seller, price, currency, approved/sold/remaining quantity, and token context server-side.
3. Web preview builds a payments preview payload with seller account, platform account, total amount, currency, and commission policy. It does not create a payment intent and does not call Keepz or Algorand directly.
4. svc-payments preview evaluates split readiness: Keepz split support flag, seller payout profile, platform commission profile, balanced seller/platform split, masked recipient references, and commission ledger draft.
5. UI preview gating permits execution only when preview is present, current for the selected quantity, and readinessStatus is READY with no blocking reasons.
6. Execute route re-resolves canonical context, builds a deterministic request id, and forwards quantity internally to POST /payments/buy-now-split-order.
7. svc-payments create path validates split order configuration and settlement profiles, calculates buyer total, seller net, and platform commission, then persists intent metadata with intentType=BUY_NOW_KEEPZ_SPLIT_ORDER and a sanitized buyNow block.
8. On finality, payments projects safe Buy Now metadata into payment.finality.recorded: kind, auctionId, quantity, unitPriceMinor, and currency.
9. Payments outbox publishes finality to the configured payments finality topic when outbox publication is enabled.
10. Optional svc-tenders payment finality consumer records one idempotent auction_buy_now_fills row for settled Buy Now events.
11. Auction read projection sums settled fills and exposes soldQuantity and remainingQuantity on auction list/detail responses.
12. Admin visibility is available through payments admin, reconciliation, readiness, commission ledger, and payment detail surfaces.

Implemented pieces

• Preview-only dry-run route with no database mutation and no direct Keepz or Algorand call.
• Server-side canonical commercial context for Buy Now preview and execution.
• Preview parser ignores buyer-supplied seller, platform, recipient, and commission fields.
• Preview gate blocks missing, stale, loading, invalid, and blocked previews.
• Deterministic Buy Now execution request id based on canonical commercial fields, buyer, quantity, projection state, and token context.
• Quantity forwarding from web execute route into payments create payload.
• Payments create schema accepts optional trusted server-side quantity.
• Split settlement math calculates buyer total, seller net, and platform commission in minor units.
• Preview returns readiness, blocking reasons, masked recipient references, and ledger draft.
• Keepz split request builder emits gross amount, currency, description, uniqueId, and splitDetails for split mode.
• Finality metadata projector omits unsafe or incomplete metadata instead of guessing.
• Tender finality consumer sanitizes metadata and records idempotent settled fills only.
• Auction projection reads settled fills and computes sold/remaining quantities without mutating auctions.
• Admin payment readiness, reconciliation, health, commission ledger, and payment detail routes are present through the API gateway.

Missing / staging-only pieces

• Keepz sandbox/live contract is not confirmed; external Keepz sandbox/live requests must not be enabled yet.
• TENDERS_PAYMENT_FINALITY_CONSUMER_ENABLED defaults to false; fill recording requires explicit staging enablement plus Kafka brokers.
• Payments outbox, projection, and reconciliation workers are environment-gated and must be running for full end-to-end observability.
• Target staging database must already have the Buy Now fills table and approved_quantity column before finality/projection validation. Do not run migrations without explicit operator approval.
• approved_quantity is not automatically backfilled by migration 0060; pilot auction data must be prepared explicitly.
• Canonical min lot and quantity step enforcement is not present in the inspected merged Buy Now resolver; the current runtime gate enforces whole-number quantity bounds. Pilot min lot and step constraints must be handled as staging data/operator acceptance criteria or added in a follow-up PR.
• Linked asset/token context is required for tokenized instruments, but pilot data must ensure linkedAssetId, entitlementId, or linkedKesContractId is present.
• Admin payment and projection visibility exists, but a dedicated per-auction Buy Now fill ledger view may still be useful for operators.

Real-money blockers

• Keepz eCommerce split-order sandbox/live contract must be confirmed by Keepz.
• Keepz live must remain disabled until explicit operator approval after sandbox evidence.
• Provider payload contract must be accepted as currently shaped before any external execution path is enabled.
• Live Keepz credentials, base URLs, auth behavior, split settlement semantics, and status semantics must be verified outside production first.
• Production/staging migrations must be explicitly approved and verified, especially auction_buy_now_fills and approved_quantity.
• Pilot auctions need durable approved_quantity, correct sold/remaining projection, and valid token context where required.
• Seller and Kvary platform settlement profiles must be VERIFIED, support BANK, and have Keepz-recognized recipient references.
• Kafka/outbox/finality consumer path must be proven in staging before buyer money is accepted.
• Reconciliation and admin visibility must be healthy: no payments service 502, admin health green, and reconciliation behavior understood.
• Min lot and quantity step rules need a clear source of truth before real buyer flow if those constraints are commercially required.
• Algorand live/user-wallet transfer must remain disabled. The vault-first claim model is not a live buyer wallet transfer path.

Go / No-Go checklist

Go only if all of the following are true:

• Deployed code is origin/main at commit 60806766 or newer, and the built artifact matches the deployed source.
• Weekend work remains dry-run/readiness-only.
• KEEPZ_EXECUTION_MODE is DISABLED or DRY_RUN, not SANDBOX or LIVE.
• KEEPZ_FORCE_DRY_RUN=true is set if any internal create-intent dry-run path can reach provider execution code.
• No live Keepz credentials are used.
• No live Algorand transfer mode is enabled.
• No provider defaults are changed for the pilot.
• No migrations are run without explicit operator approval.
• Pilot auction has canonical seller, Buy Now price, currency, approvedQuantity, expected soldQuantity, and enough remainingQuantity.
• Tokenized pilot auction has linked asset/token/entitlement context.
• Pilot quantity is a whole number and within agreed min lot and step constraints.
• Seller payout profile is VERIFIED.
• Platform commission profile is VERIFIED.
• Recipient references are masked in responses and never accepted from browser-supplied payloads.
• Preview returns READY, balanced seller/platform amounts, and masked settlement legs.
• Invalid seller or platform profile returns blocked readiness and creates no payment intent.
• Idempotent retry of the same Buy Now request does not create duplicate downstream request boundaries.
• Created intent metadata contains sanitized Buy Now metadata with quantity and derivable unitPriceMinor.
• Finality event contains Buy Now metadata only when complete and safe.
• If enabled in staging, tender finality consumer records one fill per settled payment intent and ignores duplicates.
• Auction detail/list show expected sold and remaining quantities after a settled dry-run finality event.
• /admin/payments, reconciliation, readiness, commission ledger, and payment detail surfaces are reachable and do not return gateway 502.
• Operators can disable tender finality consumer and Keepz split-order flag without data rollback.

No-go if any of the following are true:

• KEEPZ_EXECUTION_MODE is SANDBOX or LIVE while Keepz contract remains unconfirmed.
• External Keepz sandbox/live requests would be made during weekend readiness work.
• Settlement profiles are missing, pending, disabled, or invalid.
• approved_quantity is absent for a tokenized pilot auction.
• Preview is stale, missing, blocked, or for a different quantity than execution.
• Finality, outbox, Kafka, or tender consumer behavior cannot be observed in staging.
• Admin/reconciliation visibility is unavailable.

Do-not-enable-live list

• Do not set KEEPZ_EXECUTION_MODE=LIVE.
• Do not set KEEPZ_EXECUTION_MODE=SANDBOX until Keepz confirms the external sandbox contract.
• Do not use live KEEPZ_API_KEY for this pilot.
• Do not rely on KEEPZ_API_BASE_URL or the live distributor URL for weekend work.
• Do not enable external Keepz split-order execution in production.
• Do not change Keepz provider payload shape, including splitDetails, commissionType, toIban, or direct receiver fields.
• Do not change commission calculation or rounding.
• Do not change provider defaults.
• Do not enable live Algorand or automatic ASA/user-wallet transfer behavior.
• Do not run migrations without explicit operator approval.
• Do not deploy as part of this checklist PR.
• Do not stage or commit unrelated dirty local worktree files.

Recommended next PRs in order

1. Staging data/readiness PR or ops runbook: prepare and verify pilot auction approved_quantity, token context, seller/platform profile readiness, and expected min lot / quantity step values without running broad migrations.
2. Quantity constraints PR: add canonical min lot and quantity step enforcement if those rules are required for MVP pilot acceptance.
3. Admin visibility PR: add a focused Buy Now pilot admin panel or fill-ledger view if operators need per-auction fill rows beyond current projection/payment views.
4. Staging finality PR: enable and verify payments outbox plus tender finality consumer in staging only, with KEEPZ_EXECUTION_MODE=DRY_RUN.
5. Keepz contract-confirmation PR: after Keepz confirms sandbox contract, add sandbox smoke/runbook updates without enabling live.
6. Real-money readiness PR: only after sandbox evidence, add operator-controlled live activation docs and checks, with no provider payload or commission changes unless contract evidence requires it.