Backend CRM formula writeback with release snapshots

This PR lets Dealops 2 CRM writeback fields use published runtime formulas, while evaluating every formula against one immutable organization release before any CRM mutation.

Author: @mehulshinde PR: dealops#7618 Branch: mehul/dea-8099-formula-writeback State: open Files: 56 Diff: +4478 / -288 Ticket: DEA-8099

What it adds

Runtime formulas become a new CRM writeback value source for quote, product, and emitted-row scopes.

Outputs are typed and converted before CRM payload construction.

What it protects

All formula fields are evaluated and validated before the first CRM write.

If a gate, binding, release, parameter, or formula output is invalid, the push fails with no CRM egress.

What it snapshots

Writeback mappings are pinned into org releases beside the formula manifest.

Rollback restores the destination mapping and formula revision set together.

Rollout posture

The org setting runtimeFormulaWritebackEnabled defaults off.

The admin UI, rollout tooling, and migration parity work are deferred to #7666.

Runtime formula
Writeback spec
Org release
StandardWriteBack
CRM mutation
Diff note: the provided diff is truncated, so this explainer is based on the PR description, file list, and visible diff hunks. It does not claim to cover unseen lines in the remaining files.

1. Why this exists

Before

CRM writeback fields were mostly direct copies, calculated legacy sources, literals, references, or product/quote paths.

Custom CRM-only calculations needed to be encoded as writeback-specific code or approximated with existing sources.

After

A writeback destination field can bind to a published runtime formula.

Ordinary field copies remain direct; formulas are used only where custom calculation is needed.

System touched

This is mainly Dealops 2 CRM writeback plus the shared runtime formula system under dealops3/formulas.

New APIs stay on existing tRPC routes; no new REST surface is introduced.

Larger effort

This is PR 1/2 for DEA-8099.

The UI, selected-field migration CLI, parity tests, and expanded CI matrix are intentionally left for #7666.

Key invariant

The backend resolves mappings and formula revisions from one immutable org release.

No push should combine “latest mapping” with a different formula manifest.

2. What changes

Backend capability map

Area Main files Meaningful change
Formula profile dealops3/formulas/profiles/crmWritebackV1.ts
profiles/index.ts
runtime.ts
Adds crm-writeback.v1, explicit quote/product/row scopes, and shared-runtime evaluation support.
Binding rules formulaSource/bindings.ts
packages/types/v2/writebackSpec.ts
Defines formula value sources, target object compatibility, output type conversion, required parameters, and formula usage metadata.
Execution StandardWriteBack.ts
formulaSource/prepare.ts
formulaSource/values.ts
Evaluates formula bindings up front, validates transformed/coerced values, and then reuses prepared values while building CRM payloads.
Release snapshot writebackSpecRepository.ts
formulaSource/release.ts
versioning/store.ts
Pins writeback mappings into org releases and loads the spec snapshot plus formula manifest together.
Tests / safety formulaWritebackSource.e2e.ts
bindings.test.ts
hydrate.test.ts
release.test.ts
Covers scalar output types, gate-on/off behavior, invalid bindings, no-egress failures, metadata, and rollback snapshots.

Before / after execution model

Previous writeback path
latest WritebackSpec
└─ fields[]
   ├─ direct valueSource
   ├─ calculated / term / reference
   └─ CRM payload construction

Formula revisions were not part of the writeback mapping contract.

New formula-aware path
active OrgGlobalVersion
├─ formulaVersionManifest
└─ writebackSpec snapshot
   └─ fields[]
     ├─ direct valueSource
     └─ formula valueSource → preflight values

The mapping and formula versions are read from the same release boundary.

Schema and repository changes

Prisma migration

Adds release storage for writeback spec snapshots.

packages/prisma/migrations/20261009192724_add_writeback_spec_release/migration.sql

Repository behavior

WritebackSpecRepository.create now locks the org row, writes the spec, and calls pinWritebackSnapshot.

update creates a new pinned spec row when the release is already pinned or formula fields are present.

Read behavior

findMostRecentWithRelease returns both the writeback spec and the active release.

If the release has a snapshot, it reads the pinned spec data instead of mutable latest mappings.

Small client compatibility patch

The client change is minimal and exists so the backend work compiles with stable browser coverage.

3. How it works

Writeback push flow

No partial write on formula failure: formula preparation wraps gate checks, release resolution, binding validation, hydration, evaluation, value conversion, and destination coercion. Failures become FORMULA_EVALUATION_FAILED before CRM calls are made.

Binding rules reviewers should focus on

Scopes
  • quote: can write quote, opportunity, and line-item destinations.
  • product: can write line-item destinations only.
  • row: requires crm-writeback.v1 and emitted-row context.
  • period: refused for CRM writeback.
Output conversion
  • money → CRM number amount.
  • percent → percentage number, e.g. 0.125 → 12.5.
  • date → ISO date string.
  • null → omit field, not clear field.
Save / publish enforcement
  • Spec save refuses missing published formulas, wrong object scope, wrong field type, and missing required parameters.
  • Formula publish refuses revisions that would break existing writeback bindings.
  • Rollback runs the same release validation.

Key code seams

Seam Why it matters
isFieldExecutable Moved into fieldExecution.ts so binding validation and StandardWriteBack share the same disabled / managed-by-Dealops rule.
prepareFormulaWriteback Prepares direct source dependencies and formula values in one pass before any CRM mutation.
hydrateWritebackFacts Keeps fact hydration behind a resolver with no database, CRM client, compiler, or writer dependency.
prepareWritebackFormulaValues Dynamically imports formula evaluation so CommonJS Jest suites do not load the ESM-only CEL parser.
resolveFormulaSourceValue Lets normal CRM payload assembly read already-prepared formula values for quote and line-item objects.

Release snapshot mechanics

Create / update

The repository takes an org lock, saves the mapping, and pins an orgSpecVersion entry when formulas are present or the release is already pinned.

First formula baseline

When moving an org into formula-aware mappings, the backend captures a pre-formula CRM writeback baseline so rollback has a direct-mapping target.

Read path

If the release points at a writeback snapshot, the writer uses that immutable data even if a newer mutable writeback row exists.

Validation coverage called out by the PR

1,140
Mocha writeback, gate, and shared-runtime checks passed
74
HockeyStack / amendment Jest checks passed
18
Client field-key and picklist helper checks passed
6
Server and client TypeScript 6 checks reported locally

4. What it doesn't change

Explicit non-goals in this PR

5. Risks / rollback / open questions

Deployment order: apply the Prisma enum / release snapshot migration before deploying app code. The PR description explicitly says deployment does not enable the CRM formula setting or migrate any organization.
Primary risk

A binding can become stale if the destination mapping and formula revision are read from different moments.

Mitigation: mappings and formula manifests are pinned and loaded from one release.

Operational risk

Disabling the gate for an org that already has formula bindings would make those pushes fail preflight.

Guidance: restore a direct release baseline before disabling the gate.

Rollback boundary

Rollback restores backend release state: mapping snapshot plus formula manifest.

It does not reverse CRM mutations already sent to Salesforce or another CRM.

Reviewer checklist
Open rollout dependency: this backend PR is intentionally incomplete without #7666 for UI and rollout tooling. Keep runtimeFormulaWritebackEnabled off until that top branch is available and reviewed.