Contract v1 · generated reference

RuntimeHandler.paymentsCaptureRedrive

OP-RUNTIME-PAYMENTS-CAPTURE-REDRIVE is a scheduled operation owned by Traveler.

Authority and transport

Actor: Firebase scheduler
Authentication: platform invocation
Authorization: platform-only
Resource boundary: server-derived from verified payload and stored state
Transport: SCHEDULED
Deployed export: paymentsCaptureRedrive
Trigger: onSchedule; schedule "every 5 minutes" Etc/UTC; retryCount 3
App Check: NOT_APPLICABLE
Canonical source: functions/src/properties/traveler/payments/capture.ts

Request schema

This operation accepts no client-supplied request parameters. Its managed platform trigger and recovery behavior are documented below.

Response schema

Promise<void> managed scheduler acknowledgement

States, consistency and recovery

State path: SCHEDULED → BOUNDED_REQUESTED_ROW_SCAN → PER_ROW_CAPTURE_CORE → CAPTURED_OR_LEFT_REQUESTED → STALLED_OR_FROZEN_SIGNALLED → PLATFORM_RETRY
Reads: at most 20 REQUESTED capture rows older than two minutes, oldest first, plus each row's saga and provider pre-flight
Writes: per-row capture through the same core as the trigger; attempts and last error on rows that fail
Transaction: per-row isolation: one row's infrastructure failure is counted on that row and the batch continues
Idempotency: safe bounded rerun; the capture idempotency key {sagaId}:CAPTURE prevents a second charge
Concurrency: saga lease with fencing token per row
Retry/replay: Firebase scheduler retryCount is 3; each five-minute run converges the remaining rows
Rate limits: Managed schedule only; there is no public caller quota.
Audit: per-row outcome and attempts; a stalled row raises payments.capture_request_stalled

Error contract

No public error envelope; a thrown execution failure is governed by the scheduler's configured retry policy. Never treat an unknown error as success.

No public error code is exposed by this managed trigger.

Producer test references

Evidence tier: SEMANTIC_CORE_REFERENCE.

Reviewer-mapped semantic/core references

functions/test/recovery-settlement.test.js
- S2 the capture producer: provider outage leaves the row REQUESTED; a reachable provider captures once
- S8 producer resilience (adversarial review 2026-09-04): live lease → LEASE_BUSY; lapsed RUNNING is re-driven; an escaping throw is counted, not SKIPPED; a cancelled intent is SKIPPED without a capture

Each cited test name is checked against the referenced file by the documentation suite, so a renamed or removed producer test breaks this page instead of leaving a stale claim.

Protocol or inventory references

functions/test/estate-service-inventory.js

These references prove export, wrapper or protocol behavior only. They are not counted as complete operation semantics.

Example availability

NOT_PUBLIC_TRANSPORT: This handler is provider- or platform-invoked and has no public client invocation.

Common integration contract

Sandbox and Production are isolated

Run examples only in a governed sandbox or local emulator. Sandbox identities, App Check tokens, payment fixtures and data do not grant Production access. The typed ports do not ratify a public numeric quota; enforcement may be stricter. Honor RATE_LIMITED and the server's retry-after value.

Authentication and authorization

Firebase Auth proves identity. App Check proves the approved app where a callable requires it. Roles, organization membership, requester identity and resource ownership are derived and rechecked by the server.

Authentication guide

Errors and recovery

Stable error codes distinguish validation, denial, conflict, expiry, authority pending, rate limiting and temporary unavailability. Never infer success from an HTTP redirect or a browser state.

Error catalogue

Idempotency, concurrency and retry

Reuse an idempotency key only for an identical retry. A new intent needs a new key. Preserve version preconditions and reload after a conflict.

Retry guidance

Changes and escalation

Check compatibility before adopting a new contract version. Review the changelog, service status and support guidance before retrying a persistent failure.

Changelog Service status Developer support

Common failure families
Family	Client decision
Authentication / authorization	Refresh or step up only when instructed; do not retry a denial unchanged.
Validation / conflict / expiry	Correct or reload state, then obtain confirmation for a new intent.
Rate limited / unavailable	Honor retry-after and use bounded backoff; inspect service status.
Unknown / server	Fail closed and escalate with a privacy-safe correlation id.

Executable network examples are published only when the exact wire schema is producer-proven. Check the selected operation's example-availability status; an unresolved schema is a release blocker, not permission to guess.

Verified examples and local-only recovery snippets