Planning and execution tracking — what is PLANNED
| Capability | Status | Progress | Est. Hours | Assigned To |
|---|---|---|---|---|
|
Billing Executions Schema
billing_executions table with tenant_id, entity_contract_id, plan_contract_id, amount, currency, Citus-ready indexes
|
Completed |
100%
|
0h | — |
|
6-State Execution Machine
created -> pending -> processing -> completed|failed. Pending settlement: processing -> pending. Cancel: created|pending -> canceled
|
Completed |
100%
|
0h | — |
|
Triple-Layer Idempotency
App-level check + DB ON CONFLICT (idempotency_key partial unique) + WHERE status guard. Pending included in duplicate detection.
|
Completed |
100%
|
0h | — |
|
DB Immutability Enforcement
Trigger: terminal row protection (completed/failed/canceled), valid-only transitions, processing->pending allowed for async
|
Completed |
100%
|
0h | — |
|
Append-Only Lifecycle Event Store
BillingExecutionEventRepository — every state transition records type, old_status, new_status, metadata, user_id, correlation_id
|
Completed |
100%
|
0h | — |
|
Transactional Outbox Pattern
Dual-write: execution state + outbox event in same DB transaction. Events carry payment_rail, payment_provider, idempotency_key.
|
Completed |
100%
|
0h | — |
| Capability | Status | Progress | Est. Hours | Assigned To |
|---|---|---|---|---|
|
Authoritative Workflow Write Path
recordWorkflowEventTransactional() writes to billing.contract_term_datetimes inside DB transaction. AUTHORITATIVE_WRITE_ENABLED=true.
|
Completed |
100%
|
0h | — |
|
BillingWorkflowConfig Canonical Key
Centralized config: workflow key wf:billing.execution, 8 phase codes, target table, default source. Single source of truth.
|
Completed |
100%
|
0h | — |
|
Stateless Context Propagation
WorkflowWriteContext VO: serviceDefault(), webhook(provider), user(userId), system(). Passed explicitly at every call site.
|
Completed |
100%
|
0h | — |
|
Full Transition Coverage
All 9 repository transition methods emit workflow events: markPending, markProcessing, markCompleted, markFailed, markCanceled, confirmFromPending, rejectFromPending, settleFromProcessing, reconcile
|
Completed |
100%
|
0h | — |
|
Historical Event Backfill
Backfill migration creates contract_term_datetimes rows for all existing executions with deterministic SHA-256 transition IDs
|
Completed |
100%
|
0h | — |
| Capability | Status | Progress | Est. Hours | Assigned To |
|---|---|---|---|---|
|
Provider-Agnostic Webhook Handler
/api/v1/billing/webhook/{provider} — idempotent, extracts event_type/reference_id, dispatches confirmation/rejection
|
Completed |
100%
|
0h | — |
|
Webhook Signature Verification
Per-provider HMAC-SHA256 verification of webhook payload. Skeleton in place; needs provider-specific signing keys.
|
In progress |
40%
|
0h | — |
|
Pending Reconciliation Worker
Polls findPendingForReconciliation(), calls checkStatus() per rail, transitions pending->completed or pending->failed
|
Completed |
100%
|
0h | — |
|
Transient Failure Retry Strategy
Exponential backoff for isRetryable() failures. Max retries per rail, dead-letter after exhaustion.
|
Pending |
0%
|
0h | — |
|
Billing Structured Observability
billing.execution.result + billing.rail.execution structured log events with duration_ms, rail, provider, correlation_id
|
Completed |
100%
|
0h | — |
| Capability | Status | Progress | Est. Hours | Assigned To |
|---|---|---|---|---|
|
Payment Instrument Entity (Contract Pattern)
Model payment methods as contract pattern entities with tokenized storage via contract_term_attrs
|
Pending |
0%
|
0h | — |
|
3D Secure Authentication Flow
3DS challenge flow for card payments: enroll check, challenge redirect, result verification
|
Pending |
0%
|
0h | — |
|
Risk Assessment and Velocity Check
Pre-execution risk scoring: velocity limits, amount thresholds, fraud signals, device fingerprinting
|
Pending |
0%
|
0h | — |
|
Settlement Reconciliation Reports
Daily/weekly reconciliation between internal records and provider settlement files. Discrepancy flagging.
|
Pending |
0%
|
0h | — |
|
Financial Compliance Audit Trail
PCI-DSS Level 1 evidence: all cardholder data access logged, tokenization enforced, audit trail for regulatory inquiry
|
Pending |
0%
|
0h | — |