Pricing calculation audit trail — Phase 1 capture

Freezes a typed, reproducible trace of the pricing engine's output at every SAVE, so any displayed TCV/ARR can be explained exactly — without an engineer reconstructing the math by hand.

1. Why this exists

Sales and finance regularly ask "why does this quote's TCV/ARR show this number? I think it's off." Today, answering means an engineer reruns the pricing engine in their head against a snapshot of inputs and a snapshot of engine code that may have already moved on. The answer is slow, manual, and not reproducible.

This PR is Phase 1 of rfcs/2026-05-29-pricing-calculation-audit-trail.md. It builds the foundation — the collector, the tree builder, the persistence model — and wires it into the SAVE milestone on both quote-creation paths. There is no read API and no UI yet; that's Phase 2.

2. How a SAVE flows, end to end

Use the carousel to step through one quote save with the flag enabled. The engine path is unchanged; what's new is the collector injected into peLogger, and the best-effort write at the end.

3. The two SAVE call sites

Wiring is identical on both paths. Build a collector iff the flag is on for the org; pass it through the engine; capture against the final summary after persistence.

const traceEnabled = await
  isPricingCalculationTraceEnabledForOrg(
    { organizationId, userId });
const traceCollector = traceEnabled
  ? new TraceCollector() : undefined;

const pricingEngineSummary =
  await PricingEngineSummary.calculateSummary(
    calculationInput,
    traceCollector
      ? { peLogger: traceCollector }
      : undefined,
  );

// …amendment override, persist quote…

if (traceCollector) {
  await captureCalculationTrace({
    organizationId,
    pricingQuoteId: createdQuote.id,
    trigger: 'SAVE',
    effectiveInput: inputWithDefaults,
    summary: pricingEngineSummary,
    collector: traceCollector,
  });
}

const updateTraceEnabled = await
  isPricingCalculationTraceEnabledForOrg({
    organizationId: ctx.organization.id,
    userId: ctx.user.id,
  });
const updateTraceCollector = updateTraceEnabled
  ? new TraceCollector() : undefined;

const finalPricingEngineSummary =
  await PricingEngineSummary.calculateSummary(
    summaryInputUpdate,
    updateTraceCollector
      ? { peLogger: updateTraceCollector }
      : undefined,
  );

// …amendment override, persist quote…

if (updateTraceCollector) {
  await captureCalculationTrace({
    organizationId: ctx.organization.id,
    pricingQuoteId: id,
    trigger: 'SAVE',
    effectiveInput: finalMergedInput,
    summary: finalPricingEngineSummary,
    collector: updateTraceCollector,
  });
}

4. The peLogger seam, before and after

The engine already accepts a peLogger on FormulaEvaluateAttr for Datadog logging. This PR adds an optional event() sibling. PricingEngineLogger doesn't implement it; TraceCollector does. Engine call sites guard with peLogger?.event?.(…).

peLogger?: {
  log: (message: string,
    meta?: Record<string, unknown>) => void;
  invocationId: string;
};

peLogger?: {
  log: (message: string,
    meta?: Record<string, unknown>) => void;
  invocationId: string;
  // NEW — optional, guarded at call sites
  event?: (event: TraceEventInput) => void;
};

export type PricingEnginePeLogger =
  NonNullable<FormulaEvaluateAttr['peLogger']>;

The new calculateSummary signature accepts an injected logger by this structural type — so neither concrete implementation is coupled to the other.

static async calculateSummary(
  input: PricingEngineSummaryInput,
  options?: { peLogger?: PricingEnginePeLogger },
): Promise<PricingEngineSummaryOutput> {
  // …
  const peLogger = options?.peLogger ?? new PricingEngineLogger();
  // …
}

5. Building the tree

The tree is built from the final summary (post amendment override), not from the live event stream. That is the entire reason the trace's TCV/ARR can never disagree with the displayed numbers — they are literally the same values, threaded into a structured shape.

Any line-item events the collector picked up during the run are merged in as deeper detail, attached by parentKey === 'product:<id>'. Unmatched events attach at the root.

Shape produced

Visibility

Every node carries a visibility flag — customer for price × volume × term × discount facts, internal for cost, margin, and engine fallbacks. The future explain UI will gate on this.

6. Reproducibility: inputHash and stableStringify

The trace row is keyed on (pricingQuoteId, inputHash, trigger) for dedup. The hash has to survive a Postgres round-trip — an in-memory input and the same input loaded back from JSONB must produce the same hash. JSON.stringify alone is not enough.

// stableStringify({ b: 1, a: 2 }) === stableStringify({ a: 2, b: 1 })
// stableStringify({ a: 1, b: undefined }) === '{"a":1}'
// stableStringify(new Date(...)) === '"2026-05-29T00:00:00.000Z"'

7. The persistence model

8. Safety — failure modes and the flag

9. What it doesn't change

10. Follow-ups (Phase 2 / 3)

11. Open questions for review