A PSP-agnostic credit ledger
built for global SaaS scale.

Section 2 · PSP-Agnostic Invariant (PAYG §9.6)

The single foundational rule. Zero Stripe imports in the ledger. Architect

Per PAYG §9.6: the credit ledger (credit-engine.ts, credit-service.ts, complexity-calculator.ts, and the data-model tables themselves) contains zero PSP-specific types, IDs, or imports. Stripe is isolated to stripe-credits.ts + the webhook handler file. This is checked mechanically in the Phase 3 hand-test by grepping every file under lib/billing/ for import.*stripe; exactly one file matches.

flowchart LR
    subgraph PSP["PSP Layer (isolated)"]
        SC[stripe-credits.ts]:::psp
        WH[webhooks/stripe/route.ts]:::psp
    end

    subgraph CORE["Credit Ledger Core — PSP-AGNOSTIC"]
        CE[credit-engine.ts
reserve / settle / release]:::core
        CS[credit-service.ts
DB-driven config lookup]:::core
        CC[complexity-calculator.ts
10-factor + log₂]:::core
        DB[(Tables
CreditTransaction
TenantCreditBalance
CreditReservation)]:::db
    end

    subgraph FUTURE["Future PSPs (drop-in, v1.5+)"]
        RZ[razorpay-credits.ts
v1.5 India]:::future
        CB[chargebee-bridge.ts
v2 Enterprise AR]:::future
        PD[paddle-credits.ts
v3 MOR]:::future
    end

    WH --> SC
    SC -- "topUpCreditsFromPurchase(
purchaseId, pspPaymentId)" --> CE
    CE --> CS
    CE --> CC
    CE --> DB
    RZ -. "same entry point" .-> CE
    CB -. "same entry point" .-> CE
    PD -. "same entry point" .-> CE

    classDef psp fill:#3f1d1d,stroke:#fb7185,color:#fff;
    classDef core fill:#0d1a0d,stroke:#a3e635,color:#fff;
    classDef db fill:#0d1a0d,stroke:#a3e635,color:#fff,stroke-dasharray:4 2;
    classDef future fill:#1e2a3a,stroke:#38bdf8,color:#fff,stroke-dasharray:4 2;
                

Section 4 · 20% Value-Capture Pricing (PAYG §5.0)

Credits priced at 20% of equivalent manual labour cost. CXO Sales

Every credit-bearing activity is priced as a fraction of the documented manual cost to produce the same outcome. This is the foundation of the pricing model and the 95–99% gross margin. Internal/LLM cost is irrelevant to what the customer is charged — what they're charged is anchored to their alternative.

baseCredits = round(manualCostBasisUSD × captureRatePct)
            where captureRatePct defaults to 0.20
            (negotiable 0.15–0.25 per TenantCreditContract)

Sampled activity prices (matches seed)

Section 6 · 10-Factor Complexity Multiplier (PAYG §5.8.4–5)

10 runtime dimensions. Weighted sum. log₂ dampening. Clamped. Architect Finance

Per-execution complexity is derived from 10 runtime dimensions captured by the workflow runner. Each is normalised against the activity's baseline profile, capped to prevent any one dimension from dominating, weight-summed, then logarithmically dampened. The result is multiplied onto the base credits.

The formula

// For each dimension i:
normalized_i  = actual_i / baseline_i              // baseline per activity
factorScore_i = min(normalized_i, capMultiplier_i) // per-factor cap
weightedSum  += factorScore_i × weight_i           // platform defaults sum to 1.00

complexityScore       = weightedSum / Σ(weight_i)
rawMultiplier         = log₂(complexityScore + 1) × 1.44   // scalingConstant
complexityMultiplier  = clamp(rawMultiplier,
                              contract.minComplexityMultiplier,  // default 0.5
                              contract.maxComplexityMultiplier)  // default 3.0

Default factor weights

Final credit formula

finalCredits = round(
  baseCredits
  × complexityMultiplier        // from runtime metrics (this section)
  × customerTierMultiplier      // from TenantCreditContract.customerTierKey (§5)
  × globalCreditMultiplier      // volume discount
  × (isByollm ? byollmMultiplier : 1.0)
)

Section 8 · Reserve → Settle → Release Lifecycle (PAYG §8.3)

Worst-case hold, actual deduction, automatic release. Zero charge for failed jobs. Architect

Every credit-bearing execution follows this lifecycle. Reserve happens before work starts and holds the worst-case against the balance. Settle happens at successful completion and computes the actual via complexity. Release returns the full reservation if execution fails — customers never pay for our failures.

sequenceDiagram
    autonumber
    participant U as User
    participant API as /api/…
    participant CE as credit-engine
    participant DB as Ledger DB

    U->>API: Approve & Run Now (executionId)
    API->>CE: reserveCredits(executionId, baseCredits)
    CE->>DB: read TenantCreditContract + Config (5-min cache)
    CE->>DB: compute maxReserve, write CreditReservation(HELD)
    CE-->>API: ok, balance debited by maxReserve

    Note over U,DB: Workflow executes…

    alt success
        API->>CE: settleCredits(executionId, runtimeVector)
        CE->>DB: complexity calc, write CreditTransaction(DEDUCTION)
        CE->>DB: flip CreditReservation to SETTLED + release unused
        CE-->>API: settled = actualCredits
    else failure
        API->>CE: releaseReservation(executionId)
        CE->>DB: flip CreditReservation to RELEASED_ON_FAILURE
        CE->>DB: full reservedCredits returned to balance
        CE-->>API: zero charged
    end

    Note over CE,DB: Idempotency: @@unique(executionId, type)
second settle / release call → no-op
                

Reserve at worst case

maxReserve = baseCredits
           × maxComplexityMultiplier   // from contract, default 3.0
           × customerTierMultiplier    // e.g. 1.30 for MULTINATIONAL
           × globalCreditMultiplier    // volume discount, e.g. 0.80 for Scale-pack

Idempotency guard

Every CreditTransaction row has a unique index on (executionId, type). The first settleCredits call inserts a DEDUCTION row. A second call for the same executionId raises a unique-constraint violation; the engine catches it and returns {alreadySettled: true}. No double-charge possible — verified in the Phase 2 hand-test (PR #29).

Section 10 · DB-Driven Configuration Principle (PAYG §8.1 #2)

Zero hardcoded credit constants in code. Everything from the database. Architect

Every credit value — base credits per activity, factor weights, complexity baselines, tier multipliers, included-credits-per-plan, BYOLLM multipliers — lives in DB tables. Tenant-specific contract overrides (negotiated capture rates, flat pricing for regulated industries) take effect immediately, without code deploys.

What this means in practice

• lib/billing/credit-engine.ts calls resolveWorkflowCreditConfig() + resolveTenantContract() — never imports a constant
• No const PROBE_DISCOVERY_BASE_CREDITS = 100 anywhere in lib/billing/
• 5-min in-memory LRU cache on lookup; invalidateCreditCaches(tenantId) exposed for hot-reload after contract edits
• Postgres NULLS LAST ordering (orderBy: [{ tenantId: { sort: "desc", nulls: "last" } }]) — tenant override row sorts before the platform default
• Re-running prisma/seed/credit-packs.ts + prisma/seed/workflow-credit-config.ts is idempotent on the unique key — safe for production

Section 12 · Webhook Event Handling

Three handled events. At-least-once delivery. Idempotent by construction. Architect

POST /api/billing/webhooks/stripe is the single webhook endpoint. Forces Node runtime (raw body required for HMAC), dynamic = "force-dynamic" (no caching), 400 on signature failure (Stripe retries), 200 on every successfully-ingested event (handled or ignored — non-2xx would trigger infinite retries for events we never plan to handle).

Section 14 · Phased PSP Roadmap (PAYG §9.4)

v1 Stripe. v1.5 Razorpay. v2 Chargebee. v3 Paddle MOR. Each adds without breaking. Sales Finance

Each PSP addition is approximately one new file + one new webhook route + one IAM secret reference. The credit ledger doesn't move. The customer-facing UI doesn't change. Triggers are revenue-mix driven, not engineering-driven — we add the PSP when the customer base or revenue mix justifies the operational cost.

Section 16 · Internal Surface — /admin/billing-internal

Four tabs. iArchitron-only. Behind hasAdminAccess. Architect Finance

The internal dashboard for iArchitron ops + finance. The four APIs (margin-analytics, anomalies, stripe-reconciliation, finance-export) are all gated at the route level — non-admin authenticated callers get 403. The Phase 6 hand-test (PR #33) asserts this for every endpoint.

Section 18 · Worked Example — Full Lifecycle

PostgreSQL DataProbe + Hierarchy Synthesis end-to-end. $0.24 internal cost. CXO Finance

Scenario: 200 tables, 50 stored procedures (10 require AI summarisation), 4 EA artefacts drafted per tech across 7 techs (subset). Tenant on MULTINATIONAL tier (×1.30) with 20% Scale-pack discount (globalCreditMultiplier = 0.80), non-BYOLLM, complexity enabled.

Step 1 — Base credits (from WorkflowCreditConfig)

Step 2 — Worst-case reservation (at "Approve & Run Now")

maxReserve = 700 × 3.0 × 1.30 × 0.80 = 2,184 credits  // ≈ $1,747 at Scale-pack rate

Step 3 — Runtime metrics + complexity score

rawMultiplier        = log₂(3.225 + 1) × 1.44 = log₂(4.225) × 1.44 = 2.99
complexityMultiplier = clamp(2.99, min=0.5, max=3.0) = 2.99

Step 4 — Final settle

finalCredits = round(700 × 2.99 × 1.30 × 0.80) = round(2,177.4) = 2,177

Step 5 — Margin (iArchitron-only, never customer-facing)

creditsBilled        = 2,177
internalCostUSD      = $0.18 LLM + $0.04 compute + $0.02 storage = $0.24
usdEquivalent        = 2,177 × $0.80/credit = $1,741.60
grossMarginPct       = ($1,741.60 − $0.24) / $1,741.60 = 99.99%

Section 20 · Glossary

Billing vocabulary for LLM grounding + onboarding. LLM Finance

Credit

The platform unit of customer-facing billing. One credit = one USD at base rate ($1.00), discounted by volume pack tier (down to $0.60/credit on Strategic Annual).

Activity

A credit-bearing workflow type (e.g. architecture-document, compliance-report, probe-discovery-run). Each has a row in WorkflowCreditConfig with manual cost basis + capture rate + base credits.

Manual Cost Basis

The documented USD cost of producing the equivalent outcome manually (e.g. $4,000 for an architecture document = 40 hours × $100/hr EA consultant). Anchors the credit price.

Capture Rate

The fraction of manual cost basis charged as credits. Default 0.20 (20%). Negotiable 0.15–0.25 per TenantCreditContract. baseCredits = round(manualCostBasisUSD × captureRatePct).

Base Credits

The fixed pre-multiplier credit cost of an activity. Stored in WorkflowCreditConfig.baseCredits.

Customer Tier

Five-tier structural-overhead classification: INDIVIDUAL (0.75) → SMB (0.90) → ENTERPRISE (1.00) → MULTINATIONAL (1.30) → MISSION_CRITICAL (1.60). Set per tenant at contract time.

Complexity Multiplier

Runtime-derived multiplier from 10 factors (child count, token intensity, context size, etc.), per-factor capped, weight-summed, then log₂(score+1) × 1.44 dampened, clamped to [contract.min, contract.max].

Global Multiplier

Volume discount applied per TenantCreditContract.globalCreditMultiplier. Reflects pack tier (e.g. 0.80 for Scale-pack = 20% off; 0.65 for Enterprise-pack = 35% off).

BYOLLM

Bring-Your-Own-LLM. Tenant supplies their own LLM API keys; pays reduced credit rate (0.62× default) + 15% license discount. Tenant.byollmEnabled = true.

Reservation

Pre-execution credit hold (worst-case). Row in CreditReservation with status HELD → SETTLED or RELEASED_ON_FAILURE.

Settle

Post-execution computation of actual credits via complexity multiplier; writes CreditTransaction(DEDUCTION) + flips reservation to SETTLED + returns unused to balance.

Release

Post-execution full reservation return on failure. Writes nothing to CreditTransaction (no DEDUCTION). Zero credits consumed.

Top-up

Credit grant from a pack purchase. Writes CreditTransaction(TOPUP) with executionId = "purchase:" + purchaseId + type=TOPUP for idempotency.

Two-Layer Measurement

The PAYG §7.0 invariant separating internal telemetry (WorkflowExecutionTelemetry with compute units, tokens, LLM cost, gross margin %) from customer-facing credits (CreditTransaction). The two never cross.

PSP

Payment Service Provider. Stripe in v1; Razorpay (v1.5), Chargebee (v2), Paddle (v3) on the roadmap.

PSP-Agnostic Invariant

Per PAYG §9.6: the credit ledger (credit-engine.ts, credit-service.ts, complexity-calculator.ts) contains zero PSP-specific types/IDs/imports. Mechanically verified in the hand-test.

MOR (Merchant of Record)

A payment processor (e.g. Paddle) that takes seller-of-record responsibility — handling sales tax, VAT, GST registrations across all jurisdictions in exchange for a higher per-transaction fee. v3 evaluation.

Webhook Idempotency

The property that processing the same event twice has no additional effect. Achieved via @@unique(executionId, type) on CreditTransaction. Stripe delivers at-least-once; we accept that without double-crediting.

DB-Driven Configuration

Per PAYG §8.1 #2: zero hardcoded credit constants in code. All values come from WorkflowCreditConfig, WorkflowComplexityProfile, ComplexityFactorConfig, TenantCreditContract rows. Pricing committee can change values via seed-script re-run; no application redeploy.

Flat Pricing

For regulated industries (financial services, government, healthcare): TenantCreditContract.flatPricingEnabled = true → complexity multiplier always returns 1.0. Predictable bill, no scope-based variability.

Anomaly

One of 4 flagged conditions surfaced on /admin/billing-internal Anomalies tab: low-margin tenant, failed purchase, unresolved deficit, large refund.

Reconciliation

The process of matching internal ledger entries (CreditPackPurchase) against PSP payment records (Stripe payouts). v1: ledger inspection only. v1.5: stripe.payouts.list roundtrip + line-item match.