@spinekit/purchase 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.1.0 - 2026-08-21
+
+### Changed
+- **License:** relicensed from MIT to the **Classytic Source-Available License**
+  (Community & Commercial). Evaluation and development use remain free; production
+  use now requires a commercial license from Classytic LLC. See `LICENSE`.
+
+### Notes
+- First stable **1.0.0** release of the Classytic `arc` suite. Versions published
+  before 1.0.0 remain under their original MIT terms; the new license applies from
+  1.0.0 onward.
+
+## 0.2.1 — 2026-07-21
+
+- **Engine teardown symmetry**: a module-created engine now registers
+  `onClose` → `engine.destroy()` (closes the kernel's event transport);
+  a BYO engine is never closed by the module.
+- **Cast reduction (3 → 0 `as unknown as`)**: verbs flow through the
+  kernel-exported `PurchaseOrderRepository` type (`CreateOrderInput` /
+  `UpdateOrderInput` / `PurchaseContext` narrow the call sites); the
+  `readPopulate` hook wiring uses repo-core's public `RepositoryBase.on`;
+  the AnyRecord/entity invariance widens ONCE through the documented
+  `entity-model.ts` boundary helpers.
+
+## 0.2.0 — 2026-07-17
+
+- **BREAKING: `PurchaseModuleDeps.baseCurrency` is now REQUIRED** — threaded to
+  `createPurchaseEngine`, which since purchase 0.5 fail-louds without a valid
+  ISO 4217 code (a money kernel has no jurisdiction default; same rule as
+  arc-invoice/arc-assets). New optional `allowForeignCurrency?: boolean`
+  (default `false`) permits POs/bills in a non-base currency.
+- Peer `@classytic/purchase` floor raised `>=0.3.0` → `>=0.5.0` (0.5's required
+  baseCurrency, policy bridge, batch catalog resolution, and `unitCostMinor`
+  make older kernels incompatible with this module's composition).
+- **BREAKING: kernel-bypass seams REMOVED** — `controller` / `repository` /
+  `customSchemas` / `deleteGate` are gone. The module owns HTTP: CREATE and
+  PATCH route through the kernel verbs (`createOrder`, `updateDraft` — FSM
+  guard, re-enrichment, paid-floor invariant, currency/FX pairing), the
+  kernel's own Zod schemas (`CreateOrderSchema`/`UpdateOrderSchema`) are the
+  wire contract, and DELETE is a hard 405 (`purchase.delete_forbidden` —
+  immutable audit trail; `action: cancel` is the verb). Hosts extend via
+  `extraActions`/`extraRoutes` (which ADD, never bypass) and the new
+  `readPopulate` (display joins on HTTP read paths only — list via
+  before-read hooks, detail via the controller; kernel verbs and internal
+  `getById` stay bare so domain code can rely on bare ObjectId refs).
+
+## 0.1.1 — 2026-07-11
+
+- **`PurchaseModuleDeps.tenant?`** — optional `boolean` (default `false`). Pass
+  `true` to enable per-branch scoping on purchase orders; previously the module was
+  hardcoded to single-tenant. One knob flows to the kernel's multi-tenant plugin.
+- devDep `@classytic/primitives` bumped to `^0.11.0`.
+
+## 0.1.0
+
+Initial release — supplier purchase orders (draft→approve→receive with CAS +
+compensation + `pendingStockReceipt` crash heal) composed into arc. Catalog/
+stockReceipt/sequence kernel ports injected; accounting posting + approval stay
+host seams.

package/LICENSE

@@ -0,0 +1,75 @@
+Classytic Source-Available License (Community & Commercial), Version 1.0
+
+Copyright (c) 2026 Classytic LLC. All rights reserved.
+
+This software is source-available, not open source. Please read this License
+before using it.
+
+1. DEFINITIONS
+   "Software" means the contents of this package and any accompanying source
+   code, object code, or documentation, in any form.
+   "Licensor" means Classytic LLC, a limited liability company organized in the
+   United States.
+   "You" means the individual or legal entity exercising rights under this
+   License.
+   "Evaluation Use" means use for evaluation, development, testing,
+   experimentation, or internal non-commercial purposes only.
+   "Production Use" means any use of the Software that is live, commercial,
+   revenue-generating, or customer-facing, or any use other than Evaluation Use.
+   "Commercial License" means a separate written agreement executed with
+   Licensor that grants Production Use rights.
+
+2. OWNERSHIP
+   The Software is licensed, not sold. Licensor retains all right, title, and
+   interest in and to the Software, including all intellectual property rights.
+   All rights not expressly granted in this License are reserved by Licensor.
+
+3. EVALUATION GRANT
+   Subject to Your compliance with this License, Licensor grants You a
+   worldwide, royalty-free, non-exclusive, non-transferable, revocable license
+   to download, install, run, and modify the Software solely for Evaluation Use.
+
+4. PRODUCTION USE REQUIRES A COMMERCIAL LICENSE
+   Production Use of the Software is NOT permitted under this License and
+   requires a Commercial License from Licensor. A Commercial License may be
+   granted at Licensor's discretion, with or without a fee, and may confer
+   perpetual, irrevocable, and transferable Production Use rights as set out in
+   that agreement. Contact licensing@classytic.com to obtain one.
+
+5. RESTRICTIONS
+   You may not:
+   (a) make any Production Use of the Software without a Commercial License;
+   (b) redistribute, resell, rent, sublicense, or otherwise make the Software
+       (in whole or in part, original or modified) available to third parties as
+       a stand-alone product, framework, library, or hosted/managed service that
+       competes with the Software or with Licensor;
+   (c) remove, obscure, or alter any copyright, license, or attribution notice.
+
+6. FEEDBACK AND CONTRIBUTIONS
+   Any feedback, suggestions, or contributions You provide relating to the
+   Software may be used by Licensor for any purpose without obligation to You.
+
+7. TERMINATION
+   This License and the Evaluation Grant terminate automatically if You breach
+   any term. Upon termination You must cease all use of the Software and destroy
+   all copies in Your possession. Rights under a Commercial License are governed
+   by that agreement's own terms and survive termination of this License to the
+   extent stated there.
+
+8. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+9. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL LICENSOR BE LIABLE
+   FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+   TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+   OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+10. GOVERNING LAW
+   This License is governed by the laws of the State of Delaware, United States,
+   without regard to its conflict-of-laws principles. (Adjust to Your LLC's state
+   of formation.)
+
+For commercial licensing, contact: licensing@classytic.com

package/README.md

@@ -0,0 +1,40 @@
+# @spinekit/purchase
+
+> Purchasing / procurement — purchase orders with approval and receiving.
+
+Part of **Spine**, Classytic's ERP — the arc-module layer that composes the
+framework-agnostic `@classytic/purchase` kernel into an [`@classytic/arc`](https://www.npmjs.com/package/@classytic/arc)
+application via `createApp({ modules })`.
+
+## Install
+
+```sh
+npm install @spinekit/purchase @classytic/purchase @classytic/arc @classytic/mongokit mongoose zod
+```
+
+Kernels and the framework are **peer dependencies** — the host installs a single
+copy; this module bundles nothing.
+
+## Usage
+
+```ts
+import { createApp } from '@classytic/arc/factory';
+import { createPurchaseModule } from '@spinekit/purchase';
+
+const app = await createApp({
+  modules: [
+    createPurchaseModule({
+      connection,          // your mongoose connection
+      permissions,         // { view, manage, ... } role gates
+      // BYO engine + host seams (extraActions, extraRoutes, bridges) as needed
+    }),
+  ],
+});
+```
+
+The module's `bootstrap` return is recorded at `fastify.arc.modules['purchase']`
+for container-free cross-module wiring.
+
+## License
+
+MIT © Classytic

package/dist/bridges.d.mts

@@ -0,0 +1,167 @@
+//#region src/bridges/ports.d.ts
+/**
+ * What a host must supply for the purchase bridges — engines and lookups only.
+ *
+ * Every port here is a HANDLE or a DATA lookup. None is a rule: numbering,
+ * enrichment, totals, payment status and the domain event belong to
+ * `@classytic/purchase`; item resolution and terms derivation belong to the
+ * bridges. A host that finds itself passing a policy through one of these
+ * should be changing the bridge, not the port.
+ */
+/**
+ * What a resolved line hands back to the kernel.
+ *
+ * Mirrors `@classytic/purchase`'s `ResolvedPurchaseItem` structurally rather
+ * than importing it — the bridge package stays usable without the kernel as a
+ * hard type dependency, and the kernel's repository re-validates the currency
+ * regardless. `costPrice` is integer MINOR units.
+ */
+interface ResolvedPurchaseLine {
+  productName: string;
+  variantSku?: string | null;
+  costPrice: number;
+  currency?: string | undefined;
+  leadTimeDays?: number | undefined;
+}
+/** Catalog reads for product identity + variant validation. */
+interface PurchaseCatalogEngineLike {
+  repositories: {
+    product: {
+      findAll(filter: Record<string, unknown>, options: Record<string, unknown>): Promise<unknown[]>;
+    };
+  };
+}
+/** A supplier-price quote from the buy-side pricelist. */
+interface SupplierQuote {
+  price: number;
+  currency?: string | undefined;
+  leadTimeDays?: number | undefined;
+  ruleMatched?: boolean | undefined;
+}
+/**
+ * Buy-side pricelist. OPTIONAL by design: a deployment with no supplier
+ * pricelists resolves costs manually, and that is a valid configuration —
+ * pricing here is an assist, never a gate.
+ */
+interface PurchasePricelistEngineLike {
+  repositories: {
+    priceList: {
+      resolvePartnerPrice(input: {
+        partnerRef: string;
+        kind: string;
+        productId: string;
+        variantSku?: string;
+        quantity: number;
+        basePrice: number;
+      }, scope?: {
+        organizationId: string;
+      } | undefined): Promise<SupplierQuote | null>;
+    };
+  };
+}
+interface SupplierLike {
+  paymentTerms?: string | undefined;
+  creditDays?: number | undefined;
+}
+/** The supplier master — identity check + terms defaults. */
+interface SupplierPort {
+  getById(supplierId: string): Promise<SupplierLike | null>;
+}
+/**
+ * Branch resolution for RECEIVING.
+ *
+ * Which branch may receive a purchase is deployment policy (be-prod centralises
+ * on head office; another vertical may receive per-site), so the decision is a
+ * port rather than a constant here.
+ */
+interface BranchPort {
+  resolveReceivingBranch(inputBranchId: string | undefined): Promise<string>;
+}
+interface PurchaseLogger {
+  warn?(obj: Record<string, unknown>, msg: string): void;
+}
+interface PurchaseIntegrationDeps {
+  /** BYO catalog engine — awaited per call so a late boot resolves. */
+  catalog: () => Promise<PurchaseCatalogEngineLike> | PurchaseCatalogEngineLike;
+  /** Buy-side pricelist, or a getter returning null when none is configured. */
+  pricelist?: (() => PurchasePricelistEngineLike | null) | undefined;
+  suppliers: SupplierPort;
+  branches: BranchPort;
+  /** Order currency fallback when an input carries none. */
+  baseCurrency: string;
+  /** Default when neither the caller nor the supplier states terms. */
+  defaultPaymentTerms: string;
+  /** `invoiceDate + creditDays` for credit terms; deployment calendar. */
+  resolveDueDate(input: {
+    paymentTerms: string;
+    creditDays: number;
+    dueDate: Date | null;
+    invoiceDate: Date | undefined;
+  }): Date | null;
+  /** Raised when a supplier id does not resolve. */
+  supplierNotFound(supplierId: string): Error;
+  logger?: PurchaseLogger | undefined;
+}
+//#endregion
+//#region src/bridges/catalog.bridge.d.ts
+interface PurchaseItemInputLike {
+  product: unknown;
+  variantSku?: string | null | undefined;
+  quantity?: unknown;
+  costPrice?: number | undefined;
+}
+interface ResolveItemsContextLike {
+  currency?: string | undefined;
+  supplierId?: string | undefined;
+  branchId?: string | undefined;
+}
+interface CatalogBridgeDeps extends Pick<PurchaseIntegrationDeps, 'catalog' | 'pricelist' | 'baseCurrency' | 'logger'> {
+  /** Thrown for an unresolvable product, variant, or a negative quantity/cost. */
+  invalidItem(message: string, status?: number): Error;
+}
+declare function createPurchaseCatalogBridge(deps: CatalogBridgeDeps): {
+  resolveItems: (items: ReadonlyArray<PurchaseItemInputLike>, context: ResolveItemsContextLike) => Promise<Array<ResolvedPurchaseLine | null>>;
+};
+//#endregion
+//#region src/bridges/policy.bridge.d.ts
+/**
+ * Generic in the terms union, so the KERNEL's union flows through unchanged.
+ *
+ * `@classytic/purchase` deliberately types `paymentTerms` as its canonical
+ * union rather than `string` — its own docblock: "a host adapter returning a
+ * typo ('net_30') fails at compile time instead of at persistence". Declaring
+ * `string` here would erase exactly that guarantee at the seam meant to
+ * preserve it.
+ */
+interface ResolvedPaymentTerms<TTerms extends string = string> {
+  paymentTerms: TTerms;
+  creditDays: number;
+  dueDate: Date | null;
+}
+type PolicyBridgeDeps<TTerms extends string = string> = Pick<PurchaseIntegrationDeps, 'suppliers' | 'branches' | 'resolveDueDate' | 'supplierNotFound'> & {
+  defaultPaymentTerms: TTerms;
+};
+declare function createPurchasePolicyBridge<TTerms extends string = string>(deps: PolicyBridgeDeps<TTerms>): {
+  resolveReceivingBranch(inputBranchId: string | undefined): Promise<string>;
+  validateSupplier(supplierId: string): Promise<void>;
+  resolvePaymentTerms(input: {
+    supplierId?: string | undefined;
+    paymentTerms?: TTerms | undefined;
+    creditDays?: unknown;
+    dueDate?: Date | null | undefined;
+    invoiceDate?: Date | undefined;
+  }, _ctx?: unknown): Promise<ResolvedPaymentTerms<TTerms>>;
+};
+//#endregion
+//#region src/bridges/integrations.d.ts
+interface PurchaseIntegrations<TTerms extends string = string> {
+  catalog: ReturnType<typeof createPurchaseCatalogBridge>;
+  policy: ReturnType<typeof createPurchasePolicyBridge<TTerms>>;
+}
+declare function createPurchaseIntegrations<TTerms extends string = string>(deps: Omit<PurchaseIntegrationDeps, 'defaultPaymentTerms'> & {
+  defaultPaymentTerms: TTerms;
+  /** Thrown for an unresolvable product/variant or a negative quantity/cost. */
+  invalidItem(message: string, status?: number): Error;
+}): PurchaseIntegrations<TTerms>;
+//#endregion
+export { type BranchPort, type CatalogBridgeDeps, type PolicyBridgeDeps, type PurchaseCatalogEngineLike, type PurchaseIntegrationDeps, type PurchaseIntegrations, type PurchaseLogger, type PurchasePricelistEngineLike, type ResolvedPaymentTerms, type ResolvedPurchaseLine, type SupplierLike, type SupplierPort, type SupplierQuote, createPurchaseCatalogBridge, createPurchaseIntegrations, createPurchasePolicyBridge };

package/dist/bridges.mjs

@@ -0,0 +1,151 @@
+//#region src/bridges/catalog.bridge.ts
+/** Coerce a possibly-string numeric to a finite number, else the fallback. */
+function num(value, fallback) {
+	const n = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(n) ? n : fallback;
+}
+function createPurchaseCatalogBridge(deps) {
+	async function resolveItems(items, context) {
+		const catalog = await deps.catalog();
+		const currency = context.currency || deps.baseCurrency;
+		const catalogCtx = {
+			actorId: "purchase-service",
+			roles: ["admin"],
+			locale: "en",
+			currency
+		};
+		const uniqueIds = [...new Set(items.map((item) => String(item.product)))];
+		const products = await catalog.repositories.product.findAll({ _id: { $in: uniqueIds } }, {
+			...catalogCtx,
+			lean: true
+		});
+		const productMap = new Map(products.map((p) => [String(p._id), p]));
+		const quotes = /* @__PURE__ */ new Map();
+		const pricelist = context.supplierId ? deps.pricelist?.() ?? null : null;
+		if (pricelist && context.supplierId) for (let i = 0; i < items.length; i++) {
+			const item = items[i];
+			if (!item || item.costPrice !== void 0) continue;
+			try {
+				const quote = await pricelist.repositories.priceList.resolvePartnerPrice({
+					partnerRef: String(context.supplierId),
+					kind: "purchase",
+					productId: String(item.product),
+					...item.variantSku ? { variantSku: item.variantSku } : {},
+					quantity: num(item.quantity, 0) || 1,
+					basePrice: 0
+				}, context.branchId ? { organizationId: context.branchId } : void 0);
+				if (!quote?.ruleMatched) continue;
+				if (quote.currency && quote.currency !== currency) {
+					deps.logger?.warn?.({
+						productId: String(item.product),
+						quoteCurrency: quote.currency,
+						orderCurrency: currency
+					}, "purchase pricelist quote dropped: currency mismatch with order");
+					continue;
+				}
+				quotes.set(i, quote);
+			} catch {}
+		}
+		return items.map((item, index) => {
+			const quantity = num(item.quantity, 0);
+			const costPrice = num(item.costPrice ?? quotes.get(index)?.price, 0);
+			if (quantity < 0 || costPrice < 0) throw deps.invalidItem("Quantity and cost price must be non-negative");
+			const product = productMap.get(String(item.product));
+			if (!product) throw deps.invalidItem(`Product not found: ${String(item.product)}`, 404);
+			if (item.variantSku) {
+				if (!(product.variants ?? []).find((entry) => entry?.sku === item.variantSku)) throw deps.invalidItem(`Variant not found: ${item.variantSku}`, 404);
+			}
+			const quote = quotes.get(index);
+			return {
+				productName: product.name ?? String(item.product),
+				variantSku: item.variantSku ?? null,
+				costPrice: quote?.price ?? num(item.costPrice, 0),
+				currency: quote?.currency ?? context.currency,
+				...quote?.leadTimeDays !== void 0 ? { leadTimeDays: quote.leadTimeDays } : {}
+			};
+		});
+	}
+	/** Batch resolution IS the port in purchase 0.5.x. */
+	return { resolveItems };
+}
+//#endregion
+//#region src/bridges/policy.bridge.ts
+function createPurchasePolicyBridge(deps) {
+	return {
+		async resolveReceivingBranch(inputBranchId) {
+			return deps.branches.resolveReceivingBranch(inputBranchId);
+		},
+		async validateSupplier(supplierId) {
+			if (!await deps.suppliers.getById(supplierId)) throw deps.supplierNotFound(supplierId);
+		},
+		async resolvePaymentTerms(input, _ctx) {
+			const supplier = input.supplierId ? await deps.suppliers.getById(input.supplierId) : null;
+			const paymentTerms = input.paymentTerms || supplier?.paymentTerms || deps.defaultPaymentTerms;
+			const creditDays = Number.isFinite(input.creditDays) ? Number(input.creditDays) : Number.isFinite(supplier?.creditDays) ? Number(supplier?.creditDays) : 0;
+			return {
+				paymentTerms,
+				creditDays,
+				dueDate: deps.resolveDueDate({
+					paymentTerms,
+					creditDays,
+					dueDate: input.dueDate ?? null,
+					invoiceDate: input.invoiceDate
+				})
+			};
+		}
+	};
+}
+//#endregion
+//#region src/bridges/integrations.ts
+/**
+* `createPurchaseIntegrations` — ONE call that wires every purchase bridge.
+*
+* This is the shape a host should meet the spine with:
+*
+* ```ts
+* return createPurchaseModule({
+*   connection,
+*   permissions: purchasePermissions,
+*   bridges: createPurchaseIntegrations({
+*     catalog: () => ensureCatalogEngine(),
+*     pricelist: getPricelistEngineOrNull,
+*     suppliers, branches,
+*     baseCurrency: BASE_CURRENCY,
+*     defaultPaymentTerms: PaymentTerms.CASH,
+*     resolveDueDate, supplierNotFound,
+*   }),
+* });
+* ```
+*
+* ## Why an aggregator rather than exporting the two factories
+*
+* The bridges share deps — both need the supplier master, both are bounded by
+* the same currency. Wiring them separately means a host restates those, and
+* two hosts restate them differently. It also means the host has to KNOW how
+* many bridges the kernel port set has: adding a third would silently leave
+* every existing host without it, with nothing to say so. One factory returning
+* the whole port set makes that a compile error instead.
+*
+* The individual factories stay exported for tests and for a host that
+* genuinely needs to substitute one.
+*/
+function createPurchaseIntegrations(deps) {
+	return {
+		catalog: createPurchaseCatalogBridge({
+			catalog: deps.catalog,
+			pricelist: deps.pricelist,
+			baseCurrency: deps.baseCurrency,
+			logger: deps.logger,
+			invalidItem: deps.invalidItem
+		}),
+		policy: createPurchasePolicyBridge({
+			suppliers: deps.suppliers,
+			branches: deps.branches,
+			defaultPaymentTerms: deps.defaultPaymentTerms,
+			resolveDueDate: deps.resolveDueDate,
+			supplierNotFound: deps.supplierNotFound
+		})
+	};
+}
+//#endregion
+export { createPurchaseCatalogBridge, createPurchaseIntegrations, createPurchasePolicyBridge };

package/dist/entity-model-D-03ovSg.mjs

@@ -0,0 +1,23 @@
+//#region src/entity-model.ts
+function asEntityModel(model) {
+	return model;
+}
+/**
+* Arc's resource layer (custom-controller path) speaks `AnyRecord` — an
+* index-signed record — while the kernel repository is typed on the CLOSED
+* `IPurchaseOrder` interface (no index signature). Same lean entities at
+* runtime; only the static index signature is asserted, and only HERE.
+*/
+function asRecordRepository(repo) {
+	return repo;
+}
+/**
+* Wire-response widening for the same boundary: a hydrated kernel document
+* going out through arc's `IControllerResponse<AnyRecord>` — the closed
+* document interface has no index signature, the payload is unchanged.
+*/
+function asRecord(doc) {
+	return doc;
+}
+//#endregion
+export { asRecord as n, asRecordRepository as r, asEntityModel as t };

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { n as PurchasePermissions, t as PurchaseModuleDeps } from "./types-T9gsXOf_.mjs";
+//#region src/module.d.ts
+declare function createPurchaseModule(deps: PurchaseModuleDeps): import("@classytic/arc/factory").ArcModule<unknown>;
+//#endregion
+export { type PurchaseModuleDeps, type PurchasePermissions, createPurchaseModule };

package/dist/index.mjs

@@ -0,0 +1,140 @@
+import { createPurchaseOrderResource } from "./resources/purchase-order/purchase-order.resource.mjs";
+import { defineEngineModule } from "@spinekit/kit/engine-module";
+import { definePurchase } from "@classytic/purchase/engine";
+import { createPurchaseCleanupSteps } from "@classytic/purchase";
+//#region src/module.ts
+/**
+* createPurchaseModule — @spinekit/purchase's single composition surface.
+*
+*   createApp({ modules: [createPurchaseModule({
+*     connection, permissions,
+*     bridges: { catalog, stockReceipt, sequence },  // kernel ports
+*     extraActions: { ...withApprovalChain({...}), pay: hostPayAction },
+*   })] });
+*
+* Bootstrap RETURNS the engine -> `fastify.arc.modules.purchase` (layer-2
+* export) for container-free cross-module wiring (supplier-performance OTIF
+* scoring, accounting bridges). BYO-engine supported for stranglers.
+* Engine tenancy defaults OFF (kernel `branch` field + arc RequestScope are
+* the boundary — mirrors be-prod's proven wrap).
+*
+* Composed over `defineEngineModule` (`@spinekit/kit/engine-module`) — the ONE
+* primitive for mounting a kernel engine as an arc module. This file used to
+* thread `deferredEngine` + `defineSpineModule` by hand; the primitive now owns
+* the four-piece dance (slot publishing, ownership-conditional teardown,
+* bootstrap-returns-engine, resource threading). Notably, `spine-purchase` is
+* one of the three packages `defineSpineModule`'s `onClose` docblock names as
+* having historically had its host-`onClose` passthrough silently DROPPED
+* whenever `closeOwned` was set — the two arms now COMPOSE (host teardown
+* first, then the owned engine's close), and routing `deps.onClose` through
+* `extend` below keeps riding that composed seam.
+*/
+function createPurchaseModule(deps) {
+	const { module } = defineEngineModule({
+		name: "purchase",
+		/**
+		* BYO engine (a live engine or a host thunk): the host then owns the
+		* lifecycle — `boot` never runs and nothing is closed on teardown. The
+		* purchase kernel's `close()` closes its event transport, so closing a
+		* host-supplied engine here would silence a bus the host still uses.
+		*/
+		...deps.engine !== void 0 ? { supplied: deps.engine } : {},
+		/**
+		* Publish into the HOST's slot when supplied, so a host can READ the engine while this module
+		* keeps OWNERSHIP (it binds it, it closes it). Undefined ⇒ private slot, unreadable outside.
+		*/
+		...deps.slot !== void 0 ? { slot: deps.slot } : {},
+		/**
+		* Allocated at arc's `bootstrap`, never at composition — a graph that fails
+		* validation leaks nothing. (An earlier revision justified construction
+		* placement by "eager resolution is what lets `owns` be derived"; that
+		* constraint died with arc 2.32's `owns: 'provided'`, and the primitive now
+		* owns the timing outright.) A LIVE engine passed by a host is adopted
+		* immediately, so this stays backwards compatible.
+		*
+		* DESCRIBE then BIND: currency policy, tenancy and index policy shape the
+		* documents; the connection, bridges and transport are live collaborators.
+		*/
+		boot: () => definePurchase({
+			baseCurrency: deps.baseCurrency,
+			...deps.allowForeignCurrency !== void 0 ? { allowForeignCurrency: deps.allowForeignCurrency } : {},
+			tenant: deps.tenant ?? false,
+			...deps.autoIndex !== void 0 ? { autoIndex: deps.autoIndex } : {},
+			...deps.forceRecreate !== void 0 ? { forceRecreate: deps.forceRecreate } : {}
+		}).bind(deps.connection, {
+			...deps.bridges ? { bridges: deps.bridges } : {},
+			...deps.eventTransport ? { eventTransport: deps.eventTransport } : {},
+			...deps.outbox ? { outbox: deps.outbox } : {},
+			/**
+			* Transaction waiver — forwarded ONLY when the host stated it.
+			*
+			* Never `deps.allowNonTransactional ?? true`: that would be a general default overriding
+			* a specific decision on a MONEY path, and it fails in the expensive direction (a
+			* misconfigured production deployment moving money non-atomically, with nothing thrown).
+			* Absent ⇒ the kernel's fail-closed requirement stands.
+			*/
+			...deps.allowNonTransactional !== void 0 ? { allowNonTransactional: deps.allowNonTransactional } : {}
+		}),
+		resources: (engine) => {
+			const late = deps.wiring?.() ?? {};
+			const permissions = deps.permissions ?? late.permissions;
+			if (permissions === void 0) throw new Error("[spine-purchase] permissions were not supplied. Pass `permissions` directly, or return them from the `wiring` thunk when they depend on the engine. Refusing to mount purchase resources with no permission gates.");
+			const pick = (k) => deps[k] ?? late[k];
+			return [createPurchaseOrderResource({
+				engine,
+				permissions,
+				...deps.prefix ? { prefix: deps.prefix } : {},
+				...pick("extraActions") ? { extraActions: pick("extraActions") } : {},
+				...pick("extraRoutes") ? { extraRoutes: pick("extraRoutes") } : {},
+				...pick("readPopulate") ? { readPopulate: pick("readPopulate") } : {}
+			})];
+		},
+		/**
+		* Arms the primitive's config does not enumerate, built against the
+		* LATE-BOUND engine accessor: capture `get`, never `get()` — the engine
+		* exists only after bootstrap, and each arm below is a thunk for exactly
+		* that reason.
+		*/
+		extend: (get) => ({
+			/**
+			* Host teardown passthrough. Composes with the owned-engine close in
+			* `defineSpineModule` (host `onClose` FIRST, then `closeOwned`) — the
+			* seam where this exact passthrough was once silently dropped.
+			*/
+			...deps.onClose !== void 0 ? { onClose: deps.onClose } : {},
+			/**
+			* Pre-live purge targets — what a reset wipes for this domain, and what must go FIRST.
+			*
+			* `after` declares the real data dependency, not a preferred position. The host used to
+			* encode the whole sequence as numbered comments (`// 0.` … `// 6.`) with nothing
+			* verifying them; reordering two blocks silently changed a destructive run.
+			*/
+			preLivePurge: () => ({
+				targets: [{
+					id: "pre-live.purchase-orders",
+					resource: "purchase orders",
+					repo: get().repositories.purchaseOrder
+				}, {
+					id: "pre-live.supplier-bills",
+					resource: "supplier bills",
+					repo: get().repositories.supplierBill
+				}],
+				after: ["order"]
+			}),
+			/**
+			* Retention steps this domain contributes.
+			*
+			* `createPurchaseCleanupSteps` has always existed in the kernel; what was missing was a way
+			* to OFFER it. So a host did the offering — re-checking the feature gate that already
+			* decided this module composes, re-importing the engine held right here, and calling the
+			* kernel itself. The collector needs no list of domains, so nothing has to remember this
+			* one exists. Via `extend` (not the dedicated config field) because the thunk closes over
+			* the engine accessor.
+			*/
+			cleanupSteps: () => ({ drafts: [createPurchaseCleanupSteps({ repositories: get().repositories }).removeDrafts] })
+		})
+	});
+	return module;
+}
+//#endregion
+export { createPurchaseModule };