Build the StarIntel billing ledger and payment state machine #1

New issue

Open

opened 2026-08-25 10:52:57 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-25 10:52:57 +00:00

(Migrated from github.com)

Goal

Build the canonical StarIntel billing domain in starintel-biz. This issue owns provider-neutral billing state, money/accounting semantics, and webhook-driven payment transitions; Stripe and crypto integrations are separate adapters.

Core model

Define stable entities and invariants for at least:

customer/account
product/plan/price
subscription
invoice
payment attempt
payment/refund/credit
entitlement grant/revocation reference
provider event/idempotency record
money amount + currency

Requirements

StarIntel owns canonical billing/subscription state; payment providers own payment-method/card/crypto-processing details.
Use integer minor units or another exact decimal representation; never binary floating point for money.
Every external payment/event transition is idempotent by provider + event/payment identity.
Explicit state machine for invoice/payment/subscription transitions; impossible transitions fail closed rather than being silently coerced.
Preserve an append-only audit/event history sufficient to explain how current state was derived.
Reconcile asynchronous provider events, duplicate delivery, out-of-order events, retries, refunds, disputes/reversals, partial failures, and provider outages.
Separate billing truth from application entitlements: billing produces normalized subscription/payment state; entitlement projection is a separate issue.
No PAN/card secrets, crypto private keys, API keys, webhook secrets, or sensitive provider payloads in the application database/logs beyond the minimum safe identifiers needed.
Emit structured billing/audit events suitable for the StarIntel syslog contract without leaking customer/payment secrets.
Define retention/privacy boundaries for customer billing metadata.

Interfaces

Provide a provider-neutral internal API/service boundary for adapters to submit verified normalized events and for authorized StarIntel services to query billing/subscription state. Do not let webhooks directly mutate arbitrary application state.

Tests / acceptance

deterministic state-machine fixtures for initial purchase, recurring renewal, failed payment, retry, cancellation, refund, reversal/dispute, duplicate event, and out-of-order delivery
money/currency arithmetic property tests
crash/replay recovery is idempotent
audit history reconstructs current state
secret/redaction fixtures pass
repo-native checks pass at exact PR HEAD

Execution mode — AUTO-RAGE

Run the full ADARD/ADADR loop autonomously: inspect the empty/current repo and adjacent StarIntel auth/account contracts; research current payment-domain patterns; design and record the canonical billing model; adversarial review + accounting/idempotency/privacy threat model; autonomous decision gate; TDD-first implementation; exact-head verification; push a focused branch and open/update a PR targeting main. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

## Goal Build the canonical StarIntel billing domain in `starintel-biz`. This issue owns provider-neutral billing state, money/accounting semantics, and webhook-driven payment transitions; Stripe and crypto integrations are separate adapters. ## Core model Define stable entities and invariants for at least: - customer/account - product/plan/price - subscription - invoice - payment attempt - payment/refund/credit - entitlement grant/revocation reference - provider event/idempotency record - money amount + currency ## Requirements - StarIntel owns canonical billing/subscription state; payment providers own payment-method/card/crypto-processing details. - Use integer minor units or another exact decimal representation; never binary floating point for money. - Every external payment/event transition is idempotent by provider + event/payment identity. - Explicit state machine for invoice/payment/subscription transitions; impossible transitions fail closed rather than being silently coerced. - Preserve an append-only audit/event history sufficient to explain how current state was derived. - Reconcile asynchronous provider events, duplicate delivery, out-of-order events, retries, refunds, disputes/reversals, partial failures, and provider outages. - Separate billing truth from application entitlements: billing produces normalized subscription/payment state; entitlement projection is a separate issue. - No PAN/card secrets, crypto private keys, API keys, webhook secrets, or sensitive provider payloads in the application database/logs beyond the minimum safe identifiers needed. - Emit structured `billing`/audit events suitable for the StarIntel syslog contract without leaking customer/payment secrets. - Define retention/privacy boundaries for customer billing metadata. ## Interfaces Provide a provider-neutral internal API/service boundary for adapters to submit verified normalized events and for authorized StarIntel services to query billing/subscription state. Do not let webhooks directly mutate arbitrary application state. ## Tests / acceptance - deterministic state-machine fixtures for initial purchase, recurring renewal, failed payment, retry, cancellation, refund, reversal/dispute, duplicate event, and out-of-order delivery - money/currency arithmetic property tests - crash/replay recovery is idempotent - audit history reconstructs current state - secret/redaction fixtures pass - repo-native checks pass at exact PR HEAD ## Execution mode — AUTO-RAGE Run the full ADARD/ADADR loop autonomously: inspect the empty/current repo and adjacent StarIntel auth/account contracts; research current payment-domain patterns; design and record the canonical billing model; adversarial review + accounting/idempotency/privacy threat model; autonomous decision gate; TDD-first implementation; exact-head verification; push a focused branch and open/update a PR targeting `main`. Stop only for a genuinely unresolved requirement/security blocker, inaccessible dependency, or failed verification gate. Do not ask for approval between phases.

lost-rob0t commented

2026-08-25 10:58:39 +00:00

(Migrated from github.com)

Documentation for the billing architecture, state machine, provider boundaries, operations, recovery, security/privacy, and diagrams is tracked in #5. Treat the documented contracts/runbooks as part of the completion surface for this billing core.