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 { MachineState } from "./types";
/**
* The attribution engine: which job operation gets a device's run time.
* Pure — no database, no env — so it imports nothing but types. The rules are
* in `.claude/rules/oee-provider.md` → "Attribution rules".
*
* The sensor decides WHETHER the machine ran. The owner of each moment of a
* run decides WHO gets it:
*
* - a moment while maintenance blocks the work center → the queue;
* - a moment after an operator press in the same run → the queue (the press
* stopped the operator's time, not the machine);
* - else the operation loaded at that moment, if it can still take time;
* - else the queue.
*
* The facts give the same owners whatever order they arrive in. Time that a
* Machine event or an unattributed row already holds is never recorded again.
*
* Instants are compared with `Date.parse`: they are absolute UTC instants,
* the narrow exception in `.claude/rules/date-handling.md`.
*/
export type StoredStateChange = { changedAt: string; state: MachineState };
/**
* One load of an operation on the work center (`workCenterLoad`): from
* `from` until `to` (null while it is still loaded). `assignable` is false
* once the operation is Done or Canceled or its job is locked.
*/
export type LoadPeriod = {
jobOperationId: string;
from: string;
to: string | null;
assignable: boolean;
};
/** A period maintenance blocks the work center (`to` null while it does). */
export type BlockPeriod = { from: string; to: string | null };
/** Time a Machine event or an unattributed row already holds. */
export type RecordedInterval = {
id: string;
kind: "event" | "unattributed";
startTime: string;
endTime: string | null;
};
export type PlanMachineTimeInput = {
now: string;
minimumStateSeconds: number;
/** When the device was mapped to the work center. */
mappedAt: string;
currentState: MachineState | null;
currentStateAt: string | null;
/** The latest operator press. */
lastManualChangeAt: string | null;
/** The earliest press since the last sync, or null when there was none. */
firstUnplannedPressAt: string | null;
/** The work center's loads that may overlap the time planned. */
loads: LoadPeriod[];
/** The work center's maintenance blocks that may overlap the time planned. */
blocks: BlockPeriod[];
/** The newest open Machine event; `system` when the sync created it. */
openMachineEvent: {
id: string;
jobOperationId: string;
startTime: string;
system: boolean;
} | null;
openUnattributed: { id: string; startTime: string } | null;
lastMachineEventEndTime: string | null;
/** Machine events and unattributed rows around the presses. */
recordedIntervals: RecordedInterval[];
/** Stored changes after `appliedThrough`, ascending by `changedAt`. */
changes: StoredStateChange[];
};
export type MachineTimeWrite =
| {
kind: "insertMachineEvent";
jobOperationId: string;
startTime: string;
endTime: string | null;
}
| { kind: "closeMachineEvent"; productionEventId: string; endTime: string }
| { kind: "insertUnattributed"; startTime: string; endTime: string | null }
| { kind: "closeUnattributed"; unattributedId: string; endTime: string }
| {
kind: "updateUnattributed";
unattributedId: string;
startTime: string;
endTime: string;
}
| { kind: "deleteUnattributed"; unattributedId: string };
export type PlanMachineTimeResult = {
writes: MachineTimeWrite[];
currentState: MachineState | null;
currentStateAt: string | null;
/** `changedAt` of the last consumed change; null when nothing was consumed. */
appliedThrough: string | null;
};
type Interval = { startTime: string; endTime: string };
/**
* An open interval: an event or a queue row this run found (`id` set) or
* opened. `owner` is the operation, or null for the queue; `system` is false
* only for an operator's event.
*/
type Slot = {
id: string | null;
owner: string | null;
startTime: string;
system: boolean;
};
const at = (iso: string) => Date.parse(iso);
const contains = (
period: { from: string; to: string | null },
instant: string
) =>
at(period.from) <= at(instant) &&
(period.to === null || at(instant) < at(period.to));
/** The parts of `[start, end)` that no recorded interval holds. */
function unrecordedParts(
start: string,
end: string,
recorded: { startTime: string; endTime: string | null }[]
): Interval[] {
const parts: Interval[] = [];
let cursor = start;
const sorted = [...recorded].sort(
(a, b) => at(a.startTime) - at(b.startTime)
);
for (const interval of sorted) {
if (at(cursor) >= at(end)) break;
if (interval.endTime !== null && at(interval.endTime) <= at(cursor)) {
continue;
}
if (at(interval.startTime) >= at(end)) break;
if (at(interval.startTime) > at(cursor)) {
parts.push({ startTime: cursor, endTime: interval.startTime });
}
if (interval.endTime === null) return parts;
if (at(interval.endTime) > at(cursor)) cursor = interval.endTime;
}
if (at(cursor) < at(end)) parts.push({ startTime: cursor, endTime: end });
return parts;
}
/** `interval` less `cut`: zero, one or two intervals. */
function subtract(interval: Interval, cut: Interval): Interval[] {
return [
{ startTime: interval.startTime, endTime: cut.startTime },
{ startTime: cut.endTime, endTime: interval.endTime }
]
.map((part) => ({
startTime:
at(part.startTime) < at(interval.startTime)
? interval.startTime
: part.startTime,
endTime:
at(part.endTime) > at(interval.endTime)
? interval.endTime
: part.endTime
}))
.filter((part) => at(part.endTime) > at(part.startTime));
}
export function planMachineTime(
input: PlanMachineTimeInput
): PlanMachineTimeResult {
const writes: MachineTimeWrite[] = [];
const minimumMs = input.minimumStateSeconds * 1000;
const lastPress = input.lastManualChangeAt;
const presses = [input.firstUnplannedPressAt, lastPress].filter(
(press): press is string => press !== null
);
const recorded = [...input.recordedIntervals];
let state = input.currentState;
let stateAt = input.currentStateAt;
let appliedThrough: string | null = null;
const slots: Slot[] = [];
if (input.openMachineEvent) {
slots.push({
id: input.openMachineEvent.id,
owner: input.openMachineEvent.jobOperationId,
startTime: input.openMachineEvent.startTime,
system: input.openMachineEvent.system
});
}
if (input.openUnattributed) {
slots.push({
id: input.openUnattributed.id,
owner: null,
startTime: input.openUnattributed.startTime,
system: true
});
}
// ── Owners ──────────────────────────────────────────────────────────────
const blocked = (instant: string) =>
input.blocks.some((block) => contains(block, instant));
const pressedInRun = (instant: string, runStart: string) =>
presses.some(
(press) => at(runStart) < at(press) && at(press) <= at(instant)
);
const ownerAt = (instant: string, runStart: string) => {
if (blocked(instant) || pressedInRun(instant, runStart)) return null;
const load = input.loads.find((period) => contains(period, instant));
return load?.assignable ? load.jobOperationId : null;
};
// Where an owner can change: a load or a block begins or ends, or a press.
const edges = [
...input.loads.flatMap((load) => [load.from, load.to]),
...input.blocks.flatMap((block) => [block.from, block.to]),
...presses
]
.filter((edge): edge is string => edge !== null)
.sort((a, b) => at(a) - at(b));
const edgesWithin = (start: string, end: string) =>
edges.filter((edge) => at(edge) > at(start) && at(edge) < at(end));
// ── Writes ──────────────────────────────────────────────────────────────
// Closed time goes to its owner. Queue time shorter than the minimum is
// dropped, like a short state.
const writeClosed = (
{ startTime, endTime }: Interval,
owner: string | null
) => {
const interval = { startTime, endTime };
if (owner) {
writes.push({
kind: "insertMachineEvent",
jobOperationId: owner,
...interval
});
} else if (at(interval.endTime) - at(interval.startTime) >= minimumMs) {
writes.push({ kind: "insertUnattributed", ...interval });
} else {
return;
}
recorded.push({
id: "",
kind: owner ? "event" : "unattributed",
...interval
});
};
// A slot that ends at or before its start writes nothing new, and an
// existing one closes at its own start.
const closeSlot = (slot: Slot, end: string) => {
const ends = at(end) > at(slot.startTime);
if (slot.id === null) {
if (ends)
writeClosed({ startTime: slot.startTime, endTime: end }, slot.owner);
return;
}
const endTime = ends ? end : slot.startTime;
writes.push(
slot.owner === null
? { kind: "closeUnattributed", unattributedId: slot.id, endTime }
: { kind: "closeMachineEvent", productionEventId: slot.id, endTime }
);
// The interval it held now ends: replace the open one read from the
// database, if there is one.
const held = recorded.findIndex((interval) => interval.id === slot.id);
if (held >= 0) recorded.splice(held, 1);
recorded.push({
id: slot.id,
kind: slot.owner === null ? "unattributed" : "event",
startTime: slot.startTime,
endTime
});
};
const closeSlots = (end: string, which: (slot: Slot) => boolean) => {
for (const slot of slots.filter(which)) {
slots.splice(slots.indexOf(slot), 1);
closeSlot(slot, end);
}
};
// The pieces of `[start, end)` that nothing holds, split where the owner
// changes, each written to its owner. A piece that reaches `now` while the
// machine runs opens instead (a queue piece once it has lasted the
// minimum, so a machine winding down after a Pause records nothing).
const recordRun = (start: string, end: string, runStart: string) => {
for (const part of unrecordedParts(start, end, recorded)) {
const bounds = [
part.startTime,
...edgesWithin(part.startTime, part.endTime),
part.endTime
];
const pieces: (Interval & { owner: string | null })[] = [];
for (const [i, startTime] of bounds.slice(0, -1).entries()) {
const endTime = bounds[i + 1] ?? startTime;
if (at(endTime) <= at(startTime)) continue;
const owner = ownerAt(startTime, runStart);
const last = pieces.at(-1);
if (last && last.owner === owner) last.endTime = endTime;
else pieces.push({ owner, startTime, endTime });
}
for (const piece of pieces) {
if (piece.endTime !== input.now || state !== "Running") {
writeClosed(piece, piece.owner);
} else if (
piece.owner ||
at(input.now) - at(piece.startTime) >= minimumMs
) {
slots.push({
id: null,
owner: piece.owner,
startTime: piece.startTime,
system: true
});
}
}
}
};
// Open slots follow their owner up to `until`: where the owner changes, a
// slot closes and the new owner records the rest. An operator's event
// follows only maintenance: a block stops it, a load change does not.
const follow = (until: string) => {
const runStart = stateAt ?? until;
for (const slot of [...slots]) {
const change = slot.system
? edgesWithin(slot.startTime, until).find(
(edge) => ownerAt(edge, runStart) !== slot.owner
)
: input.blocks
.map((block) => block.from)
.find(
(from) => at(from) > at(slot.startTime) && at(from) < at(until)
);
if (!change) continue;
slots.splice(slots.indexOf(slot), 1);
closeSlot(slot, change);
recordRun(change, until, runStart);
}
};
// ── Late stops trim the queue ──────────────────────────────────────────
// A stop reported only after a press: a queue row that the press closed
// may hold time the machine was idle. Queue rows are not posted, so they
// are cut to the running time. Machine events are never trimmed.
const trimIdle = (idle: Interval) => {
for (const interval of [...recorded]) {
if (
interval.kind !== "unattributed" ||
!interval.id ||
interval.endTime === null ||
at(idle.endTime) <= at(interval.startTime) ||
at(idle.startTime) >= at(interval.endTime)
) {
continue;
}
const row = { startTime: interval.startTime, endTime: interval.endTime };
const [first, second] = subtract(row, idle);
recorded.splice(recorded.indexOf(interval), 1);
if (!first) {
writes.push({
kind: "deleteUnattributed",
unattributedId: interval.id
});
continue;
}
writes.push({
kind: "updateUnattributed",
unattributedId: interval.id,
...first
});
recorded.push({ ...interval, ...first });
if (second) {
writes.push({ kind: "insertUnattributed", ...second });
recorded.push({ id: "", kind: "unattributed", ...second });
}
}
};
// ── The time around the presses ────────────────────────────────────────
// Time before the last press that no sync planned yet: from the earliest
// unplanned press when the machine already ran then, or from a late
// Running change. It ends at a late stop, or at the last press.
let unplanned: { from: string; runStart: string } | null =
state === "Running" &&
stateAt !== null &&
input.firstUnplannedPressAt !== null &&
at(stateAt) <= at(input.firstUnplannedPressAt)
? { from: input.firstUnplannedPressAt, runStart: stateAt }
: null;
let idleFrom: string | null = null;
// A machine running at the last press and still running after it.
// (Typed by a cast: only the closures below assign it, which TypeScript's
// narrowing cannot see.)
let pastPress = null as { from: string; runStart: string } | null;
let pressCrossed = false;
// Leaving the time before the last press. `end` is a stop still pending
// before the press: the run may end there, so nothing past it is recorded
// until it settles.
const crossPress = (end: string | null) => {
if (pressCrossed || lastPress === null) return;
pressCrossed = true;
if (unplanned) {
recordRun(unplanned.from, end ?? lastPress, unplanned.runStart);
}
unplanned = null;
if (idleFrom !== null)
trimIdle({ startTime: idleFrom, endTime: lastPress });
idleFrom = null;
if (
end === null &&
state === "Running" &&
stateAt !== null &&
at(stateAt) <= at(lastPress)
) {
pastPress = { from: lastPress, runStart: stateAt };
}
};
const apply = (next: MachineState, changedAt: string) => {
if (next === state) return;
// A change at or before the last press: the press decided what came
// after it, so this fills only the time the press could not see.
if (lastPress !== null && at(changedAt) <= at(lastPress)) {
if (next === "Running") {
if (idleFrom !== null) {
trimIdle({ startTime: idleFrom, endTime: changedAt });
idleFrom = null;
}
unplanned = { from: changedAt, runStart: changedAt };
} else {
if (unplanned) {
recordRun(unplanned.from, changedAt, unplanned.runStart);
unplanned = null;
}
idleFrom = changedAt;
}
state = next;
stateAt = changedAt;
return;
}
crossPress(null);
if (next === "Running") {
state = next;
stateAt = changedAt;
if (slots.length === 0) {
slots.push({
id: null,
owner: ownerAt(changedAt, changedAt),
startTime: changedAt,
system: true
});
}
return;
}
follow(changedAt);
if (pastPress) {
recordRun(pastPress.from, changedAt, pastPress.runStart);
pastPress = null;
}
closeSlots(changedAt, () => true);
state = next;
stateAt = changedAt;
};
let changes = input.changes;
// First sync: the last change before the mapping is the starting state, at
// the time of the mapping. Time before the mapping is never charged.
if (state === null) {
const mappedAt = at(input.mappedAt);
const before = changes.filter((c) => at(c.changedAt) <= mappedAt);
changes = changes.filter((c) => at(c.changedAt) > mappedAt);
const seed = before.at(-1);
if (seed) {
appliedThrough = seed.changedAt;
apply(seed.state, input.mappedAt);
}
}
// Repeated reports of one state are one run: the first starts it, the last
// is how far it was read.
const runs: (StoredStateChange & { through: string })[] = [];
for (const change of changes) {
const last = runs.at(-1);
if (last && last.state === change.state) last.through = change.changedAt;
else runs.push({ ...change, through: change.changedAt });
}
// Debounce: a state shorter than the minimum is dropped; the last change
// stays pending until it has lasted the minimum.
let pending: StoredStateChange | null = null;
for (const [i, run] of runs.entries()) {
const next = runs[i + 1];
const end = next ? next.changedAt : input.now;
if (at(end) - at(run.changedAt) < minimumMs) {
if (!next) {
pending = run;
break;
}
appliedThrough = run.through;
continue;
}
apply(run.state, run.changedAt);
appliedThrough = run.through;
}
if (lastPress !== null) {
crossPress(
pending && at(pending.changedAt) <= at(lastPress)
? pending.changedAt
: null
);
}
if (state === "Running") {
// Still running past the press: the time after it that nothing holds.
if (pastPress && slots.length === 0) {
recordRun(pastPress.from, input.now, pastPress.runStart);
}
// Steady state: the machine runs, nothing holds its time, and no press
// decided it — an operation went Done mid-run, or maintenance or End
// Shift closed the event.
if (
slots.length === 0 &&
stateAt !== null &&
(lastPress === null || at(stateAt) > at(lastPress))
) {
const lastEnd = input.lastMachineEventEndTime;
recordRun(
lastEnd && at(lastEnd) > at(stateAt) ? lastEnd : stateAt,
input.now,
stateAt
);
}
follow(input.now);
} else if (stateAt !== null) {
// Stopped by a late change before the press: the engine's own open time
// ends at the stop (or at its start, when it opened after the stop).
closeSlots(stateAt, (slot) => slot.system);
}
// A slot this run opened and did not close is inserted open.
for (const slot of slots) {
if (slot.id !== null) continue;
writes.push(
slot.owner === null
? {
kind: "insertUnattributed",
startTime: slot.startTime,
endTime: null
}
: {
kind: "insertMachineEvent",
jobOperationId: slot.owner,
startTime: slot.startTime,
endTime: null
}
);
}
return {
writes,
currentState: state,
currentStateAt: stateAt,
appliedThrough
};
}