# NexusCRM Script Layer and Salesforce Apex Positioning

Status: current-state and positioning reference
Date: 2026-05-02

## Purpose

This note records what the NexusCRM "script" layer means today and how it
relates to Salesforce Apex. It has two separate jobs:

1. Describe the current implementation shape.
2. State the intended direction for future implementation work.

Keep those jobs separate. Current code does not yet cover every Apex product
role, but that does not mean the design target is limited to the currently
implemented subset. Conversely, a capability that is architecturally reachable
through new built-in functions, actions, or generic substrate must not be
described as already implemented until code and verification exist.

This document is not a proposal to build an Apex-compatible runtime. It is
also not a Salesforce package translator design. Translator-specific pipeline,
file-format, and migration-tool details belong in a translator design, not in
this positioning note.

Read this before reviewing or designing changes that compare NexusCRM packs,
Flow, Formula, Invocable Actions, custom automation, or third-party integration
extensibility with Salesforce Apex / managed packages.

## Claim Types

Use these categories when editing this document:

| Claim type | Keep? | Rule |
|---|---|---|
| Product design statement | Yes | Durable target or boundary, such as "NexusCRM does not run Apex" or "NexusCRM aims to cover Apex product roles through metadata plus platform primitives." Mark it as target/boundary, not current implementation. |
| Comparison statement | Yes | Salesforce baseline or NexusCRM-vs-Salesforce distinction. Compare product roles, not implementation mechanisms. |
| Current-state statement | Yes | Must point to current code paths or explicitly say the surface is missing. |
| Transitional / stale implementation plan | No | Remove concrete migration-translator pipeline details, deprecated status taxonomies, and route-by-route delivery plans that no longer represent current architecture. |

## Design Equivalence Claim

This is a design ceiling, not the current implementation state.

At the design ceiling, NexusCRM script reaches Apex product-capability
equivalence: Apex product roles such as triggers, Invocable Actions, REST
endpoints, callout orchestration, complex algorithms, and ISV business logic
are reachable through metadata (Flow / Formula / Approval / Validation) plus
Go-backed built-in functions and Invocable Actions. What differs from Apex is
the authoring model and runtime mechanism, not the intended CRM product-role
capability set.

Apex's substrate-internal concerns, such as governor limits, synchronous-DML
transaction mechanics, Apex Trigger phase ordering, and Apex test classes, are
mechanism artifacts of Apex. They are not product roles by themselves, though
NexusCRM may need equivalent platform primitives where customers depend on the
resulting product behavior.

The current implementation is a subset of that ceiling, not the ceiling
itself. NexusCRM reaches the ceiling incrementally, surface by surface, by
adding expression-engine built-ins, wiring metadata-action dispatch, and
building generic substrate primitives such as REST authoring, callout /
NamedCredential, package lifecycle, async execution, governor-style resource
control, and test-framework support where those primitives are accepted and
implemented.

NexusCRM never installs Apex source and never executes tenant-uploaded code.
The mechanism delta from Apex is permanent. This document states the boundary
and target shape; it is not a delivery plan.

## Status Vocabulary

Every capability claim in this document carries one of these tags. Reviewers
should reject claims that blur current implementation, reachable design, and
unsupported gaps.

| Tag | Meaning |
|---|---|
| `[IMPLEMENTED]` | Code exists and the runtime path is wired. |
| `[PARTIAL]` | One slice of the surface is implemented; another slice is missing. |
| `[BUILT-BUT-UNWIRED]` | Code exists for a primitive, but production runtime does not call it. |
| `[GENERIC EXTENSION PATH]` | The capability can be added as metadata plus a generic Go-backed function/action/primitive, but is not implemented today. |
| `[GAP - NO PRIMITIVE YET]` | No current implementation and no accepted generic primitive design yet. |
| `[OUT OF TARGET]` | The capability would require Apex source/runtime compatibility or tenant-uploaded arbitrary code, which NexusCRM is not trying to clone. |

Rules:

- Do not describe non-`[IMPLEMENTED]` capabilities with present-tense product
  claims such as "supports" or "handles".
- Do not treat compiled but unwired code as runtime capability.
- Do not treat "Salesforce uses Apex" as proof that NexusCRM must clone Apex.
- Do not treat "possible to implement in Go" as already implemented.

## Short Definition

In this repository, "script" is not a standalone package, table, or Apex-like
language runtime. Current code uses more specific names:

- expression engine
- formula engine
- Flow engine
- validation rule evaluation
- sharing-rule criteria
- approval criteria
- action execution

For current-state claims, "script" means the metadata-native executable
surface that is actually present in code:

- Flow metadata interpreted by the Flow engine.
- Formula / expression DSL evaluated by the Formula and Expression engines.
- Go-backed action execution for currently wired metadata action types.

The closest code-level substrate is the expression engine in
`backend/pkg/expression`, wrapped by the Salesforce-oriented formula engine in
`backend/pkg/formula`. Flow uses that formula layer for executable formula
resources and dynamic values, while the Flow engine itself remains a metadata
interpreter rather than a general script VM.

For target-design claims, "script" means the intended metadata-native business
logic layer: orchestration authored as metadata/script and backed by
platform-provided Go capabilities. New capabilities enter this layer as
generic built-in functions, Invocable Actions, route/action metadata,
credentials, or other reusable platform primitives. They do not enter as Apex
source code, tenant-uploaded arbitrary code, or org-specific L0 branches.

## Current Implementation Evidence

Each row is the current state of a capability already in code. Every row
carries a Status tag from the Status Vocabulary.

| Capability | Status | Current source of truth | Runtime path |
|---|---|---|---|
| Generic expression execution | `[IMPLEMENTED]` | `backend/pkg/expression` | Expr wrapper with a function registry. |
| Salesforce-style formula evaluation | `[IMPLEMENTED]` | `backend/pkg/formula` | Formula engine wraps the expression engine and normalizes Salesforce formula syntax. |
| Formula context shaping | `[IMPLEMENTED]` | `backend/pkg/formula` | Injects record/prior values, variables, FLS filtering, and lazy relationship fetch before evaluation. |
| Flow formula resources | `[IMPLEMENTED]` | `shared/pkg/models/salesforce_flow.go` | Flow metadata carries formula resources for Salesforce metadata roundtrip fidelity. |
| Flow formula execution | `[IMPLEMENTED]` | `backend/internal/features/automation/flow_executor.go`, `backend/internal/features/automation/executor_helpers.go` | Flow executor evaluates declared formula resources into interview context. |
| Flow action dispatch | `[PARTIAL]` | `backend/internal/features/automation/executor_actions.go`, `shared/pkg/models/salesforce_flow.go` | Supported action types are dispatched; Apex action execution is out of target. |
| ValidationRule formulas | `[IMPLEMENTED]` | `backend/internal/features/metadata/validation_service.go` | Active validation rules evaluate through the formula engine and fail closed on unsupported non-artifact errors. |
| Sharing-rule criteria | `[IMPLEMENTED]` | `backend/internal/features/permissions/sharing_rules.go` | Criteria formulas evaluate through the shared formula engine against record context. |
| Approval formulas | `[IMPLEMENTED]` | `backend/internal/features/automation/approval_service.go` | Approval criteria formulas evaluate through the formula engine against record and user context. |
| Action field defaults | `[IMPLEMENTED]` | `backend/internal/features/automation/field_default_resolver.go` | Action default conditions and value formulas evaluate through the formula engine at record-create time. |
| Formula field DSL / SQL-facing computation | `[IMPLEMENTED]` | `backend/internal/features/analytics` | Formula DSL parser/compiler/view-builder support metadata-driven formula field activation. |
| Standard-action registry | `[PARTIAL]` | `backend/internal/bootstrap/standard_actions.go`, `backend/internal/interfaces/rest/standard_action_dispatcher.go` | Typed input, declared permissions, discovery endpoint, and validated dispatch are wired for shipped actions such as `convertLead`. |
| Generic Go-backed action handler registry | `[BUILT-BUT-UNWIRED]` | `backend/internal/features/automation/action_registry.go` | Registry exists, but production dispatch still goes through the current action paths. |
| Apex action execution | `[OUT OF TARGET]` | Flow/action dispatch behavior | NexusCRM does not execute Apex source or bytecode. |

## Salesforce Apex Baseline

This section is the comparison target, not a NexusCRM implementation claim.
In Salesforce, Apex is both a server-side implementation language and a product
surface used by org automation and managed packages.

Apex commonly carries these product roles:

- Triggers with fine-grained before/after insert/update/delete phases.
- Invocable Actions used by Flow.
- REST endpoints and callout orchestration.
- Complex algorithms such as pricing, allocation, scoring, and custom sync.
- Third-party ISV business logic delivered through managed packages.

Salesforce can satisfy those roles by shipping Apex executable code into the
subscriber org. NexusCRM must compare against the product role, not the Apex
implementation mechanism.

## NexusCRM Position

NexusCRM does not seek Apex language or runtime compatibility. It does not
clone the Apex sandbox, and the current design does not let tenants or package
authors upload arbitrary executable code.

The NexusCRM target is Apex product-role capability equivalence through a
different mechanism:

1. Business logic is authored as metadata/script orchestration that admins and
   automation tooling can inspect and modify.
2. Generic L0 interpreters execute Flow, Formula/Expression, validation,
   approval, permission, record, and metadata semantics.
3. Capabilities that exceed pure metadata are exposed as reusable Go-backed
   built-in functions/actions, route/action metadata, credentials, or other
   platform primitives.
4. Apex code in a Salesforce-origin package is not installed as Apex. Its
   behavior must map to existing NexusCRM primitives, a generic extension
   path, an unsupported gap, or out-of-target behavior.

The current implementation is only a subset of that target. Surface-by-surface
state lives in the Apex Surface Crosswalk below; do not paraphrase those rows
into broader "supported" claims.

## Apex Surface Crosswalk

This table is the review anchor. It prevents two common mistakes: treating
every missing Apex feature as impossible, and treating every future built-in as
if it already exists.

| Salesforce Apex surface | Status | Current NexusCRM state | Target direction / review guidance |
|---|---|---|---|
| Triggers with before/after phases | `[PARTIAL]` | Flow record triggers and validation formulas cover part of the trigger role; there is no Apex Trigger runtime. | Extend Flow/metadata trigger semantics where needed. Do not add object-specific Go trigger branches. |
| Invocable Actions used by Flow | `[PARTIAL]` | Flow can call supported action types; `_System_StandardAction` exists for shipped actions; `actionType=apex` is not executed. | Replace Apex actions with metadata-driven server actions or Flow-native rewrites. |
| Generic Go-backed action handler registry | `[BUILT-BUT-UNWIRED]` | Registry exists, but it is not the unified production dispatch path. | Wiring it should be generic substrate, not tenant business logic. |
| REST endpoints | `[GENERIC EXTENSION PATH]` | Apex REST is not implemented; fixed platform REST endpoints exist. | A future primitive needs route metadata, handler binding, auth, schema, limits, audit, and lifecycle semantics. |
| Callout orchestration | `[BUILT-BUT-UNWIRED]` | NamedCredential substrate exists (NCRM-INT-02 #336): definition/value separation, AES-256-GCM secret store, masked reads, `ManageNamedCredentials` + `ViewSetup` gates, BLOCKED generic CRUD, server-internal `ResolveCredentialValue` with connector-pack active-state gate, and internal admin REST handlers under `/api/named-credentials`. No in-tree runtime consumer yet: no pack-install pipeline to author `OwnerPack`, no real callout caller invoking `ResolveCredentialValue`. Egress policy, retries, timeout, callout-level audit, and metadata-driven mapping are also not implemented. | Admin REST handlers now exist, but keep this at `[BUILT-BUT-UNWIRED]` until pack-owned writer / `OwnerPack` authoring and a real callout consumer land (NCRM-INT-04/-05). Future work also needs egress policy, retries/timeout, mapping, and audit. |
| Complex algorithms | `[PARTIAL]` | Flow/Formula can express simple logic; algorithms requiring loops, mutable state, or external effects need Go-backed actions/functions. | Implement as reusable built-ins with metadata-declared inputs/outputs. |
| Vendor-uploaded Apex executable code | `[OUT OF TARGET]` | Not implemented and not designed. | NexusCRM must not install Apex source or execute tenant-uploaded code. |
| Package-owned executable lifecycle | `[GAP - NO PRIMITIVE YET]` | Pack install/verification exists, but a complete code/action lifecycle for third-party executable behavior does not. | Designs must address namespace, install-state, versioning, conflict, upgrade, uninstall, permissions, and observability. |
| Async / Queueable / Batch / Future | `[GAP - NO PRIMITIVE YET]` | Scheduled flows and wait resumes exist; queueable/batch/future-style background jobs do not. | Do not claim Apex async parity without a primitive design. |
| Governor limits | `[GAP - NO PRIMITIVE YET]` | Subflow recursion guard exists; per-tenant CPU / row-count / heap accounting does not. | Treat as a mechanism gap, not a product capability already present. |
| Apex test classes / coverage requirement | `[GAP - NO PRIMITIVE YET]` | No Apex-style test framework exists. | Do not claim test-framework parity. |

## Important Boundary: Flow Is Not the Script VM

The Flow engine is a metadata interpreter for Flow graphs. It dispatches Flow
elements such as decisions, assignments, loops, waits, record operations,
subflows, and action calls.

The script/expression substrate is used inside that interpreter where
executable expressions are required:

- Flow formula resources.
- Formula-backed action field defaults and derived values.
- ValidationRule, sharing-rule, and approval formulas.
- Formula fields compiled or evaluated through the formula DSL path.

This boundary matters in reviews. A whole Flow graph can perform DML,
wait/resume, call actions, and trigger external effects. A Go-backed action
handler is L0 code and must be reviewed as generic substrate, not as tenant
business logic hidden in the platform.

## Product Implications

1. **Third-party package behavior.** Salesforce managed packages can carry
   Apex. NexusCRM does not install that Apex code. Equivalent behavior must be
   represented by metadata rows, Flow/Formula/Approval definitions,
   permissions, credentials, routes, and built-in action/function bindings, or
   it must be classified as a generic extension path, gap, or out of target.
2. **Apex Trigger phase control.** Flow record triggers and validation formula
   evaluation cover part of the trigger role; there is no Apex Trigger runtime.
   Designs must not imply phase parity unless they point to implemented Flow
   semantics that cover the specific behavior.
3. **Package-owned executable lifecycle.** Current action registration and
   execution is not a complete package-owned code lifecycle. Any pack-scoped
   action/function or package route proposal must explicitly design namespace,
   install-state, versioning, conflict, and uninstall semantics.

These are not automatic blockers. They become blockers only when a design
claims Salesforce product-form parity without declaring the delta, the Status
tag, the impact, and the verification path.

## Review Guidance

When reviewing a PR that touches this area:

1. Start from the Salesforce baseline: is the Salesforce solution Apex,
   Flow/Formula, package metadata, NamedCredential, ConnectedApp, or another
   primitive?
2. Identify which NexusCRM layer is being used: L2 metadata, generic L0
   interpreter, or L0 Go-backed action/function.
3. Classify each compared surface with the Status Vocabulary above.
4. Do not require an Apex-equivalent sandbox merely because Salesforce uses
   Apex internally. Engine identity is not the review target; product boundary
   and metadata-driven authoring are.
5. Do require enough mechanism for generic extension paths: schema,
   permissions, namespace/install/versioning, limits, audit, rollback or
   uninstall behavior, and tests.
6. Block undeclared drift: especially claims that a pack is Salesforce-like
   while relying on platform-only Go branches, unversioned action registration,
   or missing package lifecycle semantics.

## Summary

NexusCRM script is the metadata-native executable layer made of Flow,
Formula/Expression, formula DSL infrastructure, and platform-controlled
Go-backed actions. At the design ceiling, it reaches Apex product-capability
equivalence through metadata authoring plus extensible Go-backed built-ins and
Invocable Actions. What differs from Apex is the authoring model and runtime
mechanism, not the intended CRM product-role capability set.

The current implementation is a subset of that ceiling. It is not Apex runtime
compatibility, and it never installs Apex source or executes tenant-uploaded
code. Any design or PR comparing with Salesforce Apex must distinguish current
runtime behavior from partial support, generic extension paths, unsupported
gaps, and out-of-target Apex execution.