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: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
/**
* The work-done event catalog.
*
* "Work done" means a record was created, a state changed in a way that means
* work happened, a quantity was recorded against reality, or something was sent
* outward. Opening a screen is not work; neither is searching, filtering, or a
* write that happens as a side effect of viewing a page.
*
* Every event here answers a question a plant manager or an operator would ask
* by name. The full catalog these are drawn from, including the deferred waves
* and the reasoning per event, lives in `adoption-tracking/work-done-events.md`
* alongside this repo.
*
* ## What may go in a payload
*
* Ids, enum values, counts, and physical quantities. Nothing else.
*
* Deliberately excluded: monetary amounts, part numbers, item descriptions,
* customer and supplier names, free text of any kind. Adoption is measured in
* counts and elapsed time, so values add sensitivity without adding signal —
* and Carbon sells to defense and aerospace accounts whose part numbers and
* order values are the sensitive part. An id is resolvable against the
* customer's own database when someone genuinely needs the detail.
*
* @see ./capture.ts for how these reach PostHog.
*/
/** The Carbon module a piece of work belongs to. Used to group adoption by area. */
export type WorkModule =
| "production"
| "inventory"
| "sales"
| "purchasing"
| "invoicing";
/**
* Which surface the work was entered from.
*
* This is the single most useful property in the catalog: it separates a shop
* floor genuinely using the MES from a clerk typing yesterday's paper traveller
* into the back office. Nothing else distinguishes those two, and they mean
* completely different things about adoption.
*/
export type WorkSource = "erp" | "mes" | "mes_qr" | "api" | "portal";
/**
* Where a job came from.
*
* A separate axis from `WorkSource`: every creation path funnels through one
* service function and the `job` row itself cannot tell them apart, so the
* caller has to say. The distinction is the difference between a shop planning
* its work and a shop reacting to one.
*/
export const JOB_SOURCES = [
"erp",
"bulk",
"mrp",
"salesOrder",
"kanban",
"api",
"workflow",
/**
* The caller did not say. Reaching `insertJob` without a source is normal —
* the MCP tool and the workflow engine both dispatch `production_insertJob`
* by name through a generic (call, context, inputs) signature that has
* nowhere to put one. Defaulting those to `erp` would report automation as
* human work, which is the single thing this field exists to separate.
*/
"unknown"
] as const;
export type JobSource = (typeof JOB_SOURCES)[number];
/**
* Narrow an untrusted value to a `JobSource`, falling back to `unknown`.
*
* `insertJob` is reachable as an MCP tool, and the generated tool schema types
* this parameter as `{}` — the generator resolves inline unions but not an
* imported alias — so nothing between a caller and the event enforces the set.
* TypeScript is not a runtime guard here: without this, an agent passing
* `source: "banana"` would put "banana" in the analytics enum permanently.
*/
export function asJobSource(value: unknown): JobSource {
return JOB_SOURCES.includes(value as JobSource)
? (value as JobSource)
: "unknown";
}
type Base = {
companyId: string;
/** Carbon `userId` of the actor. Null for service-role and customer-portal work. */
userId: string | null;
};
/**
* Every work event, with the properties it carries.
*
* Adding an entry here is the whole change on the emit side — `captureWorkEvent`
* is typed off this map, so a name that is not in it will not compile, and a
* payload missing a property will not either.
*/
export type WorkEvents = {
// ------------------------------------------------------------- production
job_created: Base & {
jobId: string;
itemId: string;
quantity: number;
scrapQuantity: number;
locationId: string | null;
/** Set when the job was raised to serve a specific sales order line. */
salesOrderLineId: string | null;
deadlineType: string | null;
source: JobSource;
};
job_released: Base & {
jobId: string;
/** What the job was before. A re-save of an already-Ready job never emits. */
priorStatus: string;
/** `kanban` when a scan released it, so auto-releases stay separable. */
source: JobSource;
};
job_operation_started: Base & {
/**
* The `productionEvent` row. An operator clocks on and off a step many
* times, so the operation id would collapse a shift into one event — this
* is what makes each clock-on its own occurrence.
*/
productionEventId: string;
jobOperationId: string;
/** Setup, Labor or Machine. */
eventType: string;
source: WorkSource;
};
production_quantity_reported: Base & {
/** The `productionQuantity` row — one posting, not one operation. */
productionQuantityId: string;
jobOperationId: string;
quantity: number;
/**
* Which surface posted it. The ratio of `mes`/`mes_qr` to `erp` is the best
* single measure of whether the shop floor app is genuinely in use or a
* clerk is typing yesterday's paper traveller into the back office.
*/
source: WorkSource;
};
job_operation_finished: Base & {
jobOperationId: string;
jobId: string;
};
job_completed: Base & {
jobId: string;
/** `manual` from the complete route; `auto` when the last operation closed it. */
path: "manual" | "auto";
};
scrap_reported: Base & {
/** The `productionQuantity` row carrying type 'Scrap'. */
productionQuantityId: string;
jobOperationId: string;
quantity: number;
scrapReasonId: string | null;
source: WorkSource;
};
// -------------------------------------------------------------- inventory
receipt_posted: Base & {
receiptId: string;
/** Purchase Order, Inbound Transfer, and so on. */
sourceDocument: string | null;
};
shipment_posted: Base & {
shipmentId: string;
/** Sales Order, Purchase Order (outside processing), Outbound Transfer. */
sourceDocument: string | null;
};
picking_list_completed: Base & {
pickingListId: string;
/** Completed, Partial or Cancelled. */
finalStatus: string;
/** `mes` when the floor closed it, `erp` when the office did. */
source: WorkSource;
};
// ------------------------------------------------------------------ sales
quote_sent: Base & {
quoteId: string;
};
quote_accepted: Base & {
quoteId: string;
salesOrderId: string;
/** `portal` means the customer accepted it themselves, with no Carbon user. */
acceptedBy: "internal" | "portal";
};
sales_order_confirmed: Base & {
salesOrderId: string;
lineCount: number;
/** The status the line mix derived — To Ship and Invoice, and so on. */
derivedStatus: string;
emailed: boolean;
};
// ------------------------------------------------------------- purchasing
purchase_order_finalized: Base & {
purchaseOrderId: string;
/**
* Where the order got to, and the discriminator — one `gated` and one
* `committed` event per order, never two of either.
*
* `gated`: the finalize stopped at an approval threshold. Nothing is owed
* to the supplier yet, so this must never be counted as spend.
* `committed`: the order is live. Reached either directly, when no
* threshold applied, or later from `approveRequest` when an approver
* released a gated one — a different module, which is why a single emit on
* the finalize route left approved orders uncounted entirely.
*
* "POs issued this week" is `stage = committed`.
*/
stage: "gated" | "committed";
};
// --------------------------------------------------------------- invoicing
sales_invoice_posted: Base & {
salesInvoiceId: string;
};
purchase_invoice_posted: Base & {
purchaseInvoiceId: string;
};
};
export type WorkEventName = keyof WorkEvents;
/** Which module each event belongs to, for grouping adoption by area. */
export const WORK_EVENT_MODULE: Record<WorkEventName, WorkModule> = {
job_created: "production",
job_released: "production",
job_operation_started: "production",
production_quantity_reported: "production",
job_operation_finished: "production",
job_completed: "production",
scrap_reported: "production",
receipt_posted: "inventory",
shipment_posted: "inventory",
picking_list_completed: "inventory",
quote_sent: "sales",
quote_accepted: "sales",
sales_order_confirmed: "sales",
purchase_order_finalized: "purchasing",
sales_invoice_posted: "invoicing",
purchase_invoice_posted: "invoicing"
};
export const WORK_EVENT_NAMES = Object.keys(
WORK_EVENT_MODULE
) as WorkEventName[];
/** The payload keys of one event that hold a string id. */
type IdKeyOf<E extends WorkEventName> = {
[K in keyof WorkEvents[E]]: WorkEvents[E][K] extends string ? K : never;
}[keyof WorkEvents[E]];
/**
* The record whose id makes an occurrence unique, per event.
*
* Used to build the idempotency key, so a retry collapses instead of counting
* twice. Where an event can legitimately recur against one record — a second
* production quantity on the same operation — the emit site supplies a
* discriminator as well.
*/
export const WORK_EVENT_RECORD_KEY: {
[E in WorkEventName]: IdKeyOf<E>;
} = {
job_created: "jobId",
job_released: "jobId",
job_operation_started: "productionEventId",
production_quantity_reported: "productionQuantityId",
job_operation_finished: "jobOperationId",
job_completed: "jobId",
scrap_reported: "productionQuantityId",
receipt_posted: "receiptId",
shipment_posted: "shipmentId",
picking_list_completed: "pickingListId",
quote_sent: "quoteId",
quote_accepted: "quoteId",
sales_order_confirmed: "salesOrderId",
purchase_order_finalized: "purchaseOrderId",
sales_invoice_posted: "salesInvoiceId",
purchase_invoice_posted: "purchaseInvoiceId"
};