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 { CatalogInput, LinkFormat } from "../definition/catalog";
import { linkState } from "../definition/links";
import type {
ItemRef,
Pairs,
Template,
ValueOrRef,
VariableRef
} from "../definition/types";
import type { Resolution, RuntimeContext, RuntimeValue } from "./types";
import {
fromColumn,
fromLiteral,
isNull,
nullValue,
pairsValue,
primitiveValue
} from "./values";
export async function resolveValue(
value: ValueOrRef,
ctx: RuntimeContext
): Promise<Resolution> {
if (value.kind === "literal") return { ok: true, value: fromLiteral(value) };
if (value.kind === "item") return resolveItem(value, ctx);
if (value.kind === "template") return renderTemplate(value, ctx);
if (value.kind === "pairs") return resolvePairs(value, ctx);
return resolveRef(value, ctx);
}
/** All a SYNCHRONOUS reading of a record can offer: no catalog to ask which column names it,
* no loader to fetch one. `entityText` is what names a record properly. */
const INLINE_ENTITY_COLUMNS = ["readableId", "name"];
/** The first of `columns` this row holds a non-blank value for. */
function pickDisplay(
row: Record<string, unknown> | null | undefined,
columns: readonly string[]
): string | undefined {
if (row === null || row === undefined) return undefined;
for (const column of columns) {
const raw = row[column];
if (raw === null || raw === undefined) continue;
const text = String(raw).trim();
if (text !== "") return text;
}
return undefined;
}
/** How one resolved value reads inside a sentence. */
export function renderValue(value: RuntimeValue): string {
if (isNull(value)) return "";
if (value.kind === "list") return value.items.map(renderValue).join(", ");
if (value.kind === "entity")
return pickDisplay(value.row, INLINE_ENTITY_COLUMNS) ?? value.id;
// Neither rows nor objects have a reading as a sentence, and `rendersAsText`
// keeps both out of a template — this is the belt to that suspenders.
if (value.kind === "pairs" || value.kind === "record") return "";
return value.value === null ? "" : String(value.value);
}
/** How a record READS: the name a person would recognise it by — `SO000123`, not `so_x8f2`.
* The row is fetched when the value carries no snapshot, which is most of them: a moment
* output, a created record and a foreign key all arrive as a bare id. Reads go through the
* loader, so they are the owner's and cached for the run; an unreadable one falls back to
* the id rather than failing a message over a label. */
async function entityText(
value: Extract<RuntimeValue, { kind: "entity" }>,
ctx: RuntimeContext
): Promise<string> {
// The catalog's own display columns first, then the conventional ones: an entity
// that declares none still reads by the name it carries rather than by its id.
const columns = [
...(ctx.catalog.getEntity(value.of)?.display ?? []),
...INLINE_ENTITY_COLUMNS
];
return (
pickDisplay(value.row, columns) ??
pickDisplay(await ctx.loader.load(value.of, value.id), columns) ??
value.id
);
}
const escapeHtml = (raw: string) =>
raw
.replaceAll("&", "&")
.replaceAll("<", "<")
.replaceAll(">", ">")
.replaceAll('"', """);
// Slack mrkdwn: `&`, `<`, `>` are the only escapes. Unescaped, a value holding
// `<!channel>` pings the channel and `<url|text>` becomes a link.
const escapeSlack = (raw: string) =>
raw.replaceAll("&", "&").replaceAll("<", "<").replaceAll(">", ">");
/** How a value that is not a link reads in each dialect. A value is customer data,
* never markup: in an html body or a Slack message it is escaped, so a customer
* named `AT&T <Sales>` reads as written. Markdown is Carbon's own notification
* renderer, which already treats it as text. */
const TEXT_ESCAPERS: Record<LinkFormat, (text: string) => string> = {
markdown: (text) => text,
slack: escapeSlack,
html: escapeHtml
};
/** One entry per destination dialect. A record's NAME is customer data, so each
* renderer sanitises the label until it cannot break out of its own link; the href
* is Carbon's own URL from `linkFor`, never user text. */
const LINK_RENDERERS: Record<
LinkFormat,
(label: string, href: string) => string
> = {
// The link matcher's label cannot hold a `]` and honours no backslash escape, so a
// record named `PO](…)` would end the label early and pick the destination itself.
// Drop the brackets; a name that is nothing but brackets stays unlinked.
markdown: (label, href) => {
const clean = label.replace(/[[\]]/g, "").trim();
return clean === "" ? label : `[${clean}](${href})`;
},
// Slack mrkdwn `<url|label>`: `&`, `<`, `>` are the only escapes and `|` would end
// the label early, so it is dropped the way markdown drops brackets.
slack: (label, href) => {
const clean = escapeSlack(label).replaceAll("|", "");
return clean.trim() === "" ? escapeSlack(label) : `<${href}|${clean}>`;
},
html: (label, href) =>
`<a href="${escapeHtml(href)}">${escapeHtml(label)}</a>`
};
/** How a template turns a record into a link: where it lives, and in whose dialect. */
export interface RenderOptions {
linkFor?: (of: string, id: string) => string | null;
/** Defaults to markdown — the dialect Carbon's own notification renderer reads. */
format?: LinkFormat;
}
/**
* A record in prose reads as its name, and becomes a link when the caller knows
* where it lives — in the destination's own dialect. Every other value renders
* as `renderValue` does, escaped for the dialect — a LIST of records never
* reaches here, because `rendersAsText` refuses one as a template part.
*/
export async function renderPart(
value: RuntimeValue,
ctx: RuntimeContext,
options?: RenderOptions
): Promise<string> {
const format = options?.format ?? "markdown";
const escape = TEXT_ESCAPERS[format];
if (value.kind !== "entity") return escape(renderValue(value));
const text = await entityText(value, ctx);
if (options?.linkFor === undefined || text === "") return escape(text);
const href = options.linkFor(value.of, value.id);
if (href === null) return escape(text);
return LINK_RENDERERS[format](text, href);
}
/** An unresolvable part fails the whole template; a blank would be a silent lie. */
export async function renderTemplate(
template: Template,
ctx: RuntimeContext,
options?: RenderOptions
): Promise<Resolution> {
const pieces: string[] = [];
for (const part of template.parts) {
if (part.kind === "text") {
pieces.push(part.text);
continue;
}
const resolved =
part.kind === "item"
? await resolveItem(part, ctx)
: await resolveRef(part, ctx);
if (!resolved.ok) return resolved;
pieces.push(await renderPart(resolved.value, ctx, options));
}
return { ok: true, value: primitiveValue("string", pieces.join("")) };
}
/** One unresolvable row fails the whole set, exactly as one bad part fails a template:
* a request sent with a header quietly missing is worse than one not sent at all. */
export async function resolvePairs(
pairs: Pairs,
ctx: RuntimeContext
): Promise<Resolution> {
const entries: { name: string; value: RuntimeValue }[] = [];
for (const entry of pairs.entries) {
if (entry.name.trim() === "") continue;
const resolved = await resolveValue(entry.value, ctx);
if (!resolved.ok) return resolved;
entries.push({ name: entry.name.trim(), value: resolved.value });
}
return { ok: true, value: pairsValue(entries) };
}
export async function resolveRef(
ref: VariableRef,
ctx: RuntimeContext
): Promise<Resolution> {
const outputs = ctx.outputs[ref.nodeId];
if (outputs === undefined) {
return {
ok: false,
reason: "The step that produces this value did not run."
};
}
const value = outputs[ref.output];
if (value === undefined) {
return { ok: false, reason: `This step did not produce "${ref.output}".` };
}
return walk(value, ref.path, ctx);
}
export async function resolveItem(
ref: ItemRef,
ctx: RuntimeContext
): Promise<Resolution> {
if (ctx.item === undefined) {
return { ok: false, reason: "There is no current item here." };
}
return walk(ctx.item, ref.path, ctx);
}
/** A null anywhere along the path ends the walk as null rather than failing. */
export async function walk(
start: RuntimeValue,
path: string[],
ctx: RuntimeContext
): Promise<Resolution> {
let current = start;
for (const segment of path) {
if (isNull(current)) return { ok: true, value: current };
// A record holds its data inline, so there is nothing to load. A field the
// vendor did not send reads as null rather than failing the step — the schema
// it was declared from is the vendor's, and nothing validates it.
if (current.kind === "record") {
current = current.fields[segment] ?? nullValue();
continue;
}
if (current.kind !== "entity") {
return {
ok: false,
reason: `"${segment}" is not something this value has.`
};
}
const entity = ctx.catalog.getEntity(current.of);
if (entity === undefined) {
return {
ok: false,
reason: `We no longer know what a ${current.of} is.`
};
}
const property = entity.properties[segment];
if (property === undefined) {
return { ok: false, reason: `A ${current.of} has no "${segment}".` };
}
const row = current.row ?? (await ctx.loader.load(current.of, current.id));
if (row === null) {
return {
ok: false,
reason: `The ${current.of} this refers to could not be read.`
};
}
current = fromColumn(property, row[segment]);
}
return { ok: true, value: current };
}
/**
* A step's inputs, resolved for one run of it — shared by the action and the
* integration executors so the two kinds cannot drift apart. `declared` is every
* input the step declares.
*
* A record in prose becomes a link only where the catalog declares `links` (and
* its gate holds — see `linkState`) and the engine supplied a resolver; everything
* else renders as plain text, so a link can never ship to a field that would show
* it as literal markup (a webhook body, a vendor's plain-text field).
*/
export async function resolveStepInputs(
inputs: Record<string, ValueOrRef>,
declared: Record<string, CatalogInput>,
ctx: RuntimeContext
): Promise<
| { ok: true; inputs: Record<string, RuntimeValue> }
| { ok: false; reason: string }
> {
const resolved: Record<string, RuntimeValue> = {};
for (const [name, value] of Object.entries(inputs)) {
const link = linkState(inputs, declared, name);
const result =
link.kind === "linked" && value.kind === "template"
? await renderTemplate(value, ctx, {
linkFor: ctx.linkFor,
format: link.format
})
: await resolveValue(value, ctx);
if (!result.ok) return result;
// In a batch the one list input stands for the item this turn is on. Only a
// slot declared single-valued can be that input (`batchCandidates`); a slot
// declared as a list keeps its list, or a real list input on the same step
// would be replaced by the item on every turn.
resolved[name] =
ctx.item !== undefined &&
result.value.kind === "list" &&
declared[name]?.type.kind !== "list"
? ctx.item
: result.value;
ctx.record?.(name, resolved[name]);
}
return { ok: true, inputs: resolved };
}