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.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: LicenseRef-Carbon-Commercial
// Carbon Enterprise file, licensed only under the Carbon Commercial License
// (packages/ee/LICENSE). Not AGPL. Running, modifying, or copying it beyond those terms requires a commercial license.
import { type BatchableStep, type BatchPlan, batchPlan } from "./batch";
import {
type CatalogInput,
integrationStepId,
type WorkflowCatalog
} from "./catalog";
import { dataNodeKind } from "./data-node";
import type { WorkflowIssue } from "./issues";
import {
type ActionNode,
type ComputeNode,
DEFAULT_HANDLE,
DEFAULT_OUTPUT,
FAILURE_HANDLE,
type IntegrationNode,
SUCCESS_HANDLE,
type WorkflowNode,
type WorkflowNodeType
} from "./schema";
import {
type Clause,
canAssign,
describeType,
expectedClauseRightType,
operatorsForType,
type ScalarType,
typesEqual,
type ValueOrRef,
type ValueType
} from "./types";
export type NodeOutputs = Record<string, ValueType>;
/** `unconfigured` is suppressed — another layer reports the real cause. */
export type ResolveFailure =
| "unknown-node"
| "not-upstream"
| "unknown"
| "unconfigured"
| "no-loop";
export type ResolvedRef = { type: ValueType } | { failure: ResolveFailure };
type ListType = Extract<ValueType, { kind: "list" }>;
/** Names that frame the request rather than describe it. Letting a customer set one
* changes how the message is delivered, not what it says. */
const RESERVED_HEADER_NAMES = new Set([
"host",
"content-length",
"connection",
"transfer-encoding",
"upgrade",
"te",
"keep-alive",
"proxy-authorization"
]);
/** The list a looping node works through, or why it is not settled. */
export type LoopList = { type: ListType } | { failure: ResolveFailure };
/** One value plugged into a node — literal, variable or current item. */
export interface ValueSite {
value: ValueOrRef;
field: string;
}
/** What a node can ask about the rest of the definition. Implemented in `validate.ts`. */
export interface NodeContext {
catalog: WorkflowCatalog;
resolveValue(value: ValueOrRef, atNodeId: string): ResolvedRef;
typeOf(value: ValueOrRef, atNodeId: string): ValueType | undefined;
outputsOf(nodeId: string): NodeOutputs | undefined;
/** `card` scopes the answer to one operation card of a data-node chain;
* every other kind ignores it. */
loopListOf(nodeId: string, card?: string): LoopList | undefined;
}
/** Everything one kind of node declares about itself. */
export interface NodeKind<N extends WorkflowNode> {
/** Outgoing connection points, by name. */
handles(node: N): string[];
values(node: N): ValueSite[];
/** What it hands onward; `undefined` when its catalog entry is missing. */
outputs(node: N, ctx: NodeContext): NodeOutputs | undefined;
/** The one list this node works through, or undefined when it does not loop.
* `card` names an operation card of a data-node chain; other kinds ignore it. */
loopList(node: N, ctx: NodeContext, card?: string): LoopList | undefined;
/** Is its catalog entry resolvable? Type checking is skipped when not. */
configured(node: N, ctx: NodeContext): boolean;
checkTypes(node: N, ctx: NodeContext): WorkflowIssue[];
checkConfig(node: N, ctx: NodeContext): WorkflowIssue[];
}
export function clauseValues(clauses: Clause[], prefix: string): ValueSite[] {
return clauses.flatMap((clause, index) => [
{ value: clause.left, field: `${prefix}.${index}.left` },
...(clause.right === undefined
? []
: [{ value: clause.right, field: `${prefix}.${index}.right` }])
]);
}
/** A draft may save a clause with no right-hand side; publishing one may not. */
export function clauseConfigIssues(
node: WorkflowNode,
clauses: Clause[],
prefix: string
): WorkflowIssue[] {
return clauses.flatMap((clause, index) =>
clause.right === undefined
? [
incomplete(
node,
`${prefix}.${index}.right`,
"Choose what to compare this against."
)
]
: []
);
}
function inputValues(inputs: Record<string, ValueOrRef>): ValueSite[] {
return Object.entries(inputs).map(([field, value]) => ({ value, field }));
}
/** The first operation input wired to a list where the operation expects a single value.
* When set, the compute node runs the operation once per list item and returns a list. */
function computeBatchInput(
node: ComputeNode,
ctx: NodeContext
): string | undefined {
const operation = ctx.catalog.getOperation(node.data.operation);
if (operation === undefined) return undefined;
for (const [name, inputDecl] of Object.entries(operation.inputs)) {
if (inputDecl.type.kind === "list") continue; // already expects a list
const supplied = node.data.inputs[name];
if (supplied === undefined || supplied.kind === "item") continue;
const resolved = ctx.resolveValue(supplied, node.id);
if ("type" in resolved && resolved.type.kind === "list") return name;
}
return undefined;
}
/** The catalog entry a step node runs, or undefined when the id names nothing.
* The wiring decides whether it repeats; nothing is stored. */
function stepDefinition(
node: ActionNode | IntegrationNode,
ctx: NodeContext
): BatchableStep | undefined {
return node.type === "action"
? ctx.catalog.getAction(node.data.action)
: ctx.catalog.getIntegration(
integrationStepId(node.data.piece, node.data.action)
);
}
function stepBatchPlan(
node: ActionNode | IntegrationNode,
ctx: NodeContext
): BatchPlan {
const step = stepDefinition(node, ctx);
if (step === undefined) return { kind: "none" };
return batchPlan(step, node.data.inputs, (name) => {
const supplied = node.data.inputs[name];
return supplied === undefined ? undefined : ctx.typeOf(supplied, node.id);
});
}
function stepLoopList(
node: ActionNode | IntegrationNode,
ctx: NodeContext
): LoopList | undefined {
// With no catalog entry there is nothing to read the wiring against. `unconfigured`
// is suppressed, so an item ref reports the missing step rather than piling on.
if (stepDefinition(node, ctx) === undefined) {
return { failure: "unconfigured" };
}
const plan = stepBatchPlan(node, ctx);
if (plan.kind === "none") return undefined;
return plan.kind === "repeats"
? { type: plan.type }
: { failure: "unconfigured" };
}
/**
* The action and the integration kinds. Both run one catalog step, so they share
* every check; only how the step is chosen differs, which `unchosen` reports
* before the catalog is asked.
*/
function stepNodeKind<N extends ActionNode | IntegrationNode>(
unchosen: (node: N) => WorkflowIssue[]
): NodeKind<N> {
return {
handles: () => [SUCCESS_HANDLE, FAILURE_HANDLE],
values: (node) => inputValues(node.data.inputs),
outputs: (node, ctx) => stepDefinition(node, ctx)?.outputs,
loopList: stepLoopList,
configured: (node, ctx) => stepDefinition(node, ctx) !== undefined,
checkTypes: (node, ctx) => {
const step = stepDefinition(node, ctx);
if (step === undefined) return [];
// Ambiguity counts as batching here so two wired lists raise the one issue that
// explains them, rather than that issue plus a rejection of each list.
const batching = stepBatchPlan(node, ctx).kind !== "none";
// Advanced inputs write into the SAME `inputs` bag, so validating only the
// visible ones let an off-enum choice or a mistyped ref reach the vendor
// with no issue raised in the builder.
return checkInputs(
node,
node.data.inputs,
{ ...step.inputs, ...step.advancedInputs },
batching,
ctx
);
},
checkConfig: (node, ctx) => {
const missing = unchosen(node);
if (missing.length > 0) return missing;
const step = stepDefinition(node, ctx);
// Same code for both kinds: to the customer an integration step that no
// longer exists and an action that no longer exists are the same problem.
if (step === undefined) {
return [
{
code: "UNKNOWN_ACTION",
nodeId: node.id,
field: "action",
message: `"${node.data.action}" is not something we can do any more.`
}
];
}
const plan = stepBatchPlan(node, ctx);
if (plan.kind === "ambiguous") {
return [
incomplete(
node,
// Blamed on the second list, since the first was already working.
plan.second,
`Lists are wired into both "${plan.first}" and "${plan.second}", so this step cannot tell which one to repeat over.`
)
];
}
for (const group of step.requireOneOf ?? []) {
if (group.some((name) => node.data.inputs[name] !== undefined))
continue;
return [
incomplete(
node,
group[0] ?? "inputs",
`This step needs at least one of: ${group.join(", ")}.`
)
];
}
return [];
}
};
}
export function checkClauses(
node: WorkflowNode,
clauses: Clause[],
prefix: string,
ctx: NodeContext
): WorkflowIssue[] {
const issues: WorkflowIssue[] = [];
clauses.forEach((clause, index) => {
const field = `${prefix}.${index}`;
const left = ctx.typeOf(clause.left, node.id);
if (left === undefined) return;
if (!operatorsForType(left).includes(clause.operator)) {
issues.push({
code: "TYPE_MISMATCH",
nodeId: node.id,
field: `${field}.operator`,
message: `"${clause.operator}" is not a test you can apply to ${describeType(left)}.`
});
return;
}
// An absent right-hand side is a completeness problem, not a type one.
if (clause.right === undefined) return;
const right = ctx.typeOf(clause.right, node.id);
if (right === undefined) return;
const expected = expectedClauseRightType(left, clause.operator);
if (!typesEqual(right, expected)) {
issues.push({
code: "TYPE_MISMATCH",
nodeId: node.id,
field: `${field}.right`,
message: `This compares ${describeType(left)} against ${describeType(right)}.`
});
}
});
return issues;
}
function checkInputs(
node: WorkflowNode,
inputs: Record<string, ValueOrRef>,
declared: Record<string, CatalogInput>,
batching: boolean,
ctx: NodeContext
): WorkflowIssue[] {
const issues: WorkflowIssue[] = [];
/** Literal-only: a gate whose target holds a variable cannot be read here, so it opens. */
const gateValue = (declaration: CatalogInput): string | undefined => {
const gate = declaration.showWhen;
if (gate === undefined) return undefined;
const target = inputs[gate.input];
if (target === undefined || target.kind !== "literal") return undefined;
if (typeof target.value !== "string") return undefined;
return gate.equals.includes(target.value) ? undefined : target.value;
};
for (const [name, declaration] of Object.entries(declared)) {
const supplied = inputs[name];
const closedBy = gateValue(declaration);
if (closedBy !== undefined) {
if (supplied !== undefined) {
issues.push({
code: "INCOMPLETE_CONFIG",
nodeId: node.id,
field: name,
message: `"${name}" does not apply when ${declaration.showWhen?.input} is "${closedBy}". Clear it to continue.`
});
}
continue;
}
if (supplied === undefined) {
if (declaration.required) {
issues.push({
code: "MISSING_INPUT",
nodeId: node.id,
field: name,
message: `"${name}" needs a value before this step can run.`
});
}
continue;
}
if (supplied.kind === "pairs" || declaration.pairs === true) {
if (supplied.kind !== "pairs") {
issues.push({
code: "TYPE_MISMATCH",
nodeId: node.id,
field: name,
message: `"${name}" takes a list of names and values.`
});
continue;
}
if (declaration.pairs !== true) {
issues.push({
code: "TYPE_MISMATCH",
nodeId: node.id,
field: name,
message: `"${name}" does not take a list of names and values.`
});
continue;
}
const seen = new Set<string>();
supplied.entries.forEach((entry, index) => {
const field = `${name}.entries.${index}`;
const key = entry.name.trim().toLowerCase();
if (key === "") {
issues.push({
code: "INCOMPLETE_CONFIG",
nodeId: node.id,
field,
message: "This row needs a name."
});
return;
}
if (RESERVED_HEADER_NAMES.has(key)) {
issues.push({
code: "INCOMPLETE_CONFIG",
nodeId: node.id,
field,
message: `"${entry.name}" is set by Carbon and cannot be changed here.`
});
return;
}
if (seen.has(key)) {
issues.push({
code: "INCOMPLETE_CONFIG",
nodeId: node.id,
field,
message: `"${entry.name}" is set twice.`
});
return;
}
seen.add(key);
});
continue;
}
if (supplied.kind === "template") {
if (
declaration.type.kind === "primitive" &&
declaration.type.of === "string"
) {
continue;
}
issues.push({
code: "TYPE_MISMATCH",
nodeId: node.id,
field: name,
message: `"${name}" takes ${describeType(declaration.type)}, and a message can only be text.`
});
continue;
}
const type = ctx.typeOf(supplied, node.id);
if (type === undefined) continue;
if (declaration.type.kind !== "list" && type.kind === "list") {
if (canAssign(type, declaration.type, { batching })) continue;
issues.push({
code: "LIST_INTO_SINGLE",
nodeId: node.id,
field: name,
message: `"${name}" takes one ${describeType(declaration.type)}, but this is ${describeType(type)}. This step cannot work through a list.`
});
continue;
}
if (!typesEqual(type, declaration.type)) {
issues.push({
code: "TYPE_MISMATCH",
nodeId: node.id,
field: name,
message: `"${name}" takes ${describeType(declaration.type)}, but this is ${describeType(type)}.`
});
}
if (declaration.choices !== undefined && supplied.kind === "literal") {
// A multi-select stores a list, so every member has to be checked — a single
// string test would wave the whole array through unread.
const picked = Array.isArray(supplied.value)
? supplied.value
: [supplied.value];
for (const value of picked) {
if (typeof value !== "string") continue;
if (declaration.choices.includes(value)) continue;
issues.push({
code: "INCOMPLETE_CONFIG",
message: `"${value}" is not a valid ${name}.`,
nodeId: node.id,
field: `inputs.${name}`
});
}
}
}
// Without this a definition could quietly carry a field the executor would drop.
for (const name of Object.keys(inputs)) {
if (declared[name] !== undefined) continue;
issues.push({
code: "UNKNOWN_INPUT",
nodeId: node.id,
field: name,
message: `"${name}" is not something this step can set.`
});
}
return issues;
}
export const incomplete = (
node: WorkflowNode,
field: string,
message: string
): WorkflowIssue => ({
code: "INCOMPLETE_CONFIG",
nodeId: node.id,
field,
message
});
export const NODE_KINDS: {
[K in WorkflowNodeType]: NodeKind<Extract<WorkflowNode, { type: K }>>;
} = {
trigger: {
handles: () => [DEFAULT_HANDLE],
values: () => [],
outputs: (node, ctx) => {
if (node.data.schedule !== undefined) return {};
const eventId = node.data.events[0];
if (eventId === undefined) return undefined;
const event = ctx.catalog.getEvent(eventId);
if (event === undefined) return undefined;
return { ...event.outputs };
},
loopList: () => undefined,
configured: (node, ctx) =>
node.data.schedule !== undefined ||
(node.data.events.length > 0 &&
node.data.events.every((id) => ctx.catalog.getEvent(id) !== undefined)),
checkTypes: () => [],
checkConfig: (node, ctx) =>
node.data.events
.filter((eventId) => ctx.catalog.getEvent(eventId) === undefined)
.map((eventId) => ({
code: "UNKNOWN_EVENT" as const,
nodeId: node.id,
field: eventId,
message: `"${eventId}" is not something we can watch for any more.`
}))
},
condition: {
handles: (node) => node.data.paths.map((path) => path.id),
values: (node) =>
node.data.paths.flatMap((path) =>
clauseValues(path.clauses, `paths.${path.id}.clauses`)
),
outputs: () => ({}),
loopList: () => undefined,
configured: () => true,
checkTypes: (node, ctx) =>
node.data.paths.flatMap((path) =>
checkClauses(node, path.clauses, `paths.${path.id}.clauses`, ctx)
),
checkConfig: (node) => {
if (node.data.paths.length === 0) {
return [
incomplete(node, "paths", "Add at least one branch to this check.")
];
}
const empty = node.data.paths
.filter((path) => path.kind !== "else" && path.clauses.length === 0)
.map((path) =>
incomplete(
node,
`paths.${path.id}.clauses`,
"This branch has nothing to check."
)
);
if (empty.length > 0) return empty;
return node.data.paths.flatMap((path) =>
clauseConfigIssues(node, path.clauses, `paths.${path.id}.clauses`)
);
}
},
compute: {
handles: () => [DEFAULT_HANDLE],
values: (node) => inputValues(node.data.inputs),
outputs: (node, ctx) => {
const operation = ctx.catalog.getOperation(node.data.operation);
if (operation === undefined) return undefined;
const batchInput = computeBatchInput(node, ctx);
if (batchInput !== undefined && operation.output.kind !== "list") {
return {
[DEFAULT_OUTPUT]: { kind: "list", of: operation.output as ScalarType }
};
}
return { [DEFAULT_OUTPUT]: operation.output };
},
loopList: (node, ctx) => {
const operation = ctx.catalog.getOperation(node.data.operation);
if (operation === undefined) return { failure: "unconfigured" };
const batchInput = computeBatchInput(node, ctx);
if (batchInput === undefined || operation.output.kind === "list")
return undefined;
return { type: { kind: "list", of: operation.output as ScalarType } };
},
configured: (node, ctx) =>
ctx.catalog.getOperation(node.data.operation) !== undefined,
checkTypes: (node, ctx) => {
const operation = ctx.catalog.getOperation(node.data.operation);
if (operation === undefined) return [];
const batchInput = computeBatchInput(node, ctx);
return checkInputs(
node,
node.data.inputs,
operation.inputs,
batchInput !== undefined,
ctx
);
},
checkConfig: (node, ctx) => {
if (node.data.operation.length === 0) {
return [incomplete(node, "operation", "Choose what to work out.")];
}
if (ctx.catalog.getOperation(node.data.operation) !== undefined)
return [];
return [
{
code: "UNKNOWN_OPERATION",
nodeId: node.id,
field: "operation",
message: `"${node.data.operation}" is not something we can work out any more.`
}
];
}
},
lookup: {
handles: () => [SUCCESS_HANDLE, FAILURE_HANDLE],
values: (node) =>
node.data.match.flatMap((rule, index) =>
rule.value === undefined
? []
: [{ value: rule.value, field: `match.${index}.value` }]
),
outputs: (node, ctx) => {
const entity = ctx.catalog.getEntity(node.data.entity);
if (entity === undefined) return undefined;
const one: ValueType = { kind: "entity", of: entity.name };
return {
[DEFAULT_OUTPUT]:
node.data.returns === "list" ? { kind: "list", of: one } : one
};
},
loopList: () => undefined,
configured: (node, ctx) =>
ctx.catalog.getEntity(node.data.entity) !== undefined,
checkTypes: (node, ctx) => {
const entity = ctx.catalog.getEntity(node.data.entity);
if (entity === undefined) return [];
const issues: WorkflowIssue[] = [];
node.data.match.forEach((rule, index) => {
const field = `match.${index}`;
// A blank rule is reported by `checkConfig`; typing it would be noise.
if (rule.field === "" || rule.value === undefined) return;
const property = entity.properties[rule.field];
if (property === undefined) {
issues.push({
code: "UNKNOWN_INPUT",
nodeId: node.id,
field: `${field}.field`,
message: `A ${entity.name} has no "${rule.field}".`
});
return;
}
if (!operatorsForType(property).includes(rule.operator)) {
issues.push({
code: "TYPE_MISMATCH",
nodeId: node.id,
field: `${field}.operator`,
message: `"${rule.operator}" is not a test you can apply to ${describeType(property)}.`
});
return;
}
const supplied = ctx.typeOf(rule.value, node.id);
if (supplied === undefined) return;
// `contains` on a list tests membership, so the value is one item.
const expected =
property.kind === "list" && rule.operator === "contains"
? property.of
: property;
if (!typesEqual(supplied, expected)) {
issues.push({
code: "TYPE_MISMATCH",
nodeId: node.id,
field: `${field}.value`,
message: `This compares ${describeType(property)} against ${describeType(supplied)}.`
});
}
});
return issues;
},
checkConfig: (node, ctx) => {
if (node.data.entity.length === 0) {
return [
incomplete(node, "entity", "Choose what kind of record to find.")
];
}
if (ctx.catalog.getEntity(node.data.entity) === undefined) {
return [
{
code: "UNKNOWN_ENTITY",
nodeId: node.id,
field: "entity",
message: `"${node.data.entity}" is not a kind of record we know.`
}
];
}
const issues: WorkflowIssue[] = [];
node.data.match.forEach((rule, index) => {
if (rule.field === "") {
issues.push(
incomplete(
node,
`match.${index}.field`,
"Choose which property to match on."
)
);
return;
}
if (rule.value === undefined) {
issues.push(
incomplete(
node,
`match.${index}.value`,
"Choose what to match this property against."
)
);
return;
}
const choices = ctx.catalog.getEnum(node.data.entity, rule.field);
if (
choices !== undefined &&
rule.value.kind === "literal" &&
typeof rule.value.value === "string" &&
!choices.includes(rule.value.value)
) {
issues.push({
code: "INCOMPLETE_CONFIG",
message: `"${rule.value.value}" is not a valid ${rule.field}.`,
nodeId: node.id,
field: `match.${index}.value`
});
}
});
return issues;
}
},
filter: dataNodeKind,
action: stepNodeKind<ActionNode>((node) =>
node.data.action.length === 0
? [incomplete(node, "action", "Choose what this step should do.")]
: []
),
integration: stepNodeKind<IntegrationNode>((node) => {
if (node.data.piece.length === 0) {
return [incomplete(node, "piece", "Choose an integration.")];
}
if (node.data.action.length === 0) {
return [incomplete(node, "action", "Choose what this step should do.")];
}
return [];
})
};
// Cast: TypeScript cannot see that `NODE_KINDS[node.type]` and `node` narrow to
// the same member of the union.
function kindOf<N extends WorkflowNode>(node: N): NodeKind<N> {
return NODE_KINDS[node.type] as unknown as NodeKind<N>;
}
export const getNodeHandles = (node: WorkflowNode): string[] =>
kindOf(node).handles(node);
export const getNodeValues = (node: WorkflowNode): ValueSite[] =>
kindOf(node).values(node);
export const getNodeOutputs = (
node: WorkflowNode,
ctx: NodeContext
): NodeOutputs | undefined => kindOf(node).outputs(node, ctx);
export const getNodeLoopList = (
node: WorkflowNode,
ctx: NodeContext,
card?: string
): LoopList | undefined => kindOf(node).loopList(node, ctx, card);
export const isNodeConfigured = (
node: WorkflowNode,
ctx: NodeContext
): boolean => kindOf(node).configured(node, ctx);
export const checkNodeTypes = (
node: WorkflowNode,
ctx: NodeContext
): WorkflowIssue[] => kindOf(node).checkTypes(node, ctx);
export const checkNodeConfig = (
node: WorkflowNode,
ctx: NodeContext
): WorkflowIssue[] => kindOf(node).checkConfig(node, ctx);