Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
@carbon/ee/workflows
The shared contract for a workflow definition — the zod schema, the read-time normaliser, the validator that decides whether a workflow may be activated, the generated catalog of everything a customer can pick, and the pure runtime that evaluates a node. It runs nothing and reads no database.
Commercial. This engine lives under packages/ee/src/workflows/ (moved from the
old standalone @carbon/workflows package) and is covered by the packages/ee
commercial license. Import it as @carbon/ee/workflows (main barrel),
@carbon/ee/workflows/help, and @carbon/ee/workflows/labels (Vite-only — the msg
macro throws in plain Node). The runtime/authoring entitlement lock lives beside it in
@carbon/ee/workflows.server (workflowsEnabledForCompany / requireWorkflowsEntitlement) —
see .claude/rules/commercial-licensing.md.
The CE-safe wire contracts stayed OUT of the commercial package, in the leaf
@carbon/workflows-core (packages/workflows-core/): runTriggerSchema/RunTrigger
(what fired a run) and the moment contract (MOMENT_OUTPUT_KEYS, MomentKey,
MomentEntityRef, MomentPayload). @carbon/lib (events.ts, workflows/raise-moment.ts)
imports these type-only from the leaf, never from this engine — that is what breaks the
lib → ee → lib cycle the move would otherwise create. This engine re-exports both from the
leaf (see run-trigger.ts and catalog/moments.ts below).
"Workflow" here means the customer-facing feature: a "when this happens, do that" rule a customer
builds on a canvas. It is not the generic sense used by the .claude/rules/workflow-*.md
developer-procedure files, and unrelated to nonConformanceWorkflow.
Specs: .ai/specs/2026-07-30-workflows-foundation.md (schema, validator, runtime) and
.ai/specs/implemented/2026-07-30-workflows-catalogs.md (actions and operations).
Always
- Change the schema here, never in a consumer. The builder, the activation gate and the engine all read this one package — if any of them can disagree about what is valid, a customer can activate something broken and it will act on real records.
- Turn a stored row into a definition with
readWorkflowVersion(row). It is the single boundary where untyped JSON becomes the typed model, and it returns{ok: true, definition}or{ok: false, failure, message}— never a blank canvas standing in for a row it could not read, because the builder would then save over a definition nobody could see. - Upgrade an older stored shape only inside
migrateDefinitioninsrc/definition/normalize.ts. It is private and runs on the raw JSON before the current-schema parse — a document old enough to need upgrading cannot satisfy the current schema, so migrating after that parse could never run. It carries three upgrades today: v1 → v2 resets a lookup node'smatchto[]because its shape changed (no v1 lookup could be activated); v2 → v3 backfills nodenames from the oldtitle; v3 → v4 renames theentitynode type tocompute, leaving stored node names alone — a name is an identifier other nodes reference. - Bump
CURRENT_DEFINITION_FORMAT_VERSION(now 4, insrc/definition/schema.ts) when the stored shape changes, and add the upgrade tomigrateDefinitionin the same change. - Pass a
WorkflowCatalogintovalidateDefinition.createWorkflowCatalog()insrc/catalog/catalog.tsis the real one — events, entities, actions and operations behind one interface;createFixtureCatalog()is for tests only. - Add a node type by adding one entry to
NODE_KINDSinsrc/definition/nodes.ts. The mapped type makes a missing entry a compile error, which is the only thing stopping a new node type from validating clean with no handles and no checks at all. - Take operator names from
Operatorin@carbon/utils— Carbon's one condition vocabulary, shared with storage rules.OPERATORS_BY_TYPEdecides which of them a workflow may use where; it does not invent names. - Keep zod unions flat and avoid recursive generics.
apps/erpsits near TypeScript's instantiation budget, so new type surface here can trip TS2589 in unrelated files. - Add an entity, a moment, an action or an operation by editing one hand-written file in
src/catalog/—entities.ts,moments.ts,actions.ts,operations.ts— then runpnpm run generate:workflow-catalog. Nothing else insrc/catalog/is authored by hand. - Declare a
permission: { module, action }on every action and operation. It is required onCatalogActionandCatalogOperation(optional onCatalogEntity), and it is what the engine checks before the node runs —NodeExecutor.permissionreturns it, so the gate and the work come from the same catalog entry and cannot drift. - Reach the world from
src/runtime/only throughctx.services— theWorkflowServicesport (runAction/runOperation/search) declared insrc/runtime/types.tsand required onRuntimeContext, so a missing implementation is a compile error rather than a run-time surprise.@carbon/jobssupplies the one implementation.
Never
- Never import from
@carbon/reactor anything app-specific.@carbon/databaseis a devDependency used for types only (ColumnOf/TableNameinsrc/catalog/entities.ts) — never import it as a value. Runtime dependencies arezod,@carbon/utils,@lingui/core, and@internationalized/date(browser-safe, ES2019-safe date/timezone maths). Do not add a fifth without asking first. - Never reimplement timezone-aware schedule maths in a consumer. The next-occurrence logic lives in
src/definition/schedule.ts(nextOccurrenceAfter,nextRunAfter,scheduleOffsetSeconds) and is used by the scheduler and the phase-8 preview; both must call this, not re-derive it. - Never hand-edit
src/catalog/*.generated.ts— regenerate instead. - Never import
src/catalog/labels.generated.ts(WORKFLOW_LABELS) from anything but a Vite-built app.msgis a build-time macro; plain Node (the matcher, the engine, any vitest run) throws on import. That is why labels are a separate file from the runtime catalog, and whysrc/catalog/index.tsdoes not re-export them. - Never import
src/catalog/fromsrc/definition/. The catalog is injected into the validator, not baked into it;createFixtureCatalog'somit*options exist to prove that. - Never let a stored node/edge shape reach a consumer without going through the schema.
- Never represent a list of lists — a list's
ofaccepts scalars only, by construction. - Never import a Node builtin (
node:crypto,node:dns, …) or write a BigInt literal here.apps/erpcompiles this package's source for the browser at ES2019 — that is why hashing goes throughfnv1a64from@carbon/utilsand why the webhook's HMAC and DNS guard live in@carbon/jobs, behindWorkflowServices.
Layout
src/definition/
├── types.ts # value types, operators, refs, literals, templates, clauses, schedules
├── issues.ts # WorkflowIssueCode + WorkflowIssue
├── schema.ts # node/edge/definition schemas, format version, handle names, caps
├── batch.ts # batchCandidates + batchPlan — whether an action repeats, read off the wiring
├── nodes.ts # NODE_KINDS — what each node type declares about itself
├── normalize.ts # readWorkflowVersion + the migrateDefinition seam
├── catalog.ts # WorkflowCatalog + RequiredPermission + walkPath + createFixtureCatalog
└── validate.ts # validateDefinition -> WorkflowIssue[]
src/catalog/
├── entities.ts # HAND-WRITTEN. 16 record types — 10 triggerable (watch) + 6 reference-only; write = the update allowlist
├── moments.ts # HAND-WRITTEN. 9 business events (WORKFLOW_MOMENTS, source of truth) + labels + outputs; re-exports the moment TYPES from @carbon/workflows-core
├── actions.ts # HAND-WRITTEN. 6 actions — 4 creates, notify, webhook
├── operations.ts # HAND-WRITTEN. 15 read-only computations over one record
├── build.ts # buildCatalog(registry, moments, actions, operations, schema) — pure, schema injected
├── events.generated.ts # COMMITTED. WORKFLOW_EVENTS (106) + WORKFLOW_ENTITIES (16). No Lingui import
├── actions.generated.ts # COMMITTED. WORKFLOW_ACTION_CATALOG (16) + WORKFLOW_OPERATION_CATALOG (15)
├── labels.generated.ts # COMMITTED. WORKFLOW_LABELS — one msg`` per event, action and operation id
├── catalog.ts # createWorkflowCatalog() -> WorkflowCatalog, plus getActionRoute
└── index.ts # barrel (labels deliberately excluded)
src/runtime/
├── types.ts # RuntimeValue, Resolution, EntityLoader, WorkflowServices, RuntimeContext, NodeResult, NodeExecutor
├── values.ts # value constructors + fromColumn coercion
├── resolve.ts # refs, the current item and templates -> a value, or a readable reason
├── compare.ts # operator semantics + clause evaluation
├── condition.ts # the Condition executor
├── filter.ts # the Filter executor
├── compute.ts # the Compute executor — one catalog operation
├── lookup.ts # the Lookup executor — one search
├── action.ts # the Action executor — one item, never a loop
├── executors.ts # EXECUTORS: node kind -> executor. A kind with no entry refuses to run
├── batch.ts # planBatch + itemKeyFor
├── template.ts # re-export of renderTemplate / renderValue (they live in resolve.ts)
├── fixtures.ts # TEST-ONLY fake loader/context. Not exported from the package root
└── index.ts # barrel
src/run-trigger.ts # re-exports runTriggerSchema / RunTrigger from @carbon/workflows-core — what fired a run; the leaf (not this engine) is what @carbon/lib and @carbon/jobs depend on
src/sync.ts # trigger-event + subscription reconciler
src/runtime/ is pure: no I/O, no database client, no Supabase. Records are read
through the injected EntityLoader, and everything else that touches the world goes
through WorkflowServices; @carbon/jobs implements both over the workflow owner's
own connection. Comparison semantics live in runtime/compare.ts and must not be
re-implemented anywhere else.
Permission and execution share one EXECUTORS entry per node kind. Two lookups could
drift, and the one that drifts silently is the permission check — so a new kind is one
registry line, never an extended node.type chain.
sync.ts — deriving what the matcher reads
Five exports, all re-exported from the package root:
deriveWorkflowTriggerRows(nodes)— trigger nodes → one desiredworkflowTriggerEventrow per event id, carrying that node's origin (a duplicated id keeps the first origin). Throws if the stored nodes do not parse.deriveWorkflowSubscriptions(eventIds)— event ids → oneworkflow-<table>eventSystemSubscriptionper distinct table with exactly the operations those events need, resolved through each event's catalogmatch. Moments contribute nothing.findTriggerSchedule(nodes)— returns theSchedulefrom the trigger node, ornullif the workflow is event-triggered. Throws if nodes fail to parse.syncWorkflowTriggers(db, companyId, workflowId)— rewrites one workflow's trigger rows, writesworkflow.nextRunAt(the scheduler's bookmark), and reconciles the company's subscriptions in one transaction. Returns{ eventIds, tables, scheduled }. Call it on promote, on trigger edit, and on activate/deactivate.syncWorkflowSubscriptions(db, companyId)— standalone repair from existing rows.
Kysely is imported type-only (import type { Kysely, Transaction } from "kysely"), so
it stays a devDependency and this package keeps its four runtime dependencies
(zod, @carbon/utils, @lingui/core, @internationalized/date). Kysely also bypasses
RLS — the caller authorizes first (the activation route gates on workflows_update).
This is the one thing here that lives in this package for a dependency reason rather than a
conceptual one: it needs WORKFLOW_EVENTS, and @carbon/database (its more natural home,
beside event.ts) cannot depend on @carbon/ee/workflows without creating the package cycle
Turborepo rejects. See .claude/rules/workflow-matcher.md.
The event catalog
One customer-facing concept — an event — from two hand-written inputs. A record type with
8 watched columns yields 10 events (created, deleted, one per column); there is deliberately
no generic updated event. Moments cover what a row change cannot express. Downstream,
nothing knows which input produced an event: only the match block distinguishes them, and only
the matcher in @carbon/jobs reads it.
buildCatalog takes the swagger schema as an argument rather than importing it, which is what
keeps @carbon/database out of this package's runtime graph and lets the transform be unit-tested
in place. Entity properties are generated from the table's own columns so a customer can reach any
property by typing a dot; a foreign key becomes an entity ref only when its target is in the
registry, and a ref that disagrees with the schema's foreign key is a build error.
scripts/check-workflow-catalog.ts (CI job catalog) enforces: every moment is raised somewhere,
every raise site names a declared moment, every watched and writable column still exists, every
action's call names a real tool in tool-metadata.json, and the committed catalog — events,
entities, actions, operations and labels — matches a fresh build. A declared-but-never-raised
moment is a trigger a customer can subscribe to that can never fire — worse than a missing one, so
it fails the build.
Actions and operations
The other half of the catalog: what a workflow can do, and what it can work out. Both are
built by the same buildCatalog into src/catalog/actions.generated.ts.
- Actions (
WORKFLOW_ACTION_CATALOG, 16). Six are hand-written inactions.ts— four record creates (job.create,nonConformance.create,purchaseOrder.create,salesOrder.create), plusnotifyandwebhook. The other ten are the<entity>.updatefamily, generated from each registry entry'swriteallowlist — an entity with nowriteblock yields no update action, which is how "a workflow may set this field" stays a deliberate, reviewed decision rather than the whole table.build.tsrefuses identity and audit columns outright, and a hand-written id colliding with a generated one is a build error. - Operations (
WORKFLOW_OPERATION_CATALOG, 15). Read-only computations over a single record — one input, one scalar out — for things a property map cannot reach: stored totals live only on views (no trigger, not dot-readable) and counts span child tables.
Two fields exist for the job side and are deliberately kept off CatalogAction, which the
validator reads: call (a tool name in tool-metadata.json, so a create goes through the ERP's
own upsert service function) and update (the entity whose columns to write). Read them through
getActionRoute(id) — routing off the shape of an id would let something that merely reads like
x.update reach the update path. requireOneOf is on CatalogAction, because "at least one of
user or role" is a validation rule, not a routing detail. tool-metadata.json lives at
apps/erp/app/routes/api+/mcp+/lib/; after changing a service signature run pnpm run generate:mcp.
Implementations live in packages/jobs/src/workflows/actions/ — see
.claude/rules/workflow-actions.md. Every action and operation declares the permission its
implementation needs; nothing here executes anything.
Values a customer can plug in
valueOrRefSchema is a flat union of five forms: a literal, a {kind:"variable"} ref, the
{kind:"item"} current item, and a {kind:"template"} — text with variable and item parts
interleaved, which is how a customer writes "Order {record.readableId} needs attention". A template
is only valid where a string is expected; anywhere else is a TYPE_MISMATCH saying a message
can only be text. Its parts are checked one at a time so a bad variable names its own place, and
renderTemplate (in src/runtime/resolve.ts, re-exported from template.ts to avoid an import
cycle) fails the whole template if any part fails to resolve — a blank would be a silent lie.
What a part may hold is narrower than what a value may be: rendersAsText (definition/types.ts)
rejects a record and a list of records, and checkTemplateParts in validate.ts raises a
TYPE_MISMATCH at <field>.parts.<n> for one. A record has no reading as text — it would flatten
to whichever column looked name-ish, or to a raw id — so the property is what the customer meant.
The builder's variable menu passes textOnly for the same reason: it hides the record row and
still drills into it.
The fifth form is {kind:"pairs"} — named rows, carrying the webhook action's request headers.
It is legal only where a catalog input sets pairs: true, and such an input accepts nothing
else; both directions are a TYPE_MISMATCH in checkInputs. A row's value is a PairValue, the
four simple forms — a pairs inside a pairs is unrepresentable rather than merely invalid, so no
recursive schema is needed. Rows flatten to <field>.entries.<n> sites in expandTemplate, so a
bad reference or a record dropped into a header value reports at its own row.
CatalogInput.showWhen ({ input, equals }) gates both visibility and requiredness: a
gated-off input is never MISSING_INPUT, and a value left behind on one is INCOMPLETE_CONFIG.
It reads literals only — a gate whose target holds a variable cannot be read at build time, so it
opens rather than hiding the customer's work. buildCatalog refuses a showWhen naming an unknown
input, one whose target has no choices, or one expecting a value outside them.
CatalogInput.defaultValue is what the builder seeds a new node's input with; nothing reads it at
run time, and buildCatalog refuses one outside the input's choices. It is not a fallback — a
required input with a default is still MISSING_INPUT when a stored node omits it.
RuntimeValue has a matching fourth kind, {kind:"pairs"}, which is runtime-only: no
ValueType names it, so it is never compared, looped over, or produced as a step output. It exists
so a resolved header set stays recognisable to the run log's redactor.
Node kinds
Everything one node type does — handles, values, outputs, the list it loops over, type checks,
config checks — lives in its single NODE_KINDS entry, seven members the mapped type makes
mandatory. validate.ts owns only the cross-cutting layers below; it never switches on a node type.
loopList is where "which single list does this step work through" is answered once: a filter's
source, the one list wired into an action's single-value input, and undefined for every other
kind. A filter's outputs are its loop list; the item a {kind:"item"} value reads is that list's
of. Inputs that are themselves {kind:"item"} are skipped when looking for it, which is what
stops the item type asking for itself. An action's answer comes from batchPlan in batch.ts —
nothing is stored, so the only failure is two lists leaving it ambiguous.
validateDefinition
Returns WorkflowIssue[]; empty means activatable. Checks run in layers, each assuming the
previous passed, so a customer is never shown type errors that are really a broken shape:
- Shape — the document parses, no duplicate node ids.
- Trigger — exactly one; either events or a schedule, never both; the schedule is coherent.
- Edges — both endpoints exist, and the handle exists on the source node.
- Graph — no cycle; every non-trigger step is reachable from the trigger.
- References — every value plugged into a node resolves: a variable names a real, genuinely upstream value with a resolvable property path, and "the current item" is only read inside a step that works through a list.
- Types — required inputs supplied, types match, a
list<T>never feeds a single-Tinput unless the action isbatchable(in which case that wiring is what makes it repeat), and an input the catalog does not declare isUNKNOWN_INPUT(a lookup rule naming a property the entity does not have uses the same code). Without that check a definition could quietly carry a field the executor would silently drop. - Configuration — every event/action/operation/entity id exists; no action has lists wired into two
of its single-value inputs; every
requireOneOfgroup has at least one of its inputs supplied; nothing left half-configured.
There is one resolver and one failure vocabulary (ResolveFailure): layer 5 walks every value,
whatever form it takes, and every layer's type question goes through it. Adding a second private
pipeline beside it is how a customer ends up shown a symptom above its own cause.
unconfigured is the silent failure, and it is what keeps a single mistake to a single issue: layer
5 says nothing when the value it cannot resolve depends on something another layer already reports —
a node whose catalog entry is missing, or a looping node that has not settled on a list. Layer 6
skips such a node outright (configured() on its node kind), so an unknown action reports one
UNKNOWN_ACTION rather than that plus a pile of consequent input and item errors. A filter is always
configured — a source that is not a list is a type error the filter reports itself.
Two invariants worth knowing, both regression-tested: a reference must resolve to a strict
ancestor, which is what stops a node reading its own output and is why the output resolver needs no
re-entry guard; and a literal's value is checked against its declared type at parse time, since
every other check compares declared types only.
The workflowTriggerEvent invariant
A workflowTriggerEvent row exists if and only if the workflow has a published version and
that version's trigger nodes list that event id. Publishing a version, editing the published
version's trigger, and unpublishing must all rewrite the workflow's rows —
delete-then-insert in the same transaction as the change. If these drift, a workflow silently
stops firing or fires when it should not.
Two deploy-time checks in packages/checks watch for that drift against a live database (they need
one, so they are not CI jobs): the workflow-trigger-event-drift SQL invariant compares the rows to
the trigger nodes, and pnpm --filter @carbon/checks workflow-events confirms every subscribed
event id still exists in the catalog.
Validation Commands
pnpm --filter @carbon/ee test # vitest
pnpm --filter @carbon/ee exec tsc --noEmit # typecheck
pnpm exec biome check packages/ee/src/workflows # lint
pnpm run generate:workflow-catalog # after editing entities/moments/actions/operations.ts
pnpm run check:workflow-catalog # the CI `catalog` job
Changing Operator in @carbon/utils also needs
pnpm --filter @carbon/utils test and pnpm exec turbo run typecheck --filter=erp.
Custom fields (round 2)
src/catalog/custom-fields.ts is the per-company overlay. The catalog is build-time and
global; custom fields are runtime and per company, so they are merged in rather than generated.
buildCatalogOverlay(defs)→{ properties, labels, enums, actionInputs }, keyed by the ONE-segment property pathcustomFields.<fieldId>(the field's id, which is the key inside the JSONB blob). One segment keepswalkPathand the runtimewalksingle-step.- It holds the ONLY
DataType → ValueTypemap.itemand reference-only entities are excluded. createWorkflowCatalog(overlay?)merges generated first, overlay second — a real column always wins, and the shipped keys keep their order at the top of every picker.WorkflowCataloggainedgetPropertyLabel(entity, property)andgetInputLabel(actionId, input). They return the customer's own field name, which is customer data and is deliberately never translated.getCatalogEvent(id)is the single event lookup: the committed map, thenresolveCustomFieldEvent, which PARSES<entity>.customFields.<fieldId>.changedinto a syntheticCatalogEvent.WORKFLOW_EVENTSstays closed and drift-checked.sync.tsuses it too, which is what gives a custom-field trigger itsUPDATEsubscription.
links and ctx.linkFor
CatalogInput.links (LinksDeclaration: a format of markdown, slack or html, plus an
optional when: { input, equals } gate on a sibling input) marks an input as prose that its
destination renders with links. resolveStepInputs (runtime/resolve.ts, shared by the action
and integration executors) asks linkState (definition/links.ts) per input; only a linked
input goes through renderTemplate(template, ctx, { linkFor, format }), which wraps a record
part in that dialect's renderer (LINK_RENDERERS) and escapes every other value for it
(TEXT_ESCAPERS: html and Slack mrkdwn; a value is customer data, never markup, so
AT&T <Sales> or <!channel> reads as written). Every other input, a webhook body included,
renders the record's plain name. The builder's hints (notices.ts) read the same linkState.
This package constructs no URL — it is bundled for the browser with four runtime dependencies
and cannot import @carbon/env; the engine supplies ctx.linkFor.
rendersAsText now accepts a whole record (it prints as its readable id) and still refuses a
LIST of records.