# NexusCRM Script Layer and Salesforce Apex Positioning

Status: current-implementation and target-positioning design note
Date: 2026-04-26

## 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 or actions must not be described as already
implemented until code and verification exist.

This document is not a proposal to build an Apex-compatible runtime.

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.

## Design Equivalence Claim (ceiling, not current state)

**At the design ceiling**, NexusCRM script reaches Apex product-capability
equivalence: every Apex product role — triggers, Invocable Actions, REST
endpoints, callout orchestration, complex algorithms, ISV business logic — is
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 (governor limits,
synchronous-DML transaction model, Apex Trigger phase ordering, Apex test
classes) are out of the equivalence claim — those are mechanism artifacts of
Apex, not product roles a CRM admin or integrator depends on.

The current implementation is a subset of that ceiling, not the ceiling itself.
The implementation reaches the ceiling incrementally, surface by surface — by
adding expression-engine built-ins, wiring the metadata-action registry, and
building substrate primitives (REST authoring, callout / NamedCredential,
package lifecycle, async, governor, test framework) that are not yet present.
The **Status Vocabulary** below defines the reserved tags used throughout this
document; the **Apex Surface Crosswalk** and **NOT YET IMPLEMENTED** sections
are the authoritative state of what is built today. NexusCRM never installs
Apex source, never executes tenant-uploaded code; the mechanism delta from
Apex is permanent. This document states the ceiling, not a delivery plan.

## Status Vocabulary

Every capability claim in this document carries one of the reserved tags
below. Authors must use these tags verbatim and reviewers must reject claims
that conflate categories. The tags are the only authoritative way to describe
"is it built?" in this document; prose like "supported", "available", or
"works today" without a tag is unverified and must not be relied on.

| Tag | Meaning | Required evidence |
|---|---|---|
| `[IMPLEMENTED]` | Code exists and tests or production evidence verify the behavior. | File/test references and runtime path. |
| `[PARTIAL]` | One slice of the surface is implemented; another slice of the same surface is not. State the implemented slice and the missing slice in the same sentence. | File reference for the implemented slice + named missing slice. |
| `[BUILT-BUT-UNWIRED]` | Code exists for a primitive but the production path does not call it. The primitive is not reachable at runtime today. | File reference for the primitive + statement that no production caller exists. |
| `[DESIGNED — NOT YET BUILT]` | The capability can be implemented generically through metadata plus Go-backed built-ins / actions, but no code exists. | Named primitive, ownership, lifecycle, security, observability, and verification plan. |
| `[GAP — NO PRIMITIVE YET]` | No current implementation and no accepted generic primitive design yet. | Declared product delta and a decision on whether to design one. |
| `[OUT OF TARGET]` | The capability would require Apex source / runtime compatibility or tenant-uploaded arbitrary code, which NexusCRM is not trying to clone. | Explicit rejection and substitute path, if any. |

Anti-conflation rules:

- Never describe a `[DESIGNED — NOT YET BUILT]` capability with present-tense
  verbs ("supports", "provides", "handles"). Use "would" / "is reachable
  through" / "the designed path is".
- Never collapse `[BUILT-BUT-UNWIRED]` into `[IMPLEMENTED]` because the code
  compiles. The runtime path is the test.
- Never collapse `[GAP — NO PRIMITIVE YET]` into `[DESIGNED — NOT YET BUILT]`
  because a path is "obvious". Without a named primitive design, it is a gap.

## Short Definition

In this repository, "script" is not a standalone package, table, or Apex-like
language runtime. The current code uses more specific names: expression engine,
formula engine, Flow engine, validation rule evaluation, sharing-rule criteria,
approval criteria, and action execution.

For current-implementation 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 the currently supported 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: AI-agent-friendly 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/engine.go:11-45` | `expr-lang` compile/run wrapper with a function registry; `RegisterFunction` is exported and callable from any in-process Go caller, but production callers today are intra-package only |
| Salesforce-style formula evaluation | `[IMPLEMENTED]` | `backend/pkg/formula/engine.go:155-185` | Formula engine wraps `expression.Engine` and normalizes Salesforce formula syntax |
| Formula context shaping | `[IMPLEMENTED]` | `backend/pkg/formula/engine.go:184-297` | Injects `$Record` / prior values / variables / FLS filtering / lazy relationship fetch before evaluation |
| Flow formula resources | `[IMPLEMENTED]` | `shared/pkg/models/salesforce_flow.go:157-159`, `shared/pkg/models/salesforce_flow.go:492-498` | Flow metadata carries `FlowFormula` resources for Salesforce metadata roundtrip fidelity |
| Flow formula execution | `[IMPLEMENTED]` | `backend/internal/features/automation/flow_executor.go:200-204`, `backend/internal/features/automation/flow_executor.go:606-612`, `backend/internal/features/automation/executor_helpers.go:90-145` | `FlowExecutor` evaluates declared formula resources into `interview.ContextData` before downstream elements reference them |
| Flow action dispatch | `[PARTIAL]` | `backend/internal/features/automation/executor_actions.go:60-135`, `shared/pkg/models/salesforce_flow.go:373-381` | Flow action metadata can name action types such as `flow` / `emailAlert`; current executor special-cases a closed set of action types via hardcoded switch and otherwise resolves metadata-backed actions; `actionType=apex` is a hard blocker |
| ValidationRule formulas | `[IMPLEMENTED]` | `backend/internal/features/metadata/validation_service.go:335-365` | Active validation rules call `formula.Engine.Evaluate` and fail closed on unsupported non-artifact errors |
| Sharing-rule criteria | `[IMPLEMENTED]` | `backend/internal/features/permissions/sharing_rules.go:132-143` | Criteria formulas evaluate through the shared formula engine against record context |
| Approval formulas | `[IMPLEMENTED]` | `backend/internal/features/automation/approval_service.go:2396-2448` | Approval criteria formulas evaluate through `formulaEngine.Evaluate` against record and user context |
| Action field defaults | `[IMPLEMENTED]` | `backend/internal/features/automation/field_default_resolver.go:33-109` | `_System_ActionFieldDefault.Condition` and `ValueFormula` are evaluated through the formula engine at record-create time |
| Formula field DSL / SQL-facing computation | `[IMPLEMENTED]` | `docs/design/formula-field-activation.md:5-8`, `docs/design/metadata-driven-formula-compiler.md:14-22` | Existing formula DSL parser/compiler/view-builder/DAG solver support metadata-driven formula field activation |
| Standard-action registry (`_System_StandardAction` + `_System_ActionSchema`) | `[PARTIAL]` | `backend/internal/bootstrap/standard_actions.go`, dispatcher at `backend/internal/interfaces/rest/standard_action_dispatcher.go` | Typed-input / declared-permissions / discovery-endpoint / validated-dispatch substrate is wired and dispatches to a backing Flow; the production catalogue ships one entry today (`convertLead`). New shipped action metadata is added by **pack authors / engineers** editing pack data (`standard_actions.json`) plus authoring the backing Flow at build time — this is an L1 / pack-author surface, not an admin runtime surface. Admins do not edit `standard_actions.json`; they author or modify their org's metadata (Flow rows, Validation Rules, Approval Processes, Permission Sets, etc.) through the supported metadata APIs |
| Generic Go-backed action handler registry | `[BUILT-BUT-UNWIRED]` | `backend/internal/features/automation/action_registry.go:9-41` | `ActionHandlerRegistry` and `DefaultRegistry` are defined and constructed, but no production caller registers handlers; dispatch still goes through the hardcoded action-type switch in `action_service.go:76-92` |
| Apex action gap evidence | `[OUT OF TARGET]` (for Apex bytecode execution) | `docs/design/flow/flow-coverage-assessment-2026-04-23.md:100-110`, `docs/design/flow/flow-coverage-assessment-2026-04-23.md:286-288`, `docs/design/flow/flow-coverage-assessment-2026-04-23.md:357-376` | Existing flow coverage work records `actionType=apex` as a hard blocker because NexusCRM does not execute Apex |

## 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. The repo's Flow coverage
assessment records production metadata containing `actionType=apex` Flow calls
and separate `apexclass` / `apextrigger` metadata counts.

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
  synchronization logic.
- 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/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 AI agents and
   admins can read 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. Package installation translates Salesforce package intent into NexusCRM pack
   artifacts: objects, fields, permissions, layouts, Flow/Formula/Approval
   metadata, credentials, routes, and built-in action/function bindings. Apex
   code in the Salesforce package is not installed as Apex; it is mapped to
   equivalent NexusCRM primitives where they exist, or recorded as a designed
   extension path / unsupported gap where they do not.

The current implementation is only a subset of that target. Surface-by-surface
state lives in the **Apex Surface Crosswalk** (Status column) and the
**NOT YET IMPLEMENTED** catalogue; do not paraphrase those tables here. Per
the **Status Vocabulary** above, every claim about a specific Apex surface
must carry one of the reserved tags — `[IMPLEMENTED]`, `[PARTIAL]`,
`[BUILT-BUT-UNWIRED]`, `[DESIGNED — NOT YET BUILT]`, `[GAP — NO PRIMITIVE YET]`,
or `[OUT OF TARGET]`.

Do not collapse "not implemented today" into "not in the design", and do not
collapse "architecturally implementable" into "already implemented".

## 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.

**The Status column is the only authoritative state. The Target direction
column describes what would be true IF the extension path is built — it is
conditional, not a commitment.**

| Salesforce Apex surface | Status | Current NexusCRM state | Target direction |
|---|---|---|---|
| Triggers with before/after phases | `[PARTIAL]` | Flow record triggers and validation formulas cover part of the trigger role; there is no Apex Trigger phase 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 via the hardcoded built-in dispatch; `_System_StandardAction` registry exists with one catalogued action (`convertLead`); `actionType=apex` is a hard blocker. | Replace Apex actions with generic metadata-driven server actions or Flow-native rewrites. Each action needs schema, permissions, audit, error, and packaging semantics. |
| Generic Go-backed action handler registry | `[BUILT-BUT-UNWIRED]` | `ActionHandlerRegistry` is defined and a `DefaultRegistry` is constructed, but no production caller registers handlers; dispatch still goes through the hardcoded action-type switch. | Wire the registry as the unified dispatch path so new action types can be added without editing the central switch. |
| REST endpoints | `[DESIGNED — NOT YET BUILT]` | Apex REST is not implemented; only fixed platform REST endpoints and invocable-flow endpoints exist. | Implementable if designed as metadata-defined route/action primitives backed by Go handlers, with namespace, auth, versioning, OpenAPI/schema, limits, audit, and install/uninstall semantics. Not tenant-uploaded code. |
| Callout orchestration | `[PARTIAL]` | `CallWebhook` exists as a Go-backed action with SSRF guard, but there is no NamedCredential / secret-binding primitive. | Implementable through generic outbound-action primitives: NamedCredential / secret binding, egress policy, retries, timeout, response mapping, audit, and test contracts. |
| Complex algorithms such as pricing, allocation, scoring, sync | `[PARTIAL]` | Flow/Formula can express the slice expressible as Flow loops + formula chains; algorithms requiring loops/recursion/mutable state require Go-backed actions/functions. | Implement as reusable built-ins with metadata-declared inputs/outputs. Tenant-specific algorithms must be metadata or quarantined pack/action design, not generic L0 hardcoding. |
| Salesforce package translation model (Apex/managed-package semantics → NexusCRM pack metadata + Flow + built-in action/function bindings) | `[DESIGNED — NOT YET BUILT]` | Bootstrap pack format and metadata translation surfaces exist, but a complete Salesforce-package-to-NexusCRM-pack translator (mapping triggers / Apex classes / Apex REST / Apex tests into the equivalent NexusCRM primitives, or marking each as a designed extension path / gap / out-of-target) is not built. | Build a translator that maps each Apex product role into a NexusCRM primitive; surfaces with no equivalent primitive get tagged through this Status Vocabulary, not silently dropped. |
| Vendor-uploaded Apex executable code (Apex source / classes / triggers / `@InvocableMethod` / `@RestResource`, ISV bytecode) | `[OUT OF TARGET]` | Not implemented and not designed. NexusCRM never installs Apex source, never executes tenant-uploaded code; the mechanism delta from Apex is permanent. | Out of target unless a future strategy explicitly reverses this document. |
| Package-owned lifecycle (namespace / install-state / versioning / conflict / upgrade / uninstall / permissions / observability) | `[GAP — NO PRIMITIVE YET]` | Bootstrap reseed exists; `IsCustomized=1` survives reseeds; there is no full pack-lifecycle primitive covering version pinning, conflict resolution between packs, install/uninstall transitions, dependency declaration, or per-pack observability/audit. | No accepted primitive design yet. |
| Async / Queueable / Batch / Future | `[GAP — NO PRIMITIVE YET]` | A 1-minute scheduler runs scheduled flows and resumes Wait-paused interviews; no queueable / batch / future-style background-job primitive. | No accepted primitive design yet. |
| Governor limits (CPU / SOQL / heap quotas) | `[GAP — NO PRIMITIVE YET]` | Only `maxFlowCallDepth` (subflow recursion guard) exists; no per-tenant CPU / row-count / heap accounting. | No accepted primitive design yet. |
| Apex test classes / coverage requirement | `[GAP — NO PRIMITIVE YET]` | No test-framework primitive in the codebase. | No accepted primitive design yet. |

## 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 that evaluate against
  record/user context.
- Formula fields compiled or evaluated through the formula DSL path.

This boundary matters in reviews. The implementation evidence supports a narrow
statement: formula/expression paths are separately parsed/evaluated and formula
field activation has a DSL compiler/view-builder path. Do not generalize that
to the whole Flow engine. 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 such.

## NOT YET IMPLEMENTED

This section catalogues substrate gaps as they exist today. **It is not a
roadmap, backlog, or delivery commitment; entries are not ordered by priority
and carry no schedule.** It exists so that an LLM agent or human reviewer
grepping this document for a capability cannot accidentally read a
conditional Target direction as a current-state claim. The authoritative
state of any specific surface is the **Status** column of the Apex Surface
Crosswalk above, plus this catalogue.

The catalogue is split into two parts. *Designed extension paths* have a
named primitive shape and a defined design-time obligation; the substrate is
reachable by adding built-ins, wiring registries, or building the named
primitive. *Unsupported gaps* have no accepted primitive design yet — even
the shape of the future primitive is open.

### Designed extension paths (`[DESIGNED — NOT YET BUILT]` and `[BUILT-BUT-UNWIRED]`)

These are reached on three axes (the "three parity dials"). A surface can sit
on more than one axis when it requires both more built-ins and a primitive
that does not yet exist.

**Dial D1 — extending value-computation built-ins.** The expression / formula
engine (`backend/pkg/expression`, `backend/pkg/formula`) exposes a
`RegisterFunction` API. The current registered set covers the
Salesforce-formula functions used by ValidationRule / Sharing / Approval /
Default formulas. Additional built-ins (mathematical, date, string, encoding,
hashing, schema-introspection) extend this surface without redesign. This
dial reaches only value-producing surfaces; it cannot carry side effects,
transactional context, or governor accounting.

**Dial D2 — wiring and extending the metadata-action registry.** The
`ActionHandlerRegistry` (`backend/internal/features/automation/action_registry.go`)
is `[BUILT-BUT-UNWIRED]`: defined and constructed, but no production caller
registers handlers, and the action-type dispatcher still uses a hardcoded
switch. The `_System_StandardAction` + `_System_ActionSchema` registry is
also already in code and dispatches `convertLead` to its named Flow today;
new typed Invocable-Action–style entries are added at build time by
**pack authors / engineers** editing pack data (`standard_actions.json`)
plus authoring the backing Flow, not by editing platform Go and not by
admin runtime self-service. Admins consume what packs ship — they do not
register new platform actions at runtime. Wiring D2 — making
`ActionHandlerRegistry` the unified dispatch path and adding more
standard-action rows via pack data — is the dial for Apex Invocable
Actions, programmatic SharingRule effects, and DML-shaped action work.

**Dial D3 — designed substrate primitives that do not yet have code.** Each
of the following has a named primitive shape but no implementation. Each
entry below carries: the surface, what is missing, the named primitive (or
"no accepted primitive design yet" — which moves it to the *Unsupported gaps*
list below), and the design-time obligation that any future PR proposing it
must satisfy.

- **REST endpoint authoring.** Missing: tenant-or-pack-author HTTP route
  registry. Named primitive: metadata-defined route + Go handler binding
  with namespace, auth, versioning, OpenAPI/schema, limits, audit,
  install/uninstall semantics. Obligation: design must declare each of those
  facets and a verification path; not tenant-uploaded code.
- **Callout / NamedCredential.** Missing: managed-secret primitive bound to
  outbound actions. Named primitive: NamedCredential + secret binding +
  egress policy + retry/timeout + response mapping + audit + test contracts.
  Obligation: design must declare credential lifecycle, rotation, and
  permission gating; existing `CallWebhook` action remains the partial
  implementation until the primitive lands.
- **Programmatic record sharing.** Missing: tenant-author-callable share API
  (the declarative `SharingRule` criteria-evaluation path already exists).
  Named primitive: a registered standard-action whose handler creates / removes
  share rows under permission gating. Obligation: design must declare access
  scope, audit, and conflict semantics with declarative rules.
- **Salesforce package translation model.** Missing: a build-time
  translator that maps each Apex product role inside a Salesforce package
  (triggers, Apex classes, Apex REST, async Apex, Apex tests) onto the
  equivalent NexusCRM primitive — Flow trigger metadata, built-in
  function/action bindings, route metadata, etc. — and that explicitly
  tags any Apex behavior with no equivalent primitive (per the Status
  Vocabulary). Named primitive: package-translation pipeline + per-Apex-
  surface mapping rules. Obligation: design must declare the per-surface
  mapping table, the unmapped-behavior classification flow, and the
  validation that no silent drops occur. NexusCRM never installs Apex
  source as part of this translation.

### Unsupported gaps (`[GAP — NO PRIMITIVE YET]`)

The surfaces below have no accepted primitive design today. They are
described here to make the gap explicit, not to commit to closing it.

- **Async / Queueable / Batch / Future.** The current `SchedulerService` is a
  1-minute ticker for scheduled flows + Wait-paused interview resumes; it
  does not provide queue-bounded background jobs, batch-chunking, or
  fire-and-forget post-commit semantics. No accepted primitive design yet.
- **Governor limits (CPU / SOQL / heap quotas).** Only the
  `maxFlowCallDepth` subflow-recursion guard exists. No per-tenant CPU,
  row-count, or heap accounting. No accepted primitive design yet.
- **Apex Trigger phase parity.** Flow record triggers cover part of the
  trigger role but not the full Apex `before/after × insert/update/delete/
  undelete` phase matrix with bulk-context invariants. No accepted primitive
  design for the unmet phase semantics yet.
- **Apex test classes / coverage requirement.** No test-framework primitive
  in the codebase. No accepted primitive design yet.
- **AI-agent runtime.** The standard-action registry is shaped such that an
  agent driver could call NexusCRM actions as tools without engine surgery
  (typed inputs / declared permissions / discovery endpoint / validated
  dispatch). However, no agent runtime exists in code today: zero LLM client
  dependency in `backend/go.mod`, no JSON-Schema export endpoint, no MCP
  server, no agent orchestrator. This is a substrate-shape observation, not
  a runtime claim. No accepted primitive design for the runtime side yet.
- **Package-owned lifecycle (namespace / install-state / versioning /
  conflict / upgrade / uninstall / permissions / observability).** Bootstrap
  reseed exists and `IsCustomized=1` rows survive reseeds, but a complete
  pack-lifecycle primitive covering version pinning, conflict resolution
  between packs, install/uninstall state transitions, dependency
  declaration, and per-pack observability/audit does not exist. No accepted
  primitive design yet.

### `[OUT OF TARGET]`

Apex source / class / trigger execution; tenant-uploaded arbitrary Go or
other executable code. These would require Apex language / runtime
compatibility or a tenant-code sandbox, neither of which NexusCRM is trying
to clone. The mechanism delta from Apex is permanent.

## Relationship to Apex

Use this wording when comparing NexusCRM with Salesforce. It is the externally
quotable form of the **Design Equivalence Claim** above, and must stay
consistent with it.

> Salesforce uses Apex to carry installable business code. NexusCRM does not
> clone the Apex language, sandbox, or managed-package executable-code model.
> At the design ceiling, NexusCRM script reaches Apex product-capability
> equivalence: every Apex product role is 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 — governor limits, transaction model,
> Trigger phase ordering, Apex test classes — are mechanism artifacts and
> are out of the equivalence claim). The current implementation is a
> subset of that ceiling, reached incrementally surface by surface; every
> claim about a specific Apex surface must carry a Status-Vocabulary tag
> (`[IMPLEMENTED]` / `[PARTIAL]` / `[BUILT-BUT-UNWIRED]` /
> `[DESIGNED — NOT YET BUILT]` / `[GAP — NO PRIMITIVE YET]` /
> `[OUT OF TARGET]`). Salesforce packages are translated into NexusCRM pack
> metadata plus primitive bindings, never installed as Apex code; the
> mechanism delta from Apex is permanent.

Do not write or approve claims that imply:

- NexusCRM can run Apex code.
- Third-party ISVs can upload their own executable code into NexusCRM tenants.
- Flow + Formula + current actions already cover every Apex use case.
- A future built-in/action exists merely because it is architecturally possible.
- Go-backed Invocable Actions have the same static transparency as formulas.

Also do not write or approve claims that imply:

- A capability such as REST endpoint authoring or callout orchestration is
  impossible merely because Apex REST/callout parity is not implemented today.
- NexusCRM must clone the Apex sandbox before it can offer an equivalent
  business capability through metadata plus platform built-ins.

## Product Implications From the Current Code

The following are review-time obligations that apply across multiple Apex
surfaces. They are not duplicated per surface — surface-specific state lives
in the Apex Surface Crosswalk and the NOT YET IMPLEMENTED catalogue. Design
docs and pack RFCs that compare against Salesforce managed packages must be
this explicit.

1. **Third-party ISV package translation.** Salesforce managed packages can
   carry Apex. NexusCRM does not install that Apex code. A Salesforce package
   is translated into NexusCRM pack artifacts that compose platform
   primitives: metadata rows, Flow/Formula/Approval definitions, permissions,
   credentials, routes, and built-in action/function bindings. Any Apex
   behavior that cannot be represented this way must be classified per the
   Status Vocabulary (typically `[DESIGNED — NOT YET BUILT]` or
   `[GAP — NO PRIMITIVE YET]`) and routed through the NOT YET IMPLEMENTED
   catalogue.
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 Apex Trigger phase parity unless
   they point to implemented Flow semantics that cover the specific phase
   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
   instead of assuming Salesforce managed-package behavior.

For surface-specific implications (Apex invocable actions, complex
algorithms, REST endpoints, callout orchestration, async/queueable, governor
limits, test framework, AI-agent runtime), see the **Apex Surface
Crosswalk** and the **NOT YET IMPLEMENTED** section.

These are not automatic blockers. They become blockers only when a design
claims Salesforce product-form parity without declaring the delta, the
Status tag, justification, next-tenant impact, and 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 Invocable Action.
3. Classify each compared surface using the Status Vocabulary —
   `[IMPLEMENTED]`, `[PARTIAL]`, `[BUILT-BUT-UNWIRED]`,
   `[DESIGNED — NOT YET BUILT]`, `[GAP — NO PRIMITIVE YET]`, or
   `[OUT OF TARGET]` — and ensure the claim's verb tense matches the tag
   (no present-tense for non-`[IMPLEMENTED]` claims).
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 designed extension paths: schema,
   permissions, namespace/install/versioning, limits, audit, rollback or
   uninstall behavior, and tests.
6. Do block undeclared drift: especially claims that a pack is Salesforce-like
   while relying on platform-only Go code, unversioned action registration, or
   missing package lifecycle semantics.

## Consequence for Pack Architecture

For pack designs, derive current-state claims from implemented code paths and
target-state claims from named extension primitives:

- Pack-owned business orchestration should be authored as namespaced metadata
  where possible: Flow, Formula, Validation Rule, Approval Process,
  NamedCredential bindings, route metadata, and setup metadata.
- Vendor-agnostic integration capabilities should be platform Invocable Actions
  reusable by multiple packs.
- Salesforce package install is a translation step, not Apex execution. Package
  Apex behavior must map to NexusCRM metadata plus built-in action/function
  bindings, or be declared as a designed extension path / unsupported gap.
- Vendor-specific code is not tenant-uploaded script in the current repo. If it
  is required, the design must identify the Go-backed action/function path and
  declare the package lifecycle semantics.
- A design that says "Salesforce uses Apex; NexusCRM uses script" must define
  script using this document and must tag every compared Apex surface with
  one of the Status Vocabulary tags above; bare "supported / not supported"
  framing is not acceptable.

## Summary

NexusCRM script is the metadata-native executable layer made of Flow,
Formula/Expression, the formula DSL infrastructure, and platform-controlled
Invocable 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 (Apex's
substrate-internal concerns such as governor limits, transaction model,
Trigger phase ordering, and test classes are mechanism artifacts and are
out of the equivalence claim). The current implementation is a
subset of that ceiling, reached incrementally surface by surface; it is not
Apex runtime compatibility, and it never installs Apex source or executes
tenant-uploaded code (the mechanism delta from Apex is permanent).

The authoritative state of any specific Apex surface lives in **three
truth sources**, not in any prose claim elsewhere in this document:

- **Current Implementation Evidence** (Status column) — capabilities
  already in code.
- **Apex Surface Crosswalk** (Status column) — Apex product surfaces
  mapped to current state and conditional target direction.
- **NOT YET IMPLEMENTED** — substrate gaps as they exist today, split
  into designed extension paths and unsupported gaps; explicitly not a
  roadmap.

Any design or PR comparing with Salesforce Apex must tag every compared
surface with a Status-Vocabulary tag and route gap-shaped claims through
the NOT YET IMPLEMENTED catalogue.