Pricing calculation audit trail (RFC)

Design doc proposing a typed, milestone-frozen trace of every pricing decision so disputes about quote numbers can be answered exactly — even weeks later.

1. Why this exists

The Dealops 2 pricing engine already funnels every TCV/ARR computation through one orchestrator (PricingEngineSummary.calculateSummary) and one service (PricingEngineService). A peLogger seam is already threaded through every layer. The architecture is ready — two things are missing.

2. Locked-in decisions vs. open questions

3. The trace, as a typed tree

New types in packages/types/v2/. A tree of TraceNodes — renderable as a drill-down waterfall, diffable between two quotes.

Sample shape

type TraceNode = {
  kind: TraceNodeKind;
  label: string;                      // "Product: Card Issuing"
  inputs: Record<string, unknown>;    // { volume: 1200, tierBounds: [1000, 5000] }
  output?: AnnotatedNumber;
  source?: { kind: 'pricebook_row' | 'variable' | 'product_input'; id: string };
  note?: string;                      // "monthly-min tier not found → selfServe"
  visibility: 'internal' | 'customer';
  children: TraceNode[];
};

What a trace looks like, sketched

4. Capturing it — enrich the existing seam

A TraceCollector is a peLogger (same log() interface, so existing call sites still feed Datadog) and adds structured event(node, parentId?) + scoped withNode(node, fn). Injected exactly where PricingEngineLogger is constructed today.

5. Persisting it — at milestones, atomically

A new table written inside the existing withPlatformEvents transaction, so the trace commits atomically with the milestone’s PlatformEvent. Never a milestone without its trace, never an orphan trace.

model PricingCalculationTrace {
  id             String   @id @default(uuid())
  organizationId String
  pricingQuoteId String

  trigger    TraceTrigger        // SAVE | APPROVAL_SUBMIT | CRM_PUSH
  capturedAt DateTime @default(now())

  // Reproducibility / drift detection
  engineVersion  String           // git SHA
  inputHash      String           // hash of effectiveInput (+ spec/pricebook versions)
  effectiveInput Json             // the augmented input actually fed to the engine

  // Denormalized top-line: fast list reads, drift checks, indexing
  tcv Json
  arr Json

  invocationId String              // ties trace ↔ the Datadog peLogger run
  trace        Json                // the TraceNode tree

  @@unique([pricingQuoteId, inputHash, trigger]) // dedupe identical re-saves
  @@index([pricingQuoteId, capturedAt])
}

6. Reading it back — explainQuote

A new tRPC procedure on the pricingEngine router. The branch logic encodes the ephemeral-vs-stored decision.

explainQuote({ pricingQuoteId, atTrace?: traceId })

  if atTrace provided OR the quote is in a historical/locked state:
      → return the STORED PricingCalculationTrace (exact-match history)
  else (live/edited draft):
      → recompute calculateSummary with a TraceCollector,
        return the tree, persist NOTHING

“Locked” keys off existing signals: PricingQuote.isLocked / isDocuSignLocked and the presence of milestone traces.

7. Rollout — history-capture first

The unusual part: persistence ships before the UI, because traces cannot be backfilled. Step through the phases below.

8. Alternatives considered

9. Risks & mitigations

10. What this RFC does not change

11. Open questions (explicitly deferred)

12. Feedback wanted