@happyvertical/smrt-manufacturing 0.53.5 → 0.53.6

package/dist/models/ProductionRun.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ProductionRun — a build of some quantity of a product against one
+ * {@link BillOfMaterials}, reported as it happens: "25 to build, 12 done".
+ *
+ * The run pins the bill it was started against, carries the target and the
+ * completed quantity, and moves through `planned` → `in_progress` → `done`,
+ * or to `cancelled`. Each report of finished units is a dated
+ * {@link ProductionRunCompletion}; `completedQty` is their sum.
+ *
+ * Writes go through `ProductionRunService`, which keeps `completedQty` equal
+ * to the completions under concurrent reporting and enforces the status
+ * transitions. The generated REST/MCP/CLI surfaces are read-only for that
+ * reason.
+ *
+ * This is the shop-floor record of building. It is not the commercial
+ * instruction to make goods (`ProductionOrder` in `@happyvertical/smrt-commerce`,
+ * which carries terms and money); several runs may serve one order, or none
+ * (make to stock). An application that has both links them itself.
+ *
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Where a {@link ProductionRun} is:
+ *
+ * - `planned` — created, nothing reported yet.
+ * - `in_progress` — started, or at least one completion reported.
+ * - `done` — the target was reached, or the run was finished short.
+ * - `cancelled` — stopped; completions already reported stay.
+ */
+export type ProductionRunStatus = 'planned' | 'in_progress' | 'done' | 'cancelled';
+/** Every {@link ProductionRunStatus}, in lifecycle order. */
+export declare const PRODUCTION_RUN_STATUSES: readonly ProductionRunStatus[];
+/**
+ * Options accepted by the {@link ProductionRun} constructor.
+ */
+export interface ProductionRunOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    bomId?: string;
+    targetQty?: number;
+    completedQty?: number;
+    status?: ProductionRunStatus;
+}
+export declare class ProductionRun extends SmrtObject {
+    /** Tenant scope. `null` means the run is a global record. */
+    tenantId: string | null;
+    /**
+     * The bill the run builds against, pinned when the run is created.
+     * Restrict: a bill with runs is history and is not deleted.
+     */
+    bomId: string;
+    /** Units of the bill's product to build. Decimal; greater than zero. */
+    targetQty: number;
+    /** Units reported done so far: the sum of the run's completions. */
+    completedQty: number;
+    /** Lifecycle status; see {@link ProductionRunStatus}. */
+    status: ProductionRunStatus;
+    constructor(options?: ProductionRunOptions);
+    /**
+     * Units still to build, at the six-decimal quantity precision; `0` once
+     * the target is reached.
+     */
+    remainingQty(): number;
+    /** Refuses a status outside the lifecycle and impossible quantities. */
+    protected validateBeforeSave(): Promise<void>;
+}
+//# sourceMappingURL=ProductionRun.d.ts.map

package/dist/models/ProductionRun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProductionRun.d.ts","sourceRoot":"","sources":["../../src/models/ProductionRun.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAGL,UAAU,EACV,KAAK,iBAAiB,EAGvB,MAAM,0BAA0B,CAAC;AAKlC;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,aAAa,GACb,MAAM,GACN,WAAW,CAAC;AAEhB,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,EAAE,SAAS,mBAAmB,EAKjE,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAED,qBASa,aAAc,SAAQ,UAAU;IAC3C,6DAA6D;IAE7D,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B;;;OAGG;IAEH,KAAK,EAAE,MAAM,CAAM;IAEnB,wEAAwE;IAExE,SAAS,EAAE,MAAM,CAAO;IAExB,oEAAoE;IAEpE,YAAY,EAAE,MAAM,CAAO;IAE3B,yDAAyD;IAEzD,MAAM,EAAE,mBAAmB,CAAa;gBAE5B,OAAO,GAAE,oBAAyB;IAU9C;;;OAGG;IACH,YAAY,IAAI,MAAM;IAOtB,wEAAwE;cAC/C,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;CAuB7D"}

package/dist/models/ProductionRunCompletion.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ProductionRunCompletion — one dated report of finished units on a
+ * {@link ProductionRun} ("12 done on Tuesday").
+ *
+ * Written only by `ProductionRunService.recordCompletion`, in the same
+ * transaction that adds `qty` to the run's `completedQty` and, when the
+ * caller asks, posts the stock movements; those movements carry
+ * `sourceType: 'ProductionRunCompletion'` and this row's id. Read-only over
+ * the generated surfaces.
+ *
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+/**
+ * Options accepted by the {@link ProductionRunCompletion} constructor.
+ */
+export interface ProductionRunCompletionOptions extends SmrtObjectOptions {
+    tenantId?: string | null;
+    runId?: string;
+    qty?: number;
+    completedAt?: Date | string;
+}
+export declare class ProductionRunCompletion extends SmrtObject {
+    /** Tenant scope. `null` means a global record. */
+    tenantId: string | null;
+    /** The run the units were built on. Cascade: completions belong to their run. */
+    runId: string;
+    /** Units finished in this report. Decimal; greater than zero. */
+    qty: number;
+    /** When the units were finished (defaults to when the report was made). */
+    completedAt: Date;
+    constructor(options?: ProductionRunCompletionOptions);
+    /** Refuses a report of zero, negative or non-finite units. */
+    protected validateBeforeSave(): Promise<void>;
+}
+//# sourceMappingURL=ProductionRunCompletion.d.ts.map

package/dist/models/ProductionRunCompletion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProductionRunCompletion.d.ts","sourceRoot":"","sources":["../../src/models/ProductionRunCompletion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAGL,UAAU,EACV,KAAK,iBAAiB,EAGvB,MAAM,0BAA0B,CAAC;AAIlC;;GAEG;AACH,MAAM,WAAW,8BAA+B,SAAQ,iBAAiB;IACvE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;CAC7B;AAED,qBAQa,uBAAwB,SAAQ,UAAU;IACrD,kDAAkD;IAElD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/B,iFAAiF;IAEjF,KAAK,EAAE,MAAM,CAAM;IAEnB,iEAAiE;IAEjE,GAAG,EAAE,MAAM,CAAO;IAElB,2EAA2E;IAC3E,WAAW,EAAE,IAAI,CAAc;gBAEnB,OAAO,GAAE,8BAAmC;IAYxD,8DAA8D;cACrC,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7D"}

package/dist/models/index.d.ts

@@ -13,5 +13,7 @@ export { Assembly, type AssemblyOptions } from './Assembly.js';
 export { BillOfMaterials, type BillOfMaterialsOptions, } from './BillOfMaterials.js';
 export { BomLine, type BomLineOptions } from './BomLine.js';
 export { Operation, type OperationOptions } from './Operation.js';
+export { PRODUCTION_RUN_STATUSES, ProductionRun, type ProductionRunOptions, type ProductionRunStatus, } from './ProductionRun.js';
+export { ProductionRunCompletion, type ProductionRunCompletionOptions, } from './ProductionRunCompletion.js';
 export { RoutingStep, type RoutingStepOptions } from './RoutingStep.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/models/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,yBAAyB,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,yBAAyB,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,uBAAuB,EACvB,KAAK,8BAA8B,GACpC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/operation-types.d.ts

@@ -6,6 +6,7 @@
  * @packageDocumentation
  */
 import type { Operation } from './models/Operation.js';
+import type { SubAssemblyLabour } from './types.js';
 /**
  * Callback that returns the hourly labour rate for an operation, in the bill's
  * currency, or `null` / `undefined` when no rate is known. The package holds no
@@ -55,6 +56,14 @@ export interface LabourEstimate {
     steps: RoutingStepEstimate[];
     /** `true` when a step's rate was unavailable, so `totalCost` is a lower bound. */
     hasMissingRates: boolean;
+    /**
+     * Multi-level only (`{ levels }` above 1): every sub-assembly the walk
+     * opened, at any depth, with its own routing estimate and how many units of
+     * it one unit of this bill's product needs. `totalMinutes`, `totalCost`,
+     * `hasRouting` and `hasMissingRates` then cover them too; `steps` stays this
+     * bill's own routing.
+     */
+    subAssemblies?: SubAssemblyLabour[];
 }
 /** One step handed to `RoutingService.replaceRouting`. */
 export interface RoutingStepInput {

package/dist/operation-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operation-types.d.ts","sourceRoot":"","sources":["../src/operation-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,SAAS,EAAE,SAAS,KACjB,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAEpE,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAC;IACpB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,kFAAkF;IAClF,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,kDAAkD;AAClD,qBAAa,sBAAuB,SAAQ,KAAK;aAGnB,WAAW,EAAE,MAAM;IAFtC,IAAI,SAA4B;gBAEb,WAAW,EAAE,MAAM;CAGhD;AAED,sEAAsE;AACtE,qBAAa,2BAA4B,SAAQ,KAAK;aAGxB,IAAI,EAAE,MAAM;IAF/B,IAAI,SAAiC;gBAElB,IAAI,EAAE,MAAM;CAGzC;AAED,iEAAiE;AACjE,qBAAa,qBAAsB,SAAQ,KAAK;aAGlB,WAAW,EAAE,MAAM;IAFtC,IAAI,SAA2B;gBAEZ,WAAW,EAAE,MAAM;CAKhD;AAED,qDAAqD;AACrD,qBAAa,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,SAAgC;CAC9C"}
+{"version":3,"file":"operation-types.d.ts","sourceRoot":"","sources":["../src/operation-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,SAAS,EAAE,SAAS,KACjB,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAEpE,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAC;IACpB,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,kFAAkF;IAClF,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACrC;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,gBAAgB,EAAE,MAAM,CAAC;IACzB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,kDAAkD;AAClD,qBAAa,sBAAuB,SAAQ,KAAK;aAGnB,WAAW,EAAE,MAAM;IAFtC,IAAI,SAA4B;gBAEb,WAAW,EAAE,MAAM;CAGhD;AAED,sEAAsE;AACtE,qBAAa,2BAA4B,SAAQ,KAAK;aAGxB,IAAI,EAAE,MAAM;IAF/B,IAAI,SAAiC;gBAElB,IAAI,EAAE,MAAM;CAGzC;AAED,iEAAiE;AACjE,qBAAa,qBAAsB,SAAQ,KAAK;aAGlB,WAAW,EAAE,MAAM;IAFtC,IAAI,SAA2B;gBAEZ,WAAW,EAAE,MAAM;CAKhD;AAED,qDAAqD;AACrD,qBAAa,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,SAAgC;CAC9C"}

package/dist/production-run-types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Inputs, results and errors for `ProductionRunService`.
+ *
+ * @packageDocumentation
+ */
+import type { ProductionRun } from './models/ProductionRun.js';
+import type { ProductionRunCompletion } from './models/ProductionRunCompletion.js';
+import type { ConsumeResult, ProduceResult } from './services/ProductionService.js';
+/** Input for `ProductionRunService.createRun`. Give `bomId`, or `productId` for its active bill. */
+export interface CreateProductionRunInput {
+    /** The bill to build against. Wins over `productId`. */
+    bomId?: string;
+    /** A product (usually an `Assembly`) whose active bill the run pins. */
+    productId?: string;
+    /** Units to build; greater than zero. */
+    targetQty: number;
+}
+/** Stock to consume when a completion is recorded: the run's bill, for the completed units. */
+export interface CompletionConsumeOptions {
+    /** Location the components are taken from. */
+    locationId: string;
+    /** Optional free-form note on each movement. */
+    note?: string;
+}
+/** Finished goods to receive when a completion is recorded. */
+export interface CompletionProduceOptions {
+    /** Location the finished units are received into. */
+    locationId: string;
+    /** The SKU of the bill's product that was built. */
+    finishedSkuId: string;
+    /** Optional free-form note on the movement. */
+    note?: string;
+}
+/** Input for `ProductionRunService.recordCompletion`. */
+export interface RecordCompletionInput {
+    /** Units finished; greater than zero and no more than the run has left. */
+    qty: number;
+    /** When they were finished. Defaults to now. */
+    completedAt?: Date | string;
+    /**
+     * Consume the run's bill for `qty` units, in the same transaction. Omit
+     * (the default) to record progress without touching stock.
+     */
+    consume?: CompletionConsumeOptions;
+    /**
+     * Receive `qty` finished units, in the same transaction. Omit (the
+     * default) to record progress without touching stock.
+     */
+    produce?: CompletionProduceOptions;
+}
+/** Result of `ProductionRunService.recordCompletion`. */
+export interface RecordCompletionResult {
+    /** The run after the completion. */
+    run: ProductionRun;
+    /** The completion that was recorded. */
+    completion: ProductionRunCompletion;
+    /** Components consumed; empty unless `consume` was given. */
+    consumed: ConsumeResult[];
+    /** Finished goods received; `null` unless `produce` was given. */
+    produced: ProduceResult | null;
+}
+/** Thrown when a production run id does not exist. */
+export declare class ProductionRunNotFoundError extends Error {
+    readonly runId: string;
+    name: string;
+    constructor(runId: string);
+}
+/** Thrown when an action is not allowed in the run's current status. */
+export declare class ProductionRunStateError extends Error {
+    readonly runId: string;
+    /** The run's status when the action was refused. */
+    readonly status: string;
+    /** What was attempted: `start`, `complete`, `finish`, `cancel`, `retarget`. */
+    readonly action: string;
+    name: string;
+    constructor(runId: string, 
+    /** The run's status when the action was refused. */
+    status: string, 
+    /** What was attempted: `start`, `complete`, `finish`, `cancel`, `retarget`. */
+    action: string);
+}
+/** Thrown when a completion would take the run past its target. */
+export declare class ProductionRunOverCompletionError extends Error {
+    readonly runId: string;
+    /** The quantity reported. */
+    readonly qty: number;
+    /** What the run had left to build. */
+    readonly remaining: number;
+    name: string;
+    constructor(runId: string, 
+    /** The quantity reported. */
+    qty: number, 
+    /** What the run had left to build. */
+    remaining: number);
+}
+/** Thrown for invalid production run input (quantities, dates, bill). */
+export declare class InvalidProductionRunInputError extends Error {
+    name: string;
+}
+//# sourceMappingURL=production-run-types.d.ts.map

package/dist/production-run-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-run-types.d.ts","sourceRoot":"","sources":["../src/production-run-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACd,MAAM,iCAAiC,CAAC;AAEzC,oGAAoG;AACpG,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+FAA+F;AAC/F,MAAM,WAAW,wBAAwB;IACvC,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,+DAA+D;AAC/D,MAAM,WAAW,wBAAwB;IACvC,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,WAAW,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC;;;OAGG;IACH,OAAO,CAAC,EAAE,wBAAwB,CAAC;CACpC;AAED,yDAAyD;AACzD,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,GAAG,EAAE,aAAa,CAAC;IACnB,wCAAwC;IACxC,UAAU,EAAE,uBAAuB,CAAC;IACpC,6DAA6D;IAC7D,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;CAChC;AAED,sDAAsD;AACtD,qBAAa,0BAA2B,SAAQ,KAAK;aAGvB,KAAK,EAAE,MAAM;IAFhC,IAAI,SAAgC;gBAEjB,KAAK,EAAE,MAAM;CAG1C;AAED,wEAAwE;AACxE,qBAAa,uBAAwB,SAAQ,KAAK;aAI9B,KAAK,EAAE,MAAM;IAC7B,oDAAoD;aACpC,MAAM,EAAE,MAAM;IAC9B,+EAA+E;aAC/D,MAAM,EAAE,MAAM;IAPvB,IAAI,SAA6B;gBAGxB,KAAK,EAAE,MAAM;IAC7B,oDAAoD;IACpC,MAAM,EAAE,MAAM;IAC9B,+EAA+E;IAC/D,MAAM,EAAE,MAAM;CAIjC;AAED,mEAAmE;AACnE,qBAAa,gCAAiC,SAAQ,KAAK;aAIvC,KAAK,EAAE,MAAM;IAC7B,6BAA6B;aACb,GAAG,EAAE,MAAM;IAC3B,sCAAsC;aACtB,SAAS,EAAE,MAAM;IAP1B,IAAI,SAAsC;gBAGjC,KAAK,EAAE,MAAM;IAC7B,6BAA6B;IACb,GAAG,EAAE,MAAM;IAC3B,sCAAsC;IACtB,SAAS,EAAE,MAAM;CAMpC;AAED,yEAAyE;AACzE,qBAAa,8BAA+B,SAAQ,KAAK;IAC9C,IAAI,SAAoC;CAClD"}

package/dist/quantity.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Quantity precision for planning and production runs.
+ *
+ * Quantities are decimals held in binary floating point, so sums such as
+ * `0.1 + 0.2` and products such as `2.2 * 100` carry rounding noise. Rather
+ * than compare with a tolerance (which must grow with the value and so
+ * eventually hides a whole unit), quantities are kept to
+ * {@link QUANTITY_DECIMALS} decimal places: rounded through their decimal
+ * representation, and summed and compared exactly as whole millionths.
+ *
+ * @packageDocumentation
+ */
+/** Decimal places a quantity is kept to: a millionth of a unit. */
+export declare const QUANTITY_DECIMALS = 6;
+/**
+ * The largest quantity a production run accepts (target or report): every
+ * value up to it with {@link QUANTITY_DECIMALS} places has at most 15
+ * significant digits, so it survives a round trip through a double exactly
+ * and sums of them stay exact.
+ */
+export declare const MAX_QUANTITY = 999999999;
+/**
+ * `value` rounded to {@link QUANTITY_DECIMALS} decimal places (correctly
+ * rounded through its decimal representation, so `0.1 + 0.2` becomes
+ * exactly `0.3`).
+ */
+export declare function roundQuantity(value: number): number;
+/**
+ * `value` as a whole number of millionths, exactly (read from its decimal
+ * representation, not multiplied). Exact for any value up to
+ * {@link MAX_QUANTITY}.
+ */
+export declare function toMillionths(value: number): number;
+/** A whole number of millionths back as a quantity. */
+export declare function fromMillionths(millionths: number): number;
+//# sourceMappingURL=quantity.d.ts.map

package/dist/quantity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quantity.d.ts","sourceRoot":"","sources":["../src/quantity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAInC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,YAAc,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,uDAAuD;AACvD,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/services/AssemblyService.d.ts

@@ -165,10 +165,15 @@ export declare class AssemblyService {
      */
     resolveComponent(skuId: string, options?: ResolveComponentOptions): Promise<ResolvedComponent>;
     /**
-     * The highest-version active bill for a product, limited to one tenant's
-     * bills when `options.tenantId` is given.
+     * The highest-version active bill for a product. With `options.tenantId`,
+     * that tenant's own bill, or else a global one; another tenant's never.
      */
     findActiveBom(productId: string, options?: ResolveComponentOptions): Promise<BillOfMaterials | null>;
+    /**
+     * One row by id: through the collection's `get` without an explicit
+     * tenant, else as a list read of that tenant's and global rows.
+     */
+    private byId;
     /** `true` when the SKU belongs to an {@link Assembly}. */
     isAssembly(skuId: string): Promise<boolean>;
     /**

package/dist/services/AssemblyService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AssemblyService.d.ts","sourceRoot":"","sources":["../../src/services/AssemblyService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AssemblyService.d.ts","sourceRoot":"","sources":["../../src/services/AssemblyService.ts"],"names":[],"mappings":"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"}

package/dist/services/BomService.d.ts

@@ -9,6 +9,14 @@
  * - "What do I need to buy / pull to make N units?" via {@link explodeRequirements}
  * - "Do I have enough on hand?" via {@link canProduce}
  *
+ * Every method reads one level of the bill by default. Pass `{ levels }` to
+ * walk sub-assemblies too: a line whose component SKU belongs to an
+ * `Assembly` with an active bill is opened, to the given depth or (`'all'`)
+ * down to materials and bought items. {@link explode} returns that walk line
+ * by line with the rolled-up totals, and {@link planRequirements} nets it
+ * against stock: how much of each sub-assembly is available, how much is
+ * short, and what building the shortfall takes.
+ *
  * Construct via {@link BomService.create} — the static factory wires up
  * the BOM, BOM-line, and inventory collections so a single `db` (or a
  * pre-built {@link StockService}) drives everything.
@@ -30,7 +38,8 @@ import { OperationCollection } from '../collections/OperationCollection.js';
 import { RoutingStepCollection } from '../collections/RoutingStepCollection.js';
 import type { BomLine } from '../models/BomLine.js';
 import type { LabourEstimate, OperationRateResolver } from '../operation-types.js';
-import { type BomCostRollup, type CanProduceResult, type MaterialRequirement } from '../types.js';
+import { type BomCostRollup, type CanProduceResult, type Explosion, type ExplosionOptions, type MaterialRequirement, type RequirementsPlan } from '../types.js';
+import { AssemblyService } from './AssemblyService.js';
 /**
  * Callback signature for resolving the unit cost of a component SKU.
  *
@@ -104,6 +113,8 @@ export declare class BomService {
     readonly routingSteps: RoutingStepCollection;
     readonly operations: OperationCollection;
     private readonly rateResolver;
+    /** Resolves components for the multi-level walks. */
+    readonly assemblies: AssemblyService;
     private constructor();
     /** Factory — prefer {@link createBomService}. */
     static create(options: BomServiceOptions): Promise<BomService>;
@@ -118,8 +129,16 @@ export declare class BomService {
      * set `costUnavailable: true` on their breakdown row; the aggregate
      * `hasMissingCosts` flag mirrors this so callers can surface a UI
      * warning.
+     *
+     * With `{ levels }` above 1, a sub-assembly line whose bill the walk opens
+     * is costed from that bill instead of the resolver: its `unitCost` is the
+     * bill's rolled-up material cost per unit, its `components` hold that
+     * bill's lines, and a missing cost anywhere below marks it and
+     * `hasMissingCosts` (its known part still counts, so the total is a lower
+     * bound). Other lines, including sub-assemblies with no active bill, use
+     * the resolver as before.
      */
-    computeMaterialCost(bomId: string): Promise<BomCostRollup>;
+    computeMaterialCost(bomId: string, options?: ExplosionOptions): Promise<BomCostRollup>;
     /**
      * Roll up the estimated labour to build one unit from the bill's routing:
      * total minutes, plus cost when a `rateResolver` was supplied (hourly rate
@@ -127,9 +146,15 @@ export declare class BomService {
      * estimate with zero totals, so callers can add it to the material cost
      * unconditionally. Retired operations still count: the routing names them.
      *
+     * With `{ levels }` above 1, every sub-assembly the walk opens adds its own
+     * bill's routing, multiplied by the units of it one unit needs (waste
+     * included); see {@link LabourEstimate.subAssemblies}.
+     *
      * Throws {@link BomNotFoundError} when the BOM does not exist.
      */
-    computeLabourEstimate(bomId: string): Promise<LabourEstimate>;
+    computeLabourEstimate(bomId: string, options?: ExplosionOptions): Promise<LabourEstimate>;
+    /** One bill's own routing estimate, per unit of its product. */
+    private labourFor;
     /**
      * Return a "shopping list" of materials needed to produce `qty` units of
      * the parent product against the given BOM. Lines that reference the
@@ -140,10 +165,14 @@ export declare class BomService {
      * {@link ProductionService.consumeMaterials} when you're ready to write
      * stock movements.
      *
+     * With `{ levels }` above 1, sub-assemblies with an active bill are
+     * replaced by what their bills need, waste compounding down the levels;
+     * this is {@link explode}'s `totals`.
+     *
      * 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[]>;
+    explodeRequirements(bomId: string, qty: number, options?: ExplosionOptions): Promise<MaterialRequirement[]>;
     /**
      * Check whether the requirements for producing `qty` units against the
      * given BOM are currently satisfied by available stock. Returns
@@ -156,14 +185,64 @@ export declare class BomService {
      * "where do we pull from?" is left to the caller of
      * {@link ProductionService.consumeMaterials}).
      *
+     * With `{ levels }` above 1 the check is {@link planRequirements}: a
+     * sub-assembly that is short and has an active bill is opened for its
+     * shortfall, and each shortage is reported on the line where it occurs,
+     * with its `level` and `path`. Stock is allocated as the walk goes, so a
+     * component used in two places is not counted twice.
+     *
      * Throws {@link BomNotFoundError} when the BOM does not exist.
      */
-    canProduce(bomId: string, qty: number): Promise<CanProduceResult>;
+    canProduce(bomId: string, qty: number, options?: ExplosionOptions): Promise<CanProduceResult>;
+    /**
+     * Walk the bill for `qty` units and return every line, depth first, with
+     * its level, the path of bills above it and its quantity for the run, plus
+     * the rolled-up `totals`. Gross requirements: stock is not read.
+     *
+     * `levels` (default `1`) says how far to open sub-assemblies; see
+     * {@link ExplosionLevels}. Waste compounds: a sub-assembly line's quantity
+     * includes its own waste, and its bill's lines are multiplied by it.
+     *
+     * Throws {@link BomNotFoundError}, `BomStructureCycleError` when stored
+     * data already has a product containing itself, `BomExplosionLimitError`
+     * past the depth or line limits, and a plain `Error` for a bad `qty` or
+     * `levels`.
+     */
+    explode(bomId: string, qty: number, options?: ExplosionOptions): Promise<Explosion>;
+    /**
+     * Net the walk against stock: for each line, the available stock (all
+     * locations) not yet allocated to an earlier line and how much is short.
+     * A sub-assembly that is short and has an active bill is opened for the
+     * shortfall only, so its lines say what building that shortfall takes;
+     * one covered by stock is not opened. Lines that are short and cannot be
+     * opened are the `shortages`, each at its own level.
+     *
+     * These are facts, not a decision: the application decides whether a
+     * short sub-assembly is built or bought. Does not mutate stock.
+     *
+     * Throws as {@link explode} does.
+     */
+    planRequirements(bomId: string, qty: number, options?: ExplosionOptions): Promise<RequirementsPlan>;
     /**
      * Fetch a BOM by id or throw {@link BomNotFoundError}. Centralises the
      * "missing BOM" error path so callers don't have to repeat the check.
      */
+    /**
+     * A bill's lines: its own tenant's and global ones, whatever tenant
+     * context is active (a context alone would hide a global bill's lines).
+     */
+    private linesOf;
     private requireBom;
+    /**
+     * Available stock of a SKU across locations, counting only the top bill's
+     * tenant's rows and global ones, whatever tenant context is active (the
+     * walk reads its structure the same way).
+     */
+    private availableInTenant;
+    /** {@link computeMaterialCost} with `levels` above 1. */
+    private computeMultiLevelCost;
+    /** {@link computeLabourEstimate} with `levels` above 1. */
+    private computeMultiLevelLabour;
     /** Run the {@link OperationRateResolver}; `null` when there is no rate. */
     private resolveRate;
     /**

package/dist/services/BomService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BomService.d.ts","sourceRoot":"","sources":["../../src/services/BomService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAmB,MAAM,0BAA0B,CAAC;AAChF,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,6CAA6C,CAAC;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAEhF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EAEtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,aAAa,EAGlB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EAEzB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,cAAc,EAAE,MAAM,KACnB,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC;;;;OAIG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;CACtC,GAAG,CACA;IAAE,EAAE,EAAE,cAAc,CAAC;IAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,GACnD;IAAE,YAAY,EAAE,YAAY,CAAC;IAAC,EAAE,CAAC,EAAE,cAAc,CAAA;CAAE,CACtD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU;aAEH,IAAI,EAAE,yBAAyB;aAC/B,KAAK,EAAE,iBAAiB;aACxB,YAAY,EAAE,YAAY;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY;aACb,YAAY,EAAE,qBAAqB;aACnC,UAAU,EAAE,mBAAmB;IAC/C,OAAO,CAAC,QAAQ,CAAC,YAAY;IAP/B,OAAO;IAYP,iDAAiD;WACpC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC;IA6BpE;;;;;;;;;;;OAWG;IACG,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAwChE;;;;;;;;OAQG;IACG,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAyCnE;;;;;;;;;;;;OAYG;IACG,mBAAmB,CACvB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,mBAAmB,EAAE,CAAC;IA0BjC;;;;;;;;;;;;;OAaG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuCvE;;;OAGG;YACW,UAAU;IAOxB,2EAA2E;YAC7D,WAAW;IAUzB;;;;OAIG;YACW,WAAW;CAO1B;AA8BD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,UAAU,CAAC,CAErB;AAID,YAAY,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"BomService.d.ts","sourceRoot":"","sources":["../../src/services/BomService.ts"],"names":[],"mappings":"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"}

package/dist/services/ProductionRunService.d.ts

@@ -0,0 +1,123 @@
+/**
+ * ProductionRunService — create production runs and report work on them as
+ * it happens: "25 to build, 12 done".
+ *
+ * Every write runs in one database transaction that first saves the run
+ * row. That save is revision-guarded, so it takes the row's lock and a
+ * concurrent writer's save fails with a revision conflict; the loser's whole
+ * transaction is retried against the committed run. Two people reporting
+ * completions at once therefore both count, and a run never goes past its
+ * target.
+ *
+ * Recording a completion moves no stock unless the caller asks. With
+ * `consume` and/or `produce`, it uses the {@link ProductionService} paths
+ * inside the same transaction as the completion, so a stock shortfall rolls
+ * the completion back too.
+ *
+ * @packageDocumentation
+ */
+import { type DatabaseConfig } from '@happyvertical/smrt-core';
+import { type StockService } from '@happyvertical/smrt-inventory';
+import { BillOfMaterialsCollection } from '../collections/BillOfMaterialsCollection.js';
+import { ProductionRunCollection } from '../collections/ProductionRunCollection.js';
+import { ProductionRunCompletionCollection } from '../collections/ProductionRunCompletionCollection.js';
+import type { ProductionRun } from '../models/ProductionRun.js';
+import type { ProductionRunCompletion } from '../models/ProductionRunCompletion.js';
+import { type CreateProductionRunInput, type RecordCompletionInput, type RecordCompletionResult } from '../production-run-types.js';
+/**
+ * Options accepted by {@link ProductionRunService.create}. With a
+ * `stockService`, its database is used for everything, so a completion and
+ * its stock movements share one transaction.
+ */
+export type ProductionRunServiceOptions = {
+    db: DatabaseConfig;
+    stockService?: undefined;
+} | {
+    stockService: StockService;
+    db?: undefined;
+};
+/**
+ * Creates runs and records their progress. Construct with
+ * {@link ProductionRunService.create} or {@link createProductionRunService}.
+ *
+ * @example
+ * ```typescript
+ * const runs = await ProductionRunService.create({ db });
+ * const run = await runs.createRun({ productId: frame.id, targetQty: 25 });
+ * await runs.recordCompletion(run.id!, { qty: 12 });
+ * // run: 25 to build, 12 done, in_progress
+ * ```
+ */
+export declare class ProductionRunService {
+    /** The stock service whose database every collection here shares. */
+    readonly stockService: StockService;
+    /** Production runs (reads; writes go through this service). */
+    readonly runs: ProductionRunCollection;
+    /** Completions (reads; writes go through this service). */
+    readonly completions: ProductionRunCompletionCollection;
+    /** Bills, to pin a run's bill. */
+    readonly boms: BillOfMaterialsCollection;
+    private constructor();
+    /** Factory — prefer {@link createProductionRunService}. */
+    static create(options: ProductionRunServiceOptions): Promise<ProductionRunService>;
+    /**
+     * Create a `planned` run of `targetQty` units, pinned to `bomId`, or to the
+     * active bill of `productId`.
+     *
+     * @throws {InvalidProductionRunInputError} for a target that is not a
+     *   positive number, or when neither `bomId` nor `productId` is given.
+     * @throws {BomNotFoundError} when `bomId` does not exist.
+     * @throws {NoActiveBomForProductError} when `productId` has no active bill.
+     */
+    createRun(input: CreateProductionRunInput): Promise<ProductionRun>;
+    /** The run, or `null` when no run has this id. */
+    get(runId: string): Promise<ProductionRun | null>;
+    /** A run's completions in the order they happened. */
+    listCompletions(runId: string): Promise<ProductionRunCompletion[]>;
+    /** Mark a `planned` run `in_progress`. */
+    start(runId: string): Promise<ProductionRun>;
+    /** Mark an open run `done`, short of its target if work stopped early. */
+    finish(runId: string): Promise<ProductionRun>;
+    /** Cancel an open run. Completions already reported stay. */
+    cancel(runId: string): Promise<ProductionRun>;
+    /**
+     * Change an open run's target. It may not go below what is already done;
+     * setting it to exactly that finishes the run.
+     *
+     * @throws {InvalidProductionRunInputError} for a target that is not a
+     *   positive number or is below the completed quantity.
+     */
+    setTarget(runId: string, targetQty: number): Promise<ProductionRun>;
+    /**
+     * Report `qty` finished units on an open run: records a dated completion,
+     * adds it to `completedQty`, moves a `planned` run to `in_progress`, and
+     * marks the run `done` when the target is reached. With `consume` and/or
+     * `produce`, also writes the stock movements through
+     * {@link ProductionService}, stamped `sourceType: 'ProductionRunCompletion'`
+     * with the completion id. Everything runs in one transaction.
+     *
+     * Consumption takes the run's bill's own lines for `qty` units: a
+     * sub-assembly on the bill is taken from stock as a component. Building
+     * that sub-assembly is its own run.
+     *
+     * @throws {ProductionRunNotFoundError}
+     * @throws {ProductionRunStateError} when the run is `done` or `cancelled`.
+     * @throws {ProductionRunOverCompletionError} when `qty` is more than the
+     *   run has left.
+     * @throws {InvalidProductionRunInputError} for a bad `qty` or date.
+     * @throws `InsufficientStockError` from inventory when consuming would
+     *   drive stock below zero; nothing is recorded then.
+     */
+    recordCompletion(runId: string, input: RecordCompletionInput): Promise<RecordCompletionResult>;
+    /** Apply `apply` to an open run and save it, in one transaction. */
+    private change;
+    private load;
+    /**
+     * Run `work` in one transaction on collections bound to it, rerunning the
+     * whole transaction when it lost a revision race on the run row.
+     */
+    private inTransaction;
+}
+/** Convenience factory for {@link ProductionRunService}. */
+export declare function createProductionRunService(options: ProductionRunServiceOptions): Promise<ProductionRunService>;
+//# sourceMappingURL=ProductionRunService.d.ts.map

package/dist/services/ProductionRunService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProductionRunService.d.ts","sourceRoot":"","sources":["../../src/services/ProductionRunService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,KAAK,cAAc,EAAmB,MAAM,0BAA0B,CAAC;AAChF,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,6CAA6C,CAAC;AACxF,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AACpF,OAAO,EAAE,iCAAiC,EAAE,MAAM,qDAAqD,CAAC;AAExG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AACpF,OAAO,EACL,KAAK,wBAAwB,EAK7B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC;AAepC;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GACnC;IAAE,EAAE,EAAE,cAAc,CAAC;IAAC,YAAY,CAAC,EAAE,SAAS,CAAA;CAAE,GAChD;IAAE,YAAY,EAAE,YAAY,CAAC;IAAC,EAAE,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAmBnD;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAoB;IAE7B,qEAAqE;aACrD,YAAY,EAAE,YAAY;IAC1C,+DAA+D;aAC/C,IAAI,EAAE,uBAAuB;IAC7C,2DAA2D;aAC3C,WAAW,EAAE,iCAAiC;IAC9D,kCAAkC;aAClB,IAAI,EAAE,yBAAyB;IARjD,OAAO;IAWP,2DAA2D;WAC9C,MAAM,CACjB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC;IA8BhC;;;;;;;;OAQG;IACG,SAAS,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC;IA+CxE,kDAAkD;IAC5C,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAKvD,sDAAsD;IAChD,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAKxE,0CAA0C;IACpC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAQlD,0EAA0E;IACpE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAMnD,6DAA6D;IACvD,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAMnD;;;;;;OAMG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAezE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,gBAAgB,CACpB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,sBAAsB,CAAC;IAgFlC,oEAAoE;IACpE,OAAO,CAAC,MAAM;YAeA,IAAI;IAWlB;;;OAGG;IACH,OAAO,CAAC,aAAa;CActB;AAsCD,4DAA4D;AAC5D,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAE/B"}