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.
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.
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.
Writeback mappings are pinned into org releases beside the formula manifest.
Rollback restores the destination mapping and formula revision set together.
The org setting runtimeFormulaWritebackEnabled defaults off.
The admin UI, rollout tooling, and migration parity work are deferred to #7666.
1. Why this exists
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.
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.
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.
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.
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.tsprofiles/index.tsruntime.ts
|
Adds crm-writeback.v1, explicit quote/product/row scopes, and shared-runtime evaluation support. |
| Binding rules |
formulaSource/bindings.tspackages/types/v2/writebackSpec.ts
|
Defines formula value sources, target object compatibility, output type conversion, required parameters, and formula usage metadata. |
| Execution |
StandardWriteBack.tsformulaSource/prepare.tsformulaSource/values.ts
|
Evaluates formula bindings up front, validates transformed/coerced values, and then reuses prepared values while building CRM payloads. |
| Release snapshot |
writebackSpecRepository.tsformulaSource/release.tsversioning/store.ts
|
Pins writeback mappings into org releases and loads the spec snapshot plus formula manifest together. |
| Tests / safety |
formulaWritebackSource.e2e.tsbindings.test.tshydrate.test.tsrelease.test.ts
|
Covers scalar output types, gate-on/off behavior, invalid bindings, no-egress failures, metadata, and rollback snapshots. |
Before / after execution model
Formula revisions were not part of the writeback mapping contract.
The mapping and formula versions are read from the same release boundary.
Schema and repository changes
Adds release storage for writeback spec snapshots.
packages/prisma/migrations/20261009192724_add_writeback_spec_release/migration.sql
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.
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.
fieldUtils.tsincludes formula field keys:formula-{definitionId}-{scope}-{parameters}.- The regression keeps the same formula independently editable when bound at different scopes.
- The picklist browser test toggles by clicking visible label text instead of forcing the switch.
3. How it works
Writeback push flow
FORMULA_EVALUATION_FAILED before CRM calls are made.
Binding rules reviewers should focus on
quote: can write quote, opportunity, and line-item destinations.product: can write line-item destinations only.row: requirescrm-writeback.v1and emitted-row context.period: refused for CRM writeback.
money→ CRM number amount.percent→ percentage number, e.g.0.125→12.5.date→ ISO date string.null→ omit field, not clear field.
- 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
The repository takes an org lock, saves the mapping, and pins an orgSpecVersion entry when formulas are present or the release is already pinned.
When moving an org into formula-aware mappings, the backend captures a pre-formula CRM writeback baseline so rollback has a direct-mapping target.
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
4. What it doesn't change
- Does not enable formula writeback for any organization by default.
- Does not include the admin UI for configuring formula bindings; that is in
#7666. - Does not migrate selected fields or run rollout tooling; those are also in
#7666. - Does not replace ordinary direct CRM field copies; direct mappings still work with the formula gate off.
- Does not undo CRM records already written if an org is rolled back or the gate is later disabled.
- Does not make period-scoped runtime formulas valid CRM writeback sources.
- Does not change the hosting or API style: this stays inside the existing server/tRPC/backend paths.
5. Risks / rollback / open questions
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.
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 restores backend release state: mapping snapshot plus formula manifest.
It does not reverse CRM mutations already sent to Salesforce or another CRM.
- Confirm save-time, publish-time, rollback-time, and execution-time binding validation are consistent.
- Confirm
StandardWriteBackstill prepares reference and approval-level sources only when needed. - Confirm row fan-out behavior remains identical unless a row-scoped formula intentionally distinguishes tier or ramp rows.
- Confirm release snapshot reads fail loudly on missing pinned snapshots instead of falling back to mutable latest mappings.
- Confirm gate-off behavior leaves direct mappings usable and hides formula metadata sources.
#7666 for UI and rollout tooling. Keep runtimeFormulaWritebackEnabled off until that top branch is available and reviewed.