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.
/**
* Applying ledger delegation: when another system posts a GL family, Carbon
* must stop sending BOTH that family's journals and its backing documents.
*
* Each half alone is wrong, which is why this is one derivation rather than two
* settings a human keeps in sync:
*
* - `families[x] = "none"` alone does NOT stop the document push —
* `reconcileDocument` never reads `families`, only `entityPushEnabled`.
* - disabling the entity alone parks a `DOC_SYNC_DISABLED` Warning on every
* posted document forever (`posting.ts`), because the policy then sees a
* document-represented journal whose backing document does not sync.
*
* WHICH entity to disable is derived from `POSTING_POLICY`, never hard-coded.
* That table already declares each source type's family and backing entity, so
* delegating `ap` disables `bill` AND `reimbursement` — the latter landed after
* this rule was written and needed no edit. A version hard-coding `"bill"`
* would have kept pushing reimbursements to the GL alongside the other
* system's copy.
*/
import { POSTING_POLICY } from "../accounting/core/models";
import type { PostingSyncSettings } from "../accounting/core/posting";
import type { GlobalSyncConfig } from "../accounting/core/types";
import type { LedgerFamilyKey } from "./capabilities";
import type { IntegrationTopology } from "./topology";
/**
* `PostingSyncSettings` that have been through {@link applyLedgerDelegation}.
*
* The policy decision accepts only this type, so a caller cannot reach a
* posting decision with raw settings — the compiler is the enforcement, at the
* one place the decision is made rather than at every place metadata is parsed.
*/
export type EffectivePostingSyncSettings = PostingSyncSettings & {
readonly ledgerDelegationApplied: true;
};
/**
* The backing entities of a family, from `POSTING_POLICY`.
*
* Two sentinels are skipped, for the same reason: a `per-line` family
* (`Payment`) is shared between AR and AP and resolved per journal from its
* control-account lines, and a `per-party` backing entity (the memos) is
* resolved per record from the memo's party. Disabling either wholesale would
* break the side that is still Carbon-owned.
*/
export function backingEntitiesOfFamily(
family: LedgerFamilyKey
): Array<keyof GlobalSyncConfig["entities"]> {
const entities = new Set<keyof GlobalSyncConfig["entities"]>();
for (const entry of Object.values(POSTING_POLICY)) {
const backing = entry.backingEntityType;
if (!backing || backing === "per-party") continue;
if (entry.family === "ar" || entry.family === "ap") {
if (entry.family === family) {
entities.add(backing as keyof GlobalSyncConfig["entities"]);
}
continue;
}
// per-line / per-party families resolve per record — never wholesale.
}
// The memo families have no static POSTING_POLICY row (their source types are
// "per-party"), but they DO have their own entities, and delegating one means
// Carbon stops pushing that document.
if (family === "creditMemo" || family === "supplierCredit") {
entities.add(family as keyof GlobalSyncConfig["entities"]);
}
return [...entities];
}
export type DelegationResult = {
settings: EffectivePostingSyncSettings;
syncConfig: GlobalSyncConfig;
/** Families this company does not post itself, for messaging. */
delegated: Array<{ family: LedgerFamilyKey; integrationId: string }>;
};
export function applyLedgerDelegation(args: {
settings: PostingSyncSettings;
syncConfig: GlobalSyncConfig;
topology: IntegrationTopology;
/**
* WHOSE configuration this is.
*
* A family is delegated AWAY from Carbon's accounting provider and TO another
* integration — so the delegate must keep pushing the documents it was handed.
* Without this, resolving Ramp's own config disabled Ramp's bill entity,
* because Ramp owns `ap`: the spend platform stopped receiving the very
* documents the delegation exists to route to it. Observed live 2026-09-26 —
* no bill operation was enqueued at all, while purchase orders (no family)
* pushed normally.
*
* Optional so existing accounting-provider callers are unaffected: they never
* own a delegated family, so passing their id changes nothing.
*/
integrationId?: string;
}): DelegationResult {
const families = { ...args.settings.families };
const entities = { ...args.syncConfig.entities };
const delegated: DelegationResult["delegated"] = [];
for (const [family, owner] of Object.entries(args.topology.ledgerOwnership)) {
if (owner.kind !== "external") continue;
// The owner keeps its own family. Delegation redirects a family to this
// integration; it must not also switch it off here.
if (args.integrationId && owner.integrationId === args.integrationId) {
continue;
}
const key = family as LedgerFamilyKey;
delegated.push({ family: key, integrationId: owner.integrationId });
families[key] = "none";
for (const entity of backingEntitiesOfFamily(key)) {
const current = entities[entity];
if (current) entities[entity] = { ...current, enabled: false };
}
}
return {
settings: {
...args.settings,
families,
ledgerDelegationApplied: true
} as EffectivePostingSyncSettings,
syncConfig: { entities },
delegated
};
}
/**
* Treat settings as if nothing is delegated.
*
* For the SECONDARY gates only — a provider syncer's own
* `getPostingSyncSourceTypeSkipReason` check, which runs after the primary gate
* has already decided. A delegated family cannot reach a syncer: its backing
* entity is disabled, so `reconcileDocument` enqueues nothing, and its journals
* record `FAMILY_OFF` rather than a push. The syncer is defence-in-depth on a
* path that is already closed.
*
* Never use this where the decision is actually MADE — that is what
* `applyLedgerDelegation` is for, and the branded type is what stops the two
* being confused.
*/
export function asCarbonOwnedSettings(
settings: PostingSyncSettings
): EffectivePostingSyncSettings {
return { ...settings, ledgerDelegationApplied: true };
}