@spinekit/purchase 0.1.0

package/dist/receipt/purchase-stock-receipt.mjs

@@ -0,0 +1,225 @@
+import { ConflictError } from "@classytic/arc/utils";
+import { isDuplicateKeyError } from "@classytic/mongokit";
+import { RATE_SCALE } from "@classytic/primitives/unit-cost-rate";
+//#region src/receipt/purchase-stock-receipt.ts
+/**
+* Book a received purchase order into stock — the purchase→WMS leg.
+*
+* Lifted from be-prod (`purchase-order/actions/receive-items-into-stock.ts`). It is the
+* kernel's `StockReceiptBridge` contract implemented over a warehouse, and every host that
+* receives goods needs it; leaving it in one host is how the second host books stock slightly
+* differently and nobody can say which is right.
+*
+* Three things here are load-bearing and easy to lose in a rewrite:
+*
+*  1. **Idempotency is by `purchaseId`** on the receipt move group — purchase 0.2's crash
+*     healing depends on it. A retry after a crash between the PO's receive CAS and this call
+*     must find the group a partial run created instead of double-booking stock.
+*  2. **Convergence is BY STATE, not by existence.** A crash can land between `create` and
+*     `confirm`, or between `confirm` and `receive`. An existing group only proves the chain
+*     STARTED; only `done` is a true no-op. Treating "exists" as "finished" leaves stock
+*     permanently unbooked with a PO that says received.
+*  3. **An unresolvable destination is collected, not thrown.** One bad line must not abort a
+*     20-line receipt. Everything else propagates — see `isUnresolvable` in the types.
+*
+* ## The cost seam
+*
+* PO lines persist integer MINOR units (schemaVersion 2). The warehouse wants a scaled-integer
+* rate, so the conversion is minor → scaled DIRECTLY (`RATE_SCALE`), never through a
+* major-unit float: a major value needs a currency to interpret and the round trip loses
+* precision. Nothing in this file computes a major amount, which is what makes it usable
+* under any currency.
+*/
+/**
+* Integer MINOR units → the warehouse's scaled-integer rate.
+*
+* `RATE_SCALE` is the primitive's constant, not a local literal — a second copy of the scale
+* is a silent 1e6 valuation error the day one of them moves.
+*/
+function minorToScaledRate(costMinor) {
+	return Math.round(costMinor * RATE_SCALE);
+}
+/** The warehouse's scaled rate back to integer MINOR units. */
+function scaledRateToMinor(scaled) {
+	return Math.round(scaled / RATE_SCALE);
+}
+function createPurchaseStockReceipt(deps) {
+	return { 
+	/**
+	* Book every receivable line, returning the lines that could not be resolved.
+	*
+	* Safe to retry: see the idempotency and convergence notes in the module header.
+	*/
+async receive({ purchase, supplierName }) {
+		const warehouse = deps.warehouse();
+		const ctx = deps.buildContext(String(purchase.branch), String(purchase.createdBy ?? ""));
+		const resolver = deps.locations.create(ctx);
+		const errors = [];
+		const resolved = [];
+		for (const item of purchase.items) {
+			const productId = String(item.product);
+			const variantSku = item.variantSku || null;
+			try {
+				const destinationLocationCode = await resolver.resolve(item.destinationLocationId);
+				resolved.push({
+					productId,
+					variantSku,
+					skuRef: deps.skuRef(productId, variantSku),
+					quantity: Number(item.quantity ?? 0),
+					costMinor: Number(item.costPrice ?? 0),
+					destinationLocationCode
+				});
+			} catch (error) {
+				if (deps.locations.isUnresolvable(error)) errors.push({
+					productId,
+					variantSku,
+					error: error.message
+				});
+				else throw error;
+			}
+		}
+		/**
+		* REFUSE BEFORE MUTATING — every location is resolved above, and if ANY line failed to
+		* resolve nothing is booked.
+		*
+		* This guard was missing, and its absence broke the all-or-nothing receive the host
+		* promises. The old sequence was: resolve all lines → collect per-line errors → **book
+		* the ones that resolved** → return the errors. `purchase.engine.ts` turns a non-empty
+		* error list into a thrown `createStatusError`, so the purchase kernel then compensates
+		* the PO's receive state — while the quants, move group and cost layers written for the
+		* VALID lines stay. One bad `destinationLocationId` in a ten-line PO left the PO
+		* un-received and the other nine lines' stock booked, with nothing to reconcile against.
+		*
+		* Ordering is the whole fix: resolution is a pure read, so it is safe to complete for
+		* every line first and decide afterwards. Nothing below this line runs on a partial
+		* resolution — not `ensureBranchReady`, not the move group, not the quant updates, and
+		* not the cost-only snapshots in the second loop.
+		*
+		* If PARTIAL receipt is ever wanted, it needs modelling explicitly — per-line received
+		* quantities and a `partially_received` state. "Mutate what resolved, report the rest,
+		* let the caller throw" is not a partial-receipt design; it is an unreconcilable one.
+		*/
+		if (errors.length > 0) return errors;
+		const receivable = resolved.filter((line) => line.quantity > 0);
+		if (receivable.length > 0) {
+			await deps.ensureBranchReady(ctx.organizationId);
+			/**
+			* The RACE FENCE for this receipt.
+			*
+			* `getByQuery` → `create` below is a check-then-act: two concurrent retries of a
+			* crashed receive both read `null` and BOTH book the stock. Nothing throws and the
+			* PO looks correctly received — the warehouse is simply holding twice what arrived.
+			*
+			* `demandKey` is unique-partial-indexed on flow's move-group model, so the second
+			* create is rejected at the database and its caller replays the winner instead. The
+			* lookup below is still the primary path (it converges a group whose key was already
+			* freed by completing); the key only closes the concurrent window the lookup cannot.
+			*/
+			const demandKey = `receipt:${String(purchase._id)}`;
+			const findExisting = async () => await warehouse.repositories.moveGroup.getByQuery({
+				groupType: "receipt",
+				"metadata.purchaseId": String(purchase._id)
+			}, {
+				organizationId: ctx.organizationId,
+				throwOnNotFound: false,
+				lean: true
+			});
+			/**
+			* CONVERGE BY STATE — header note 2. Drive the group to `done` from wherever it
+			* stopped rather than assuming a pre-existing group finished.
+			*
+			* Extracted so the duplicate-key LOSER runs the identical convergence. Two copies of
+			* this switch is how one of them would eventually learn about a new status and the
+			* other would fall through to its `default` and throw on a healthy group.
+			*/
+			const converge = async (group) => {
+				const groupId = String(group._id);
+				switch (group.status) {
+					case "done": break;
+					case "draft":
+						await warehouse.services.moveGroup.executeAction(groupId, "confirm", {}, ctx);
+						await warehouse.services.moveGroup.executeAction(groupId, "receive", {}, ctx);
+						break;
+					case "confirmed":
+					case "allocated":
+					case "in_progress":
+					case "partially_done":
+						await warehouse.services.moveGroup.executeAction(groupId, "receive", {}, ctx);
+						break;
+					default:
+ /**
+					* A cancelled (or unknown-state) receipt group under a PO being received is a
+					* reconciliation problem no retry can solve. Surface it — re-booking would
+					* double the stock and skipping would leave it permanently unbooked, and both
+					* look like success from the caller's side.
+					*/
+					throw new ConflictError(`Purchase ${String(purchase._id)} has an existing receipt moveGroup ${groupId} in state '${group.status ?? "unknown"}' — manual reconciliation required (cancel-and-recreate or complete it in the WMS before retrying the receive).`);
+				}
+			};
+			const existing = await findExisting();
+			if (existing) await converge(existing);
+			else {
+				const group = await warehouse.services.moveGroup.create({
+					groupType: "receipt",
+					demandKey,
+					metadata: {
+						purchaseId: String(purchase._id),
+						supplierInvoice: purchase.invoiceNumber,
+						purchaseOrderNumber: purchase.purchaseOrderNumber,
+						vendorRef: supplierName || "unknown-vendor",
+						notes: purchase.notes
+					},
+					items: receivable.map((line) => ({
+						moveGroupId: "",
+						operationType: "receipt",
+						skuRef: line.skuRef,
+						sourceLocationId: deps.vendorLocationId,
+						destinationLocationId: line.destinationLocationCode,
+						quantityPlanned: line.quantity,
+						metadata: { unitCostScaled: minorToScaledRate(line.costMinor) }
+					}))
+				}, ctx).catch(async (err) => {
+					if (!isDuplicateKeyError(err)) throw err;
+					const winner = await findExisting();
+					if (!winner) throw err;
+					await converge(winner);
+					return null;
+				});
+				if (group !== null) {
+					await warehouse.services.moveGroup.executeAction(String(group._id), "confirm", {}, ctx);
+					await warehouse.services.moveGroup.executeAction(String(group._id), "receive", {}, ctx);
+				}
+			}
+		}
+		for (const line of resolved) {
+			/**
+			* Zero-quantity line with a price = a COST-ONLY update. `quantityDelta: 0` seeds the
+			* valuation without moving stock, which is how a price correction is applied to a SKU
+			* that has none on hand.
+			*/
+			if (line.quantity === 0 && line.costMinor > 0) {
+				await warehouse.repositories.quant.upsert({
+					organizationId: ctx.organizationId,
+					skuRef: line.skuRef,
+					locationId: line.destinationLocationCode,
+					quantityDelta: 0,
+					unitCostScaled: minorToScaledRate(line.costMinor),
+					inDate: /* @__PURE__ */ new Date()
+				});
+				await deps.costSnapshot.set(line.productId, line.variantSku, line.costMinor);
+				continue;
+			}
+			if (line.quantity > 0 && line.costMinor > 0) {
+				const settledScaled = (await warehouse.services.quant.getAvailability({
+					skuRef: line.skuRef,
+					locationId: line.destinationLocationCode
+				}, ctx)).breakdowns?.[0]?.unitCostScaled;
+				const settledMinor = typeof settledScaled === "number" && settledScaled > 0 ? scaledRateToMinor(settledScaled) : line.costMinor;
+				await deps.costSnapshot.set(line.productId, line.variantSku, settledMinor);
+			}
+		}
+		return errors;
+	} };
+}
+//#endregion
+export { createPurchaseStockReceipt };

package/dist/receipt/purchase-stock-receipt.types.d.mts

@@ -0,0 +1,167 @@
+import { PurchaseOrderDocument } from "@classytic/purchase";
+//#region src/receipt/purchase-stock-receipt.types.d.ts
+/**
+ * The MINIMUM a receipt scope must carry. `organizationId` is the branch, per the
+ * Flow convention.
+ *
+ * Every port below is GENERIC over the host's real context type rather than
+ * taking this one directly, and that is the point: a host whose context is a
+ * `FlowContext` (carrying `actorId`, and whatever else its WMS needs) got this
+ * lossy shape back at every call site, so it cast — `buildContext(...) as never`
+ * on the way in and `ctx as unknown as FlowContext` on the way out.
+ *
+ * `as never` is the expensive half. It does not narrow one field, it erases the
+ * check for ALL of them, so a genuinely wrong context would have compiled just
+ * as happily. Removing it is what revealed the gap in the first place.
+ *
+ * The index signature stays so this remains satisfiable by a plain object; the
+ * generic is what stops a host from LOSING its own type by passing through here.
+ */
+interface PurchaseReceiptContext {
+  organizationId: string;
+  [key: string]: unknown;
+}
+/**
+ * The CONSTRAINT every port is generic over — deliberately NOT
+ * {@link PurchaseReceiptContext}.
+ *
+ * That type carries an index signature so a plain object literal satisfies it.
+ * As a constraint the index signature is fatal: a concrete interface (a host's
+ * `FlowContext`) does not satisfy `[key: string]: unknown`, so
+ * `<TCtx extends PurchaseReceiptContext>` rejects exactly the real-world types
+ * the generic exists to admit. `tsc` says so plainly — "Type 'FlowContext' does
+ * not satisfy the constraint" — which is how this was caught.
+ *
+ * So the constraint states the one thing a receipt scope must have, and nothing
+ * about what else it may carry.
+ */
+interface PurchaseReceiptScope {
+  organizationId: string;
+}
+/**
+ * The Flow surface this bridge drives — structurally typed, so a deployment can satisfy it
+ * with `@classytic/flow` (what be-prod does) or anything shaped like it.
+ */
+/**
+ * What the bridge SENDS to `moveGroup.create` — every field optional ON THE PORT,
+ * deliberately (the `@spinekit/manufacturing/flow-stock` pattern, 2026-08-14): a
+ * provider's own input interface (flow's `CreateMoveGroupServiceInput`) carries no
+ * index signature, so it never assigns to `Record<string, unknown>`, and required
+ * fields here would fail the other bivariant direction. All-optional is the one
+ * shape both sides satisfy CASTLESS — which is the point: the old
+ * `getFlowEngine() as unknown as PurchaseReceiptWarehouse` in the host erased
+ * every field-name drift at this seam, and the same erasure hid a live
+ * field-name bug in the manufacturing adapter (`available` vs
+ * `quantityAvailable`). The bridge is the only caller and always sends the full
+ * shape.
+ */
+interface PurchaseReceiptGroupCreateInput {
+  groupType?: string;
+  demandKey?: string;
+  metadata?: unknown;
+  items?: unknown;
+}
+interface PurchaseReceiptWarehouse<TCtx extends PurchaseReceiptScope = PurchaseReceiptContext> {
+  repositories: {
+    moveGroup: {
+      getByQuery(filter: Record<string, unknown>, options: Record<string, unknown>): Promise<unknown>;
+    };
+    quant: {
+      upsert(input: {
+        organizationId: string;
+        skuRef: string;
+        locationId: string;
+        quantityDelta: number;
+        unitCostScaled: number;
+        inDate: Date;
+      }): Promise<unknown>;
+    };
+  };
+  services: {
+    moveGroup: {
+      /**
+       * Accepts a `demandKey` — the unique-indexed race fence for one group per unit of
+       * demand. An implementation that ignores it will DOUBLE-BOOK a concurrently retried
+       * receipt, so a provider that cannot enforce it is not a valid provider here; the
+       * bridge relies on a duplicate-key rejection, not on the field being decorative.
+       */
+      create(input: PurchaseReceiptGroupCreateInput, ctx: TCtx): Promise<{
+        _id: unknown;
+      }>;
+      executeAction(groupId: string, action: string, payload: unknown, ctx: TCtx): Promise<unknown>;
+    };
+    quant: {
+      getAvailability(query: {
+        skuRef: string;
+        locationId: string;
+      }, ctx: TCtx): Promise<{
+        breakdowns?: Array<{
+          unitCostScaled?: number | undefined;
+        }> | undefined;
+      }>;
+    };
+  };
+}
+/**
+ * Per-receipt destination resolution.
+ *
+ * A FACTORY, not a bare function, because resolution is cached for the duration of one
+ * receipt — a 40-line PO into one location must not issue 40 identical lookups. The host
+ * decides what the cache is.
+ */
+interface PurchaseLocationResolverFactory<TCtx extends PurchaseReceiptScope = PurchaseReceiptContext> {
+  /** Fresh resolver (and cache) for one receipt run. */
+  create(ctx: TCtx): {
+    /** Location CODE for a line's destination, or throw. */
+    resolve(destinationLocationId: unknown): Promise<string>;
+  };
+  /**
+   * Is this error "that location cannot be resolved" rather than a real fault?
+   *
+   * Load-bearing: an unresolvable destination is COLLECTED per line and reported, while
+   * anything else must propagate. Classifying by error TYPE is the host's job because the
+   * host owns the resolver — a message-substring check here would silently start swallowing
+   * genuine faults the day a message changes.
+   */
+  isUnresolvable(error: unknown): boolean;
+}
+/**
+ * Denormalized product cost snapshot, in integer MINOR units.
+ *
+ * Display/reporting only — it never re-enters the warehouse's valuation, which is why a
+ * one-way write is the whole contract.
+ */
+interface PurchaseCostSnapshotPort {
+  set(productId: string, variantSku: string | null, costMinor: number): Promise<void>;
+}
+interface PurchaseStockReceiptDeps<TCtx extends PurchaseReceiptScope = PurchaseReceiptContext> {
+  /** Getter, not a handle — nothing may allocate the engine during composition. */
+  warehouse: () => PurchaseReceiptWarehouse<TCtx>;
+  locations: PurchaseLocationResolverFactory<TCtx>;
+  costSnapshot: PurchaseCostSnapshotPort;
+  /** Branch + actor → WMS scope. The host owns the `organizationId = branchId` mapping. */
+  /** The host's OWN context type flows through unchanged — see `PurchaseReceiptContext`. */
+  buildContext(branchId: string, actorId: string): TCtx;
+  /**
+   * First-receipt-per-branch provisioning (warehouse node + locations). A no-op is a valid
+   * implementation for a deployment that provisions ahead of time.
+   */
+  ensureBranchReady(organizationId: string): Promise<void>;
+  /** The host's `productId` (+ variant) → `skuRef` convention. */
+  skuRef(productId: string, variantSku: string | null): string;
+  /** Counterparty location goods arrive FROM — unbounded by design. */
+  vendorLocationId: string;
+}
+/** One line that could not be booked, with the reason. Reported, never thrown. */
+interface PurchaseReceiptLineError {
+  productId: string;
+  variantSku?: string | null;
+  error: string;
+}
+interface ReceivePurchaseIntoStockInput {
+  purchase: PurchaseOrderDocument;
+  /** Vendor label for the move group's provenance metadata. */
+  supplierName?: string | undefined;
+}
+//#endregion
+export { PurchaseCostSnapshotPort, PurchaseLocationResolverFactory, PurchaseReceiptContext, PurchaseReceiptGroupCreateInput, PurchaseReceiptLineError, PurchaseReceiptScope, PurchaseReceiptWarehouse, PurchaseStockReceiptDeps, ReceivePurchaseIntoStockInput };

package/dist/receipt/purchase-stock-receipt.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/repositories/purchase-order.repository.d.mts

@@ -0,0 +1,40 @@
+import { PurchaseEngine } from "@classytic/purchase/engine";
+import { IPurchaseOrder, IStatusHistory } from "@classytic/purchase";
+import { Repository } from "@classytic/mongokit";
+import { EngineRef } from "@spinekit/kit/engine-slot";
+import { ClientSession } from "mongoose";
+//#region src/repositories/purchase-order.repository.d.ts
+declare class PurchaseOrderRepository extends Repository<IPurchaseOrder> {
+  constructor(engine: EngineRef<PurchaseEngine>);
+  /**
+   * Inject `populate: [supplier]` into HTTP-shaped read paths so list /
+   * detail responses ship a populated supplier object instead of the bare
+   * ObjectId ref.
+   *
+   * Wired ONLY on `getAll` / `getOne` / `getByQuery` — these are the paths
+   * Arc's BaseController takes for `GET /` (→ getAll) and `GET /:id`
+   * (→ getOne with compound filter via AccessControl.fetchDetailed). The
+   * `getById` path is left bare on purpose: internal callers in the
+   * `actions/` folder (approve / receive / pay / cancel / update-draft)
+   * call `getPurchaseOrderRepository().getById(id, { lean: true })` and rely
+   * on `purchase.supplier` being a bare ObjectId for transaction tagging
+   * and partner ref lookup. Auto-populating that path would break those
+   * actions silently — `String(populatedDoc)` returns `'[object Object]'`.
+   *
+   * Mongokit's getAll/findAll picks up `context.populate` (line ~440 + ~554
+   * of mongokit Repository.ts). `context.populateOptions` is NOT in that
+   * chain — only `params.populateOptions` and `options.populateOptions`
+   * are honored, neither of which a `before:*` hook can touch — so the
+   * hook MUST set `context.populate`.
+   */
+  private _setupReadHooks;
+  appendStatus(id: string, statusEntry: IStatusHistory, updates?: Record<string, unknown>, options?: {
+    session?: ClientSession | null;
+  }): Promise<IPurchaseOrder | null>;
+  recordPayment(id: string, transactionId: string, paymentUpdate?: Record<string, unknown>, options?: {
+    session?: ClientSession | null;
+  }): Promise<IPurchaseOrder | null>;
+}
+declare function createPurchaseOrderRepository(engine: EngineRef<PurchaseEngine>): PurchaseOrderRepository;
+//#endregion
+export { PurchaseOrderRepository, createPurchaseOrderRepository };

package/dist/repositories/purchase-order.repository.mjs

@@ -0,0 +1,111 @@
+import { Repository, requireField, validationChainPlugin } from "@classytic/mongokit";
+import { resolveEngineRef } from "@spinekit/kit/engine-slot";
+//#region src/repositories/purchase-order.repository.ts
+/**
+* Populate-aware PO repository, parameterised by the engine.
+*
+* Moved out of be-prod: the only host tie was a `getPurchaseEngine()` singleton import.
+* The supplier-populate policy below is not deployment-specific — any deployment that
+* lists purchase orders needs the supplier display fields, and the `model: 'Supplier'`
+* hint is required by the KERNEL's schema shape, not by one company's data.
+*/
+function getPurchaseModel(engine) {
+	const resolved = resolveEngineRef(engine);
+	if (resolved instanceof Promise) throw new Error("[spine-purchase] repository requires a synchronously-resolvable engine");
+	return resolved.models.PurchaseOrder;
+}
+/**
+* Always-on populate for read paths. Display surfaces (list table, detail
+* sheet, print) all need `supplier.name` + `supplier.code`; without populate
+* the wire payload only carries the bare ObjectId and the FE has to make a
+* second `/suppliers` call to resolve. Project just the two display fields
+* so we don't fan out the whole supplier doc on every PO row.
+*
+* `model: 'Supplier'` is explicit because the package's PurchaseOrder schema
+* stores `supplier` as a bare ObjectId without a `ref:` (the package can't
+* import host-owned models). Mongoose needs the model name to resolve the
+* populate target.
+*/
+const SUPPLIER_DISPLAY_POPULATE = {
+	path: "supplier",
+	model: "Supplier",
+	select: "name code"
+};
+var PurchaseOrderRepository = class extends Repository {
+	constructor(engine) {
+		super(getPurchaseModel(engine), [validationChainPlugin([requireField("invoiceNumber", ["create"]), requireField("branch", ["create"])])], {
+			defaultLimit: 20,
+			maxLimit: 100
+		});
+		this._setupReadHooks();
+	}
+	/**
+	* Inject `populate: [supplier]` into HTTP-shaped read paths so list /
+	* detail responses ship a populated supplier object instead of the bare
+	* ObjectId ref.
+	*
+	* Wired ONLY on `getAll` / `getOne` / `getByQuery` — these are the paths
+	* Arc's BaseController takes for `GET /` (→ getAll) and `GET /:id`
+	* (→ getOne with compound filter via AccessControl.fetchDetailed). The
+	* `getById` path is left bare on purpose: internal callers in the
+	* `actions/` folder (approve / receive / pay / cancel / update-draft)
+	* call `getPurchaseOrderRepository().getById(id, { lean: true })` and rely
+	* on `purchase.supplier` being a bare ObjectId for transaction tagging
+	* and partner ref lookup. Auto-populating that path would break those
+	* actions silently — `String(populatedDoc)` returns `'[object Object]'`.
+	*
+	* Mongokit's getAll/findAll picks up `context.populate` (line ~440 + ~554
+	* of mongokit Repository.ts). `context.populateOptions` is NOT in that
+	* chain — only `params.populateOptions` and `options.populateOptions`
+	* are honored, neither of which a `before:*` hook can touch — so the
+	* hook MUST set `context.populate`.
+	*/
+	_setupReadHooks() {
+		const inject = (payload) => {
+			const ctx = payload;
+			if (ctx.populate) return;
+			ctx.populate = [SUPPLIER_DISPLAY_POPULATE];
+		};
+		this.on("before:getAll", inject);
+		this.on("before:getByQuery", inject);
+		this.on("before:getOne", inject);
+	}
+	async appendStatus(id, statusEntry, updates = {}, options = {}) {
+		const { session = null } = options;
+		return this.Model.findByIdAndUpdate(id, {
+			...updates,
+			$push: { statusHistory: statusEntry }
+		}, {
+			returnDocument: "after",
+			...session ? { session } : {}
+		}).lean();
+	}
+	async recordPayment(id, transactionId, paymentUpdate = {}, options = {}) {
+		const { session = null } = options;
+		return this.Model.findByIdAndUpdate(id, {
+			$push: { transactionIds: transactionId },
+			...paymentUpdate
+		}, {
+			returnDocument: "after",
+			...session ? { session } : {}
+		}).lean();
+	}
+};
+/**
+* Memoized factory, one instance per engine reference.
+*
+* A module-level singleton would bind the FIRST engine it ever saw — fine in a single
+* host, wrong for a package two deployments (or two tests) share in one process.
+*/
+const cache = /* @__PURE__ */ new WeakMap();
+function createPurchaseOrderRepository(engine) {
+	const key = typeof engine === "function" ? engine : engine;
+	let repo = cache.get(key);
+	if (!repo) {
+		repo = new PurchaseOrderRepository(engine);
+		cache.set(key, repo);
+	}
+	return repo;
+}
+//#endregion
+export { PurchaseOrderRepository, createPurchaseOrderRepository };

package/dist/resources/purchase-order/purchase-order.resource.d.mts

@@ -0,0 +1,56 @@
+import { n as PurchasePermissions } from "../../types-T9gsXOf_.mjs";
+import { PurchaseEngine } from "@classytic/purchase/engine";
+import { AnyRecord, ResourceSeams } from "@classytic/arc";
+import { RequestWithExtras } from "@classytic/arc/types";
+//#region src/resources/purchase-order/purchase-order.resource.d.ts
+declare function createPurchaseOrderResource(args: {
+  engine: PurchaseEngine;
+  permissions: PurchasePermissions;
+  prefix?: string;
+  extraActions?: ResourceSeams['actions'];
+  extraRoutes?: ResourceSeams['routes'];
+  /**
+   * Mongoose populate specs injected into HTTP READ paths only (list +
+   * detail) — display joins like `{ path: 'supplier', model: 'Supplier',
+   * select: 'name code' }`. Kernel verbs and internal `getById` callers
+   * stay bare on purpose: domain code relies on refs being bare ObjectIds
+   * (`String(order.supplier)` — a populated doc stringifies to
+   * `'[object Object]'`).
+   */
+  readPopulate?: unknown[];
+}): import("@classytic/arc").ResourceDefinition<AnyRecord> & {
+  readonly actions: {
+    approve: {
+      permissions: import("@spinekit/kit/permissions").PermissionGate;
+      handler: (id: string, _d: unknown, req: RequestWithExtras) => Promise<import("mongoose").Document<unknown, {}, import("@classytic/purchase").IPurchaseOrder, {}, import("mongoose").DefaultSchemaOptions> & import("@classytic/purchase").IPurchaseOrder & {
+        _id: import("mongoose").Types.ObjectId;
+      } & {
+        __v: number;
+      } & {
+        id: string;
+      }>;
+    };
+    receive: {
+      permissions: import("@spinekit/kit/permissions").PermissionGate;
+      handler: (id: string, _d: unknown, req: RequestWithExtras) => Promise<import("mongoose").Document<unknown, {}, import("@classytic/purchase").IPurchaseOrder, {}, import("mongoose").DefaultSchemaOptions> & import("@classytic/purchase").IPurchaseOrder & {
+        _id: import("mongoose").Types.ObjectId;
+      } & {
+        __v: number;
+      } & {
+        id: string;
+      }>;
+    };
+    cancel: {
+      permissions: import("@spinekit/kit/permissions").PermissionGate;
+      handler: (id: string, data: unknown, req: RequestWithExtras) => Promise<import("mongoose").Document<unknown, {}, import("@classytic/purchase").IPurchaseOrder, {}, import("mongoose").DefaultSchemaOptions> & import("@classytic/purchase").IPurchaseOrder & {
+        _id: import("mongoose").Types.ObjectId;
+      } & {
+        __v: number;
+      } & {
+        id: string;
+      }>;
+    };
+  };
+};
+//#endregion
+export { createPurchaseOrderResource };