| name | blnk-queueing |
| description | Choose Blnk queue vs skip_queue per step from whether the next action needs an immediate ledger outcome or can proceed async. Use when setting skip_queue, mixing sync auth with async settlement, handling QUEUED status, or wiring confirmation after create or commit. |
| metadata | {"author":"blnk","version":"0.5"} |
Queueing
There is no default path for your product. Choose deliberately per step / per edge: does the next step need the ledger outcome now, or can the movement finish async?
Different sides of the same journey can disagree. Do not force one skip_queue value onto every call in a product flow.
| Need | Choice | Flag |
|---|
| Next step needs the outcome in this request (show balance, unlock UI, chain the next post, fail the HTTP call together) | Synchronous | skip_queue: true |
| Next step can continue without waiting; apply can finish in the background | Async | skip_queue: false |
Do not inherit “whatever the SDK omits.” Set the flag on purpose and record why for that call.
Docs: Concurrency, Transaction lifecycle, Queue config.
Mental model
Decide this first, for each API call in the journey (ask in plain language):
After this call returns, does the next step already need to know the ledger result?
Follow how-to-ask.md. Walk the flow step-by-step in simple words (“Does checkout need the answer right away?”). Sync on one side does not imply sync on the rest.
Assume and confirm for familiar patterns:
| Step | Likely choice | Why |
|---|
| Card auth (create inflight hold) | Sync | Issuer / checkout needs approve/decline in the request |
| Card settlement (commit / void / capture) | Often async | Clearing can finish in the background; notify via webhook/poll |
| Checkout debit the customer sees immediately | Sync | Next step is the user-facing result |
| Payout “submitted” then partner settles later | Async | Next step is acceptance, not final rail settle |
| Internal bookkeeping with no waiting caller | Async | No immediate next-step dependency |
Propose the table, then ask them to correct any row. Do not re-interview every step from scratch when the pattern is clear.
Load the blnk-inflight skill for auth → commit/void mechanics; keep queueing decisions independent per call.
When mapping, label each edge/step with sync or async. Example:
card_auth (inflight create): skip_queue: true
card_capture (commit): skip_queue: false
card_release (void): skip_queue: false
Hard rules
- No product default. Every mapped step gets an explicit sync or async choice.
- Decide from that step’s next dependency, not from sibling calls. Auth needing sync does not force settlement to sync.
- Async: HTTP/SDK success ≠ money applied (or commit finished). Confirm via webhooks (preferred) or poll-by-reference. Load the
blnk-webhooks skill.
- Sync: design the request path around the response outcome; still use unique deterministic
reference (blnk-naming-patterns).
- Record the per-step table on the map / in
.blnk_context/ (load blnk-documentation).
After you choose
For each step:
Then apply secondary constraints on sync steps that are hot:
Anti-patterns (do not)
- Leaving
skip_queue undecided (“we’ll see”)
- Applying one flag to the whole product because one step needed sync
- Choosing async but treating create/commit success as final without confirmation
- Choosing sync only to avoid building webhook/poll confirmation when that step did not need immediacy
- Sync on a hot path with no lock wait timeout or reference-safe retries
- Jumping to balance sharding without confirming with the user and trying lock wait + retries first
- Blind retry with a new
reference after timeout
- Mixing sync/async on a journey without documenting which step is which
Persist
Write the per-step sync/async table with the blnk-documentation skill (next free NN_<slug>.md).
