@happyvertical/smrt-manufacturing 0.30.0

package/dist/index.d.ts

@@ -0,0 +1,846 @@
+import { DatabaseConfig } from '@happyvertical/smrt-core';
+import { DispatchBus } from '@happyvertical/smrt-core';
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { StockMovementReason } from '@happyvertical/smrt-inventory';
+import { StockService } from '@happyvertical/smrt-inventory';
+
+export declare class BillOfMaterials extends SmrtObject {
+    /** Tenant scope. `null` means the BOM is a global record. */
+    tenantId: string | null;
+    /**
+     * Plain string reference to the upstream product this BOM produces.
+     * Typically a `Product.id` (or any STI subtype thereof) from
+     * `@happyvertical/smrt-products`. Cross-package id, intentionally not
+     * a `@foreignKey()`, so this package does not pull in `smrt-products`.
+     */
+    productId: string;
+    /**
+     * Monotonically increasing revision number scoped per `productId`. Together
+     * with `tenantId` and `productId` this forms the natural key — so
+     * `version` is an integer and `0` is reserved by convention for unsaved
+     * scratch rows.
+     */
+    version: number;
+    /**
+     * Date from which this BOM is intended to take effect for new production
+     * runs. Optional — older BOMs imported from legacy systems may have no
+     * effective date on file.
+     */
+    effectiveDate: Date | null;
+    /**
+     * Lifecycle state — `draft`, `active`, or `superseded`. See
+     * {@link BomStatus} for the semantics.
+     *
+     * Most queries that pick "the BOM to use right now" should filter for
+     * `status: 'active'`.
+     */
+    status: BomStatus;
+    /**
+     * Optional free-form notes shown in admin UIs (revision reason, source
+     * document reference, sign-off chain, etc.).
+     */
+    notes: string;
+    /**
+     * ISO 4217 currency code for cost rollups. Mostly a hint for the rollup
+     * service — defaults to `'USD'` so older imports without a currency
+     * still produce sensible numbers.
+     */
+    currency: string;
+    constructor(options?: BillOfMaterialsOptions);
+}
+
+export declare class BillOfMaterialsCollection extends SmrtCollection<BillOfMaterials> {
+    static readonly _itemClass: typeof BillOfMaterials;
+    /**
+     * Return every BOM for the given upstream product id, newest version
+     * first. Useful for "show me all revisions of this product's recipe"
+     * admin screens.
+     */
+    findByProduct(productId: string): Promise<BillOfMaterials[]>;
+    /**
+     * Return the currently `active` BOM for the given product, or `null` if
+     * none has been activated yet. When multiple `active` rows exist (which
+     * should not happen but can arise during partial migrations), the
+     * highest-version row wins.
+     */
+    findActiveForProduct(productId: string): Promise<BillOfMaterials | null>;
+    /**
+     * Return every BOM with the given lifecycle status across all products.
+     * Mostly useful for admin dashboards (e.g. "show every draft BOM").
+     */
+    findByStatus(status: BomStatus): Promise<BillOfMaterials[]>;
+}
+
+/**
+ * Options accepted by the {@link BillOfMaterials} constructor.
+ */
+export declare interface BillOfMaterialsOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    productId?: string;
+    version?: number;
+    effectiveDate?: Date | string | null;
+    status?: BomStatus;
+    notes?: string;
+    currency?: string;
+}
+
+/**
+ * Aggregate cost rollup returned by {@link BomService.computeMaterialCost}.
+ */
+export declare interface BomCostRollup {
+    /** BOM that was rolled up. */
+    bomId: string;
+    /** Total material cost per produced unit. */
+    totalCost: number;
+    /** ISO 4217 currency code. Defaults to `'USD'`. */
+    currency: string;
+    /** Per-line breakdown. Empty array when the BOM has no lines. */
+    lineBreakdown: BomLineCost[];
+    /**
+     * `true` when at least one line's unit cost could not be resolved.
+     * Callers should treat `totalCost` as a lower bound in that case.
+     */
+    hasMissingCosts: boolean;
+}
+
+export declare class BomLine extends SmrtObject {
+    /** Tenant scope. `null` means the line is a global record. */
+    tenantId: string | null;
+    /**
+     * Plain string reference to the parent {@link BillOfMaterials}. Within
+     * this package this is the only "structural" foreign key — but it is
+     * still stored as a plain string to keep with the package's
+     * cross-reference convention and to avoid coupling the schema generator
+     * to a particular load order.
+     */
+    bomId: string;
+    /**
+     * Plain string reference to the component SKU id (raw material, trim,
+     * sub-assembly). The `Sku` model itself lives in
+     * `@happyvertical/smrt-products`; `@happyvertical/smrt-inventory` uses
+     * this id to track stock levels and movements. Cross-package id;
+     * never `@foreignKey()`.
+     */
+    componentSkuId: string;
+    /**
+     * Quantity of the component required per unit of finished product, in
+     * the unit declared by {@link uom}. Decimal so fractional usage like
+     * `1.75 yards` or `12.5 grams` round-trips correctly.
+     */
+    qtyPerUnit: number;
+    /**
+     * Unit of measure for {@link qtyPerUnit}. Open-ended string so the
+     * framework does not constrain the vocabulary — `'yards'`, `'each'`,
+     * `'grams'`, `'kg'`, `'m'`, `'litres'`, `'sq_ft'`, anything.
+     *
+     * Conventions follow the upstream `Material.uom` value when applicable.
+     */
+    uom: string;
+    /**
+     * Expected percentage waste on this line. Adds to the effective quantity
+     * consumed during cost rollups and requirements explosions so a cutting
+     * yield of 10% surfaces in the total cost without callers having to
+     * pre-inflate `qtyPerUnit`. Stored as a percent (`10` means 10%), not a
+     * fraction (`0.10`).
+     */
+    wastePercent: number;
+    /**
+     * Optional free-form notes — e.g. "primary structural component",
+     * "60-second cure", or "matched batch only".
+     */
+    notes: string;
+    constructor(options?: BomLineOptions);
+    /**
+     * Effective quantity consumed per produced unit, including waste. Used
+     * by {@link BomService} for cost rollups and requirements explosions.
+     *
+     * `effectiveQty = qtyPerUnit * (1 + wastePercent / 100)`
+     */
+    effectiveQtyPerUnit(): number;
+}
+
+export declare class BomLineCollection extends SmrtCollection<BomLine> {
+    static readonly _itemClass: typeof BomLine;
+    /**
+     * Return every line that belongs to the given BOM. Caller-stable order
+     * helps make cost rollups and requirements explosions deterministic.
+     */
+    findByBom(bomId: string): Promise<BomLine[]>;
+    /**
+     * Return every line that references the given component SKU across all
+     * BOMs. Useful for "where is this material used?" admin screens and for
+     * cost-change impact analysis (a price hike on a raw material affects
+     * every BOM in the result).
+     */
+    findByComponent(componentSkuId: string): Promise<BomLine[]>;
+}
+
+/**
+ * Per-line cost breakdown returned by {@link BomService.computeMaterialCost}.
+ * Lets callers surface "here's where the $42 came from" UIs without
+ * recomputing on the client.
+ */
+export declare interface BomLineCost {
+    /**
+     * Plain string reference to a component SKU id. The `Sku` model
+     * itself lives in `@happyvertical/smrt-products`; inventory only
+     * tracks stock motion against that id.
+     */
+    componentSkuId: string;
+    /** Quantity per produced unit (pre-waste). */
+    qtyPerUnit: number;
+    /** Waste percent applied to this line (`0` if none). */
+    wastePercent: number;
+    /** Effective quantity used per produced unit, including waste. */
+    effectiveQty: number;
+    /** Latest known unit cost, or `0` if unavailable. */
+    unitCost: number;
+    /** Effective unit-cost contribution to the rolled-up total. */
+    lineCost: number;
+    /** Unit of measure as declared on the line (`'yards'`, `'each'`, ...). */
+    uom: string;
+    /**
+     * `true` when the unit cost could not be resolved from upstream
+     * `smrt-products`. The line still contributes `0` to the total; the
+     * flag lets UIs warn the user that the cost rollup is incomplete.
+     */
+    costUnavailable: boolean;
+}
+
+/**
+ * Options accepted by the {@link BomLine} constructor.
+ */
+export declare interface BomLineOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    bomId?: string;
+    componentSkuId?: string;
+    qtyPerUnit?: number;
+    uom?: string;
+    wastePercent?: number;
+    notes?: string;
+}
+
+/**
+ * Thrown when a service operation needs to resolve a BOM by id but the row
+ * does not exist. Carries the requested id so callers can surface a
+ * meaningful message.
+ */
+export declare class BomNotFoundError extends Error {
+    readonly bomId: string;
+    name: string;
+    constructor(bomId: string);
+}
+
+/**
+ * BOM-driven planning service. See module documentation for the role
+ * this plays in the manufacturing pipeline.
+ *
+ * @example
+ * ```typescript
+ * const bomService = await BomService.create({ db });
+ * const rollup = await bomService.computeMaterialCost(bom.id!);
+ * const requirements = await bomService.explodeRequirements(bom.id!, 100);
+ * const check = await bomService.canProduce(bom.id!, 100);
+ * ```
+ */
+export declare class BomService {
+    readonly boms: BillOfMaterialsCollection;
+    readonly lines: BomLineCollection;
+    readonly stockService: StockService;
+    private readonly costResolver;
+    private constructor();
+    /** Factory — prefer {@link createBomService}. */
+    static create(options: BomServiceOptions): Promise<BomService>;
+    /**
+     * Walk every {@link BomLine} for the given BOM, resolve each line's
+     * component cost, apply waste, and return the rolled-up material cost
+     * per produced unit along with a per-line breakdown.
+     *
+     * Throws {@link BomNotFoundError} when the BOM does not exist.
+     *
+     * Lines whose cost cannot be resolved contribute `0` to the total and
+     * set `costUnavailable: true` on their breakdown row; the aggregate
+     * `hasMissingCosts` flag mirrors this so callers can surface a UI
+     * warning.
+     */
+    computeMaterialCost(bomId: string): Promise<BomCostRollup>;
+    /**
+     * Return a "shopping list" of materials needed to produce `qty` units of
+     * the parent product against the given BOM. Lines that reference the
+     * same component SKU are summed so each `componentSkuId` appears once
+     * in the result.
+     *
+     * Does NOT mutate stock — purely a planning helper. Use
+     * {@link ProductionService.consumeMaterials} when you're ready to write
+     * stock movements.
+     *
+     * Throws {@link BomNotFoundError} when the BOM does not exist; throws a
+     * plain `Error` when `qty` is not a positive finite number.
+     */
+    explodeRequirements(bomId: string, qty: number): Promise<MaterialRequirement[]>;
+    /**
+     * Check whether the requirements for producing `qty` units against the
+     * given BOM are currently satisfied by available stock. Returns
+     * `{ ok: true, shortages: [] }` when every component has enough
+     * `available` stock across all locations; `{ ok: false, shortages: [...] }`
+     * with one entry per insufficient component otherwise.
+     *
+     * Available stock is summed across every location (the planning
+     * question is "do we have it at all?"; the operational question of
+     * "where do we pull from?" is left to the caller of
+     * {@link ProductionService.consumeMaterials}).
+     *
+     * Throws {@link BomNotFoundError} when the BOM does not exist.
+     */
+    canProduce(bomId: string, qty: number): Promise<CanProduceResult>;
+    /**
+     * Fetch a BOM by id or throw {@link BomNotFoundError}. Centralises the
+     * "missing BOM" error path so callers don't have to repeat the check.
+     */
+    private requireBom;
+    /**
+     * Run the supplied {@link ComponentCostResolver} for the given component
+     * SKU. Returns `null` when no resolver is registered or when the
+     * resolver returns `null` / `undefined`.
+     */
+    private resolveCost;
+}
+
+/**
+ * Options accepted by {@link BomService.create}.
+ *
+ * Either provide a `db` for the service to construct its own internal
+ * collections + {@link StockService}, or pass a pre-built `stockService`
+ * to share one across subsystems.
+ */
+export declare type BomServiceOptions = {
+    /**
+     * Optional resolver that returns the latest known unit cost for a
+     * component SKU. See {@link ComponentCostResolver}. When omitted, all
+     * costs default to `0` and per-line `costUnavailable` is set.
+     */
+    costResolver?: ComponentCostResolver;
+} & ({
+    db: DatabaseConfig;
+    stockService?: StockService;
+} | {
+    stockService: StockService;
+    db?: DatabaseConfig;
+});
+
+/**
+ * Lifecycle state of a {@link BillOfMaterials}.
+ *
+ * - `draft` — under construction; not yet released for production. Cost
+ *   rollups can still be computed, but the BOM should not yet be referenced
+ *   by a production order.
+ * - `active` — currently in use. New production orders should reference the
+ *   active BOM for a given product.
+ * - `superseded` — an older revision that has been replaced by a newer
+ *   `active` BOM. Historical production orders may still reference the
+ *   superseded row for audit, but no new orders should pick it up.
+ */
+export declare type BomStatus = 'draft' | 'active' | 'superseded';
+
+/**
+ * Result returned by {@link BomService.canProduce}.
+ *
+ * `ok: true` means every material requirement is currently covered by
+ * available stock; `ok: false` means at least one component is short.
+ */
+export declare type CanProduceResult = {
+    ok: true;
+    shortages: [];
+} | {
+    ok: false;
+    shortages: MaterialShortage[];
+};
+
+/**
+ * Callback signature for resolving the unit cost of a component SKU.
+ *
+ * Implementations should return the latest known cost in the BOM's
+ * currency, or `null` (or `undefined`) when no cost is available. The
+ * service treats unresolved costs as `0` and marks the affected line so
+ * callers can warn the user.
+ *
+ * @example
+ * ```typescript
+ * import { MaterialCollection } from '@happyvertical/smrt-products/models';
+ *
+ * const materials = await MaterialCollection.create({ db });
+ *
+ * const bom = await BomService.create({
+ *   db,
+ *   costResolver: async (componentSkuId) => {
+ *     const sku = await skus.get(componentSkuId);
+ *     if (!sku?.productId) return null;
+ *     const material = await materials.get(sku.productId);
+ *     return material?.costPerUnit ?? null;
+ *   },
+ * });
+ * ```
+ */
+export declare type ComponentCostResolver = (componentSkuId: string) => Promise<number | null | undefined> | number | null | undefined;
+
+/**
+ * Per-call options for {@link ProductionService.consumeMaterials}.
+ */
+export declare interface ConsumeMaterialsOptions {
+    /**
+     * Inventory location id (warehouse / factory) where the materials are
+     * pulled from. Required because the production order itself does not
+     * carry a stocking location — see "Location convention" in the module
+     * doc.
+     */
+    locationId: string;
+    /**
+     * Run quantity — how many finished units the BOM is being multiplied
+     * by. Each BOM line's `effectiveQtyPerUnit()` is multiplied by this
+     * number before being deducted from `available` stock.
+     */
+    qty: number;
+    /**
+     * Optional override of the reason code stamped on each
+     * {@link StockMovement}. Defaults to `'production_consume'`.
+     */
+    reasonCode?: StockMovementReason;
+    /**
+     * Optional free-form note attached to every emitted movement.
+     */
+    note?: string;
+}
+
+/**
+ * A single emitted stock movement, returned by
+ * {@link ProductionService.consumeMaterials} so callers can audit / log
+ * the impact of a production run without re-querying.
+ */
+export declare interface ConsumeResult {
+    /** Component SKU id whose stock was deducted. */
+    componentSkuId: string;
+    /** Quantity deducted (already inflated for waste). */
+    qty: number;
+    /** Location the stock was deducted from. */
+    locationId: string;
+}
+
+/**
+ * Convenience factory. Returns a fully-initialized {@link BomService}.
+ */
+export declare function createBomService(options: BomServiceOptions): Promise<BomService>;
+
+/**
+ * Convenience factory. Returns a fully-initialized {@link ProductionService}.
+ */
+export declare function createProductionService(options: ProductionServiceOptions): Promise<ProductionService>;
+
+/**
+ * Result handle returned by {@link installManufacturingDispatchHandlers}.
+ * Call `dispose()` to detach the subscribers (mainly useful in tests and
+ * on graceful shutdown).
+ */
+export declare interface InstalledManufacturingDispatchHandlers {
+    /** Resolved ProductionService — useful for follow-up writes in the same scope. */
+    productionService: ProductionService;
+    /** Detach every installed subscriber. Idempotent. */
+    dispose(): void;
+}
+
+/**
+ * Subscribe production-order handlers to the given DispatchBus.
+ *
+ * @example
+ * ```typescript
+ * import { createDispatchBus } from '@happyvertical/smrt-core';
+ * import { installManufacturingDispatchHandlers } from '@happyvertical/smrt-manufacturing';
+ *
+ * const bus = await createDispatchBus({ db });
+ * const handlers = await installManufacturingDispatchHandlers({
+ *   dispatchBus: bus,
+ *   db,
+ *   producedOnPosted: true, // consume + produce in one shot
+ * });
+ * ```
+ */
+export declare function installManufacturingDispatchHandlers(options: InstallManufacturingDispatchHandlersOptions): Promise<InstalledManufacturingDispatchHandlers>;
+
+/**
+ * Options accepted by {@link installManufacturingDispatchHandlers}.
+ *
+ * Provide either a pre-built {@link ProductionService} (when sharing
+ * across subsystems) or a `db` / `stockService` for the helper to
+ * construct one on first use.
+ */
+export declare type InstallManufacturingDispatchHandlersOptions = {
+    /** Bus to subscribe on. Typically the app-wide DispatchBus. */
+    dispatchBus: DispatchBus;
+    /**
+     * When `true` (default), install the `production_order:posted` handler.
+     */
+    installProductionPosted?: boolean;
+    /**
+     * When `true` (default `false`), install the
+     * `production_order:completed` handler. Off by default because many
+     * workflows want consume+produce to happen on `posted`; opt in to the
+     * split lifecycle when your shop emits a separate completion event.
+     */
+    installProductionCompleted?: boolean;
+    /**
+     * When `true` (default `false`) AND `installProductionCompleted` is
+     * false, the `production_order:posted` handler also calls
+     * {@link ProductionService.produceFinishedGoods} after consume —
+     * handy for "make-to-stock instantly" workflows where the factory
+     * step is invisible.
+     *
+     * Ignored when `installProductionCompleted` is `true` (in that case
+     * production is the completed-handler's job).
+     */
+    producedOnPosted?: boolean;
+} & ({
+    productionService: ProductionService;
+    db?: DatabaseConfig;
+    stockService?: StockService;
+} | {
+    stockService: StockService;
+    db?: DatabaseConfig;
+    productionService?: undefined;
+} | {
+    db: DatabaseConfig;
+    stockService?: undefined;
+    productionService?: undefined;
+});
+
+/**
+ * A single entry on a requirements explosion. Multiple BOM lines pointing
+ * at the same component SKU are summed.
+ */
+export declare interface MaterialRequirement {
+    /** Plain string reference to the required component {@link Sku}. */
+    componentSkuId: string;
+    /** Total quantity needed across the full production run (waste included). */
+    totalQty: number;
+    /** Unit of measure carried over from the originating BOM line(s). */
+    uom: string;
+}
+
+/**
+ * A single shortage discovered by {@link BomService.canProduce}.
+ */
+export declare interface MaterialShortage {
+    /** Plain string reference to the missing component {@link Sku}. */
+    componentSkuId: string;
+    /** Total quantity required for the requested production run. */
+    requested: number;
+    /** Available stock across all locations (`available` state). */
+    available: number;
+}
+
+/**
+ * Thrown when a production-order operation needs a BOM to plan against but
+ * no active BOM is currently registered for the production order's
+ * `productId`. The caller should either link a BOM by passing one in
+ * explicitly or activate one for the given product.
+ */
+export declare class NoActiveBomForProductError extends Error {
+    readonly productId: string;
+    name: string;
+    constructor(productId: string);
+}
+
+/**
+ * Per-call options for {@link ProductionService.produceFinishedGoods}.
+ */
+export declare interface ProduceFinishedGoodsOptions {
+    /**
+     * Inventory location id (warehouse / factory) where the finished goods
+     * land. Required for the same reason as {@link ConsumeMaterialsOptions.locationId}.
+     */
+    locationId: string;
+    /**
+     * Quantity of finished goods produced. Always positive.
+     */
+    qty: number;
+    /**
+     * The SKU id of the finished product to receive into `available`. The
+     * production order references a `productId` (a `Product` from
+     * `@happyvertical/smrt-products`), but a product typically has multiple
+     * SKUs (one per variant). The caller decides which concrete SKU each
+     * line of the run produces.
+     */
+    finishedSkuId: string;
+    /**
+     * Optional override of the reason code stamped on the
+     * {@link StockMovement}. Defaults to `'production_produce'`.
+     */
+    reasonCode?: StockMovementReason;
+    /**
+     * Optional free-form note attached to the emitted movement.
+     */
+    note?: string;
+}
+
+/**
+ * Result of {@link ProductionService.produceFinishedGoods}.
+ */
+export declare interface ProduceResult {
+    /** Finished SKU id whose stock increased. */
+    finishedSkuId: string;
+    /** Quantity received. */
+    qty: number;
+    /** Location the stock was received into. */
+    locationId: string;
+}
+
+/**
+ * Shape of a `production_order:completed` payload this handler expects.
+ *
+ * Typically emitted when the factory signs off the run and finished
+ * goods are physically available to ship. Only used when callers opt in
+ * via `installProductionCompleted`.
+ */
+export declare interface ProductionOrderCompletedPayload {
+    /** Production order row id. Used for `sourceId` on the receipt movement. */
+    productionOrderId: string;
+    /**
+     * SKU id of the finished product to receive into `available`. Required.
+     */
+    finishedSkuId: string;
+    /** Inventory location id where the finished goods land. */
+    locationId: string;
+    /** Quantity received. */
+    qty: number;
+}
+
+/**
+ * Shape of a `production_order:posted` payload this handler expects.
+ *
+ * The producer (typically the application's smrt.ts wiring once a
+ * `ProductionOrder` row transitions to the posted state) packs one
+ * payload per posted order. The handler consumes materials for every
+ * unit declared by `qty`, attributed to `('ProductionOrder', productionOrderId)`
+ * on each emitted {@link StockMovement}.
+ */
+export declare interface ProductionOrderPostedPayload {
+    /** Production order row id. Used for `sourceId` on every movement. */
+    productionOrderId: string;
+    /**
+     * Plain string reference to the upstream product the order is asked to
+     * produce. Used to resolve the active BOM at consume time.
+     */
+    productId: string;
+    /**
+     * Inventory location id (factory / warehouse) where materials are
+     * pulled from.
+     */
+    locationId: string;
+    /**
+     * Run quantity. Each BOM line's effective qty is multiplied by this
+     * before being deducted from `available`.
+     */
+    qty: number;
+    /**
+     * Optional explicit BOM id, e.g. when the order locked itself to a
+     * specific BOM revision when it was created. Falls back to the active
+     * BOM for `productId` if omitted.
+     */
+    bomId?: string;
+    /**
+     * Optional finished SKU id. When provided AND the
+     * `installProductionPosted` handler is wired to also produce in one
+     * shot (which only happens when `installProductionCompleted` is false
+     * and `producedOnPosted` is true), this is the SKU to receive into
+     * `available`.
+     */
+    finishedSkuId?: string;
+}
+
+/**
+ * Minimal shape of a production order this service needs. We deliberately
+ * accept this structural type rather than importing the `ProductionOrder`
+ * class from `@happyvertical/smrt-commerce` — that would either pull a
+ * dep on commerce into manufacturing or force commerce to extend a
+ * manufacturing interface. Plain duck typing keeps the dependency arrow
+ * pointing the way the architecture asks for (manufacturing builds on
+ * inventory; commerce stays orthogonal).
+ */
+export declare interface ProductionOrderRef {
+    /** Production order row id. Used for `sourceId` on every movement. */
+    id?: string | null;
+    /**
+     * Plain string reference to the upstream product the order is asked to
+     * produce. Used to look up the active BOM for the consume step.
+     */
+    productId?: string;
+    /**
+     * Optional explicit BOM id. When set, {@link consumeMaterials} uses this
+     * row even if the product has a different `active` BOM — useful when an
+     * order was kicked off against a specific revision.
+     */
+    bomId?: string;
+}
+
+/**
+ * Operational bridge between a production order and the inventory ledger.
+ */
+export declare class ProductionService {
+    /**
+     * BOM collection bound to the OUTER (non-tx) database. Used for
+     * pre-flight reads in `prepareConsume()` — those run before the
+     * stock-service transaction opens, by design (read-then-tx keeps
+     * the transaction window narrow and rollback only covers actual
+     * mutations). DO NOT add BOM writes that depend on the stock-tx
+     * rolling them back together — this collection is not tx-scoped
+     * and writes here would commit independently. If joint BOM-plus-
+     * stock mutations are ever needed, build tx-scoped BOM collections
+     * inside the `stockService.withTransaction` callback (mirror the
+     * pattern in StockService.withTransaction itself).
+     */
+    readonly boms: BillOfMaterialsCollection;
+    /**
+     * BomLine collection bound to the OUTER database. Same caveat as
+     * {@link boms} — pre-flight reads only.
+     */
+    readonly lines: BomLineCollection;
+    readonly stockService: StockService;
+    private constructor();
+    /** Factory — prefer {@link createProductionService}. */
+    static create(options: ProductionServiceOptions): Promise<ProductionService>;
+    /**
+     * Walk every BOM line for the production order's BOM and deduct
+     * `effectiveQtyPerUnit() * qty` from `available` at `locationId`. Each
+     * deduction goes through {@link StockService.adjust} with `sourceType:
+     * 'ProductionOrder'` and `sourceId: order.id`. Returns the list of
+     * movements emitted so callers can log / surface them.
+     *
+     * **Atomic across lines**: all per-line deductions and their audit
+     * movements run inside a single `stockService.withTransaction(...)`
+     * scope. An `InsufficientStockError` on line N+1 rolls back lines 1..N
+     * so production-order posting never leaves materials half-consumed.
+     * Pre-flight with {@link BomService.canProduce} when you'd rather know
+     * upfront than discover the shortfall mid-run.
+     *
+     * Throws {@link NoActiveBomForProductError} if no BOM id is supplied
+     * on the order *and* no active BOM exists for the order's `productId`.
+     * Throws {@link BomNotFoundError} if `order.bomId` is supplied but
+     * doesn't resolve. Throws plain `Error` on missing `locationId`,
+     * non-positive `qty`, or when both `order.bomId` and `order.productId`
+     * are absent (a programmer error — neither input identifies a BOM).
+     * Re-throws `InsufficientStockError` from `StockService.adjust` if a
+     * line would drive `available` below zero.
+     */
+    consumeMaterials(order: ProductionOrderRef, options: ConsumeMaterialsOptions): Promise<ConsumeResult[]>;
+    /**
+     * Receive `qty` of the finished SKU into `available` at `locationId`.
+     * Goes through {@link StockService.receive} with `sourceType:
+     * 'ProductionOrder'` and `sourceId: order.id`. Returns a single
+     * {@link ProduceResult} describing what landed.
+     *
+     * Throws plain `Error` on missing required arguments or non-positive
+     * `qty`.
+     */
+    produceFinishedGoods(order: ProductionOrderRef, options: ProduceFinishedGoodsOptions): Promise<ProduceResult>;
+    /**
+     * Atomically consume materials AND receive finished goods for one
+     * production run.
+     *
+     * Both calls share a single `stockService.withTransaction(...)` scope:
+     *
+     * - Materials are deducted line-by-line via {@link StockService.adjust}.
+     * - Finished goods are received via {@link StockService.receive}.
+     * - If ANY step throws — a BOM-line shortage, the produce-leg adapter
+     *   failing, a tenancy mismatch surfaced by an interceptor — every
+     *   write in the transaction rolls back. The materials are restored
+     *   and the finished SKU's `available` row is unchanged. Callers
+     *   never observe "materials deducted but finished goods missing".
+     *
+     * Use this when consume + produce should be one indivisible event —
+     * e.g. a make-to-stock workflow posting `production_order:completed`
+     * where the shop floor step is invisible to the ledger.
+     *
+     * The two-call form (call {@link consumeMaterials} then {@link
+     * produceFinishedGoods} separately) is still appropriate when the
+     * factory step is a real wall-clock gap that other observers need to
+     * see — work-in-progress dashboards, partial-run reporting, etc.
+     *
+     * Throws the same errors as the individual methods: missing args
+     * (plain `Error`), unresolvable BOM ({@link BomNotFoundError} /
+     * {@link NoActiveBomForProductError}), or `InsufficientStockError`
+     * if a line would drive `available` below zero.
+     */
+    runProduction(order: ProductionOrderRef, options: {
+        consume: ConsumeMaterialsOptions;
+        produce: ProduceFinishedGoodsOptions;
+    }): Promise<RunProductionResult>;
+    /**
+     * Validate consume args, resolve the BOM + lines, and pre-compute the
+     * mutation attribution. Anything that can throw without a tx open
+     * happens here so the transaction we open later doesn't have to roll
+     * back over a validation miss.
+     */
+    private prepareConsume;
+    /**
+     * Execute the consume leg against a caller-supplied tx-bound
+     * {@link StockService}. Public entry points (`consumeMaterials`,
+     * `runProduction`) open the tx and call through here. Each per-line
+     * `tx.adjust(...)` shares the same transaction so a shortfall on
+     * line N+1 rolls back lines 1..N.
+     */
+    private consumeMaterialsWith;
+    /**
+     * Execute the produce leg against a caller-supplied tx-bound
+     * {@link StockService}. Public entry points (`produceFinishedGoods`,
+     * `runProduction`) open the tx and call through here.
+     */
+    private produceFinishedGoodsWith;
+    /**
+     * Resolve the BOM for a production order. Order of preference:
+     *
+     * 1. Explicit `order.bomId` if supplied — the caller pinned a specific
+     *    revision; we honor that pin or fail. We deliberately do NOT fall
+     *    back to the active BOM when `order.bomId` is stale or mistyped,
+     *    because silently switching recipes would have the production run
+     *    consume materials against a different BOM than the order locked.
+     * 2. The active BOM for `order.productId`.
+     *
+     * Throws {@link BomNotFoundError} when an explicit `order.bomId` is
+     * supplied but doesn't resolve to a row.
+     *
+     * Throws {@link NoActiveBomForProductError} when no `bomId` was supplied
+     * and the product has no active BOM.
+     *
+     * Throws plain `Error` when neither `order.bomId` nor `order.productId`
+     * is supplied — there's nothing to resolve against, so we surface that
+     * as a programmer error with a distinct message rather than overload
+     * `NoActiveBomForProductError` with an empty product id.
+     */
+    private resolveBom;
+}
+
+/**
+ * Options accepted by {@link ProductionService.create}.
+ *
+ * Either pass a `db` for the service to construct its own
+ * collections + {@link StockService}, or share a pre-built `stockService`
+ * across subsystems.
+ */
+export declare type ProductionServiceOptions = {
+    db: DatabaseConfig;
+    stockService?: StockService;
+} | {
+    stockService: StockService;
+    db?: DatabaseConfig;
+};
+
+/**
+ * Result of {@link ProductionService.runProduction} — the consume + produce
+ * pair, run inside one transaction.
+ */
+declare interface RunProductionResult {
+    consumed: ConsumeResult[];
+    produced: ProduceResult;
+}
+
+export { }