@spinekit/purchase 0.1.0

package/dist/lifecycle/purchase-lifecycle.d.mts

@@ -0,0 +1,17 @@
+import { PurchaseLifecycleDeps } from "./purchase-lifecycle.types.mjs";
+import { PurchaseOrderDocument } from "@classytic/purchase";
+//#region src/lifecycle/purchase-lifecycle.d.ts
+declare function createPurchaseLifecycle(deps: PurchaseLifecycleDeps): {
+  /** Approve a draft purchase — `draft → approved`, atomically via the kernel's CAS. */
+  approve(purchaseId: string, actorId: string | undefined): Promise<PurchaseOrderDocument>;
+  /** Cancel a draft or approved purchase — one atomic claim, so no concurrent
+   *  payment / approval / receive can slip past the FSM gate. */
+  cancel(purchaseId: string, actorId: string | undefined, reason?: string): Promise<PurchaseOrderDocument>;
+  /**
+   * Receive a purchase order. See the module header for the transaction boundary — the part
+   * that is genuinely subtle and the part a second host would get wrong.
+   */
+  receive(purchaseId: string, actorId: string | undefined): Promise<Record<string, unknown>>;
+};
+//#endregion
+export { createPurchaseLifecycle };

package/dist/lifecycle/purchase-lifecycle.mjs

@@ -0,0 +1,120 @@
+import { PENDING_EVENTS, flushPending } from "@classytic/purchase";
+import { ConflictError, NotFoundError } from "@classytic/arc/utils";
+//#region src/lifecycle/purchase-lifecycle.ts
+/**
+* Purchase-order LIFECYCLE verbs — approve · cancel · receive.
+*
+* Lifted from be-prod (`purchase-order/actions/{approve,cancel,receive}-purchase-order.ts` plus
+* the state machine that lived in `purchase-order.service.ts`). Each verb is thin because the
+* kernel's repository owns the atomic transition; what was worth extracting is the ORDER of
+* operations around it, which is where every silent failure lives.
+*
+* ## Why the pre-CAS read exists at all
+*
+* The kernel's `claim()` CAS already enforces the FSM — a cancel cannot race past an approve.
+* But a CAS that finds no match returns "no match", which is indistinguishable from losing a
+* concurrency race. The read before it exists purely so a caller learns *"only draft purchases
+* can be approved"* instead of *"concurrent modification"*. It is a MESSAGE, never the guard:
+* removing it costs clarity, and trusting it instead of the CAS would cost correctness.
+*
+* ## Receive: what is deliberately OUTSIDE the transaction
+*
+* The kernel's `receive()` does the CAS first, stamps `pendingStockReceipt` so a crash between
+* the CAS and the bridge heals on the next receive, and compensates the status back if the
+* bridge throws. The stock booking itself runs in the WMS's OWN unit of work — nested Mongo
+* transactions do not exist — so a failure *after* the bridge rolls the PO back to `approved`
+* while the booked stock REMAINS. That divergence is CONVERGED, not prevented: the bridge is
+* idempotent on `purchaseId`, so the healing receive re-fires it as a no-op and completes the
+* flip.
+*/
+/**
+* Prior states each verb accepts, for the friendly pre-CAS message only.
+*
+* The kernel's FSM is the authority. This map exists so the two cannot silently disagree in
+* the direction that matters: it may only ever be a SUBSET of what the kernel permits — a
+* superset would produce a helpful-looking message for a transition the CAS then refuses.
+*/
+const ALLOWED_PRIOR_STATES = {
+	approve: ["draft"],
+	cancel: ["draft", "approved"]
+};
+const REFUSAL = {
+	approve: "Only draft purchases can be approved",
+	cancel: "Only draft or approved purchases can be cancelled"
+};
+function createPurchaseLifecycle(deps) {
+	/** Load for the friendly message. Lean — nothing here mutates the document. */
+	async function readStatus(purchaseId) {
+		const purchase = await deps.engine().models.PurchaseOrder.findById(purchaseId).lean();
+		if (!purchase) throw new NotFoundError("Purchase");
+		return purchase.status ?? "unknown";
+	}
+	function assertPrior(verb, status) {
+		if (!ALLOWED_PRIOR_STATES[verb].includes(status)) throw new ConflictError(`${REFUSAL[verb]} (current status: ${status})`);
+	}
+	return {
+		/** Approve a draft purchase — `draft → approved`, atomically via the kernel's CAS. */
+		async approve(purchaseId, actorId) {
+			assertPrior("approve", await readStatus(purchaseId));
+			return deps.engine().repositories.purchaseOrder.approve(purchaseId, actorId ? { actorId } : {});
+		},
+		/** Cancel a draft or approved purchase — one atomic claim, so no concurrent
+		*  payment / approval / receive can slip past the FSM gate. */
+		async cancel(purchaseId, actorId, reason) {
+			assertPrior("cancel", await readStatus(purchaseId));
+			return deps.engine().repositories.purchaseOrder.cancel(purchaseId, reason, actorId ? { actorId } : {});
+		},
+		/**
+		* Receive a purchase order. See the module header for the transaction boundary — the part
+		* that is genuinely subtle and the part a second host would get wrong.
+		*/
+		async receive(purchaseId, actorId) {
+			let resolvedSupplierName;
+			/**
+			* Managed-session contract (purchase 0.2+): given `ctx.session` the kernel QUEUES its
+			* domain events rather than publishing mid-transaction. A subscriber must never observe
+			* events for a write that may still roll back.
+			*/
+			const pendingEvents = [];
+			return deps.withTransaction(async (session) => {
+				const engine = deps.engine();
+				const repo = engine.repositories.purchaseOrder;
+				const ctx = {
+					...actorId !== void 0 ? { actorId } : {},
+					...session ? {
+						session,
+						[PENDING_EVENTS]: pendingEvents
+					} : {}
+				};
+				const query = engine.models.PurchaseOrder.findById(purchaseId);
+				const existing = await (session ? query.session(session) : query);
+				if (!existing) throw new NotFoundError("Purchase");
+				/**
+				* Receiving a draft implies approval — it stamps approvedBy/At and an APPROVED
+				* history entry. Routing through the kernel verb rather than an inline status write
+				* is what makes the approval-chain gate apply: a PO with a pending multi-step chain
+				* can no longer be received *around* its chain.
+				*/
+				if (existing.status === "draft") await repo.approve(purchaseId, ctx);
+				const updated = await repo.receive(purchaseId, ctx);
+				const supplierId = updated.supplier ? String(updated.supplier) : void 0;
+				resolvedSupplierName = (await deps.supplier.getById(supplierId))?.name;
+				return typeof updated.toObject === "function" ? updated.toObject() : updated;
+			}, { onCommit: async (purchase) => {
+				await flushPending(deps.eventTransport, pendingEvents, deps.logger);
+				/**
+				* Host side effects — notifications, cache invalidation. Deliberately after the
+				* drain and deliberately a HOOK: which of these a deployment wants is not this
+				* package's business, and running them pre-commit would announce a receive that
+				* an abort un-makes.
+				*/
+				await deps.onReceived?.(purchase, {
+					actorId,
+					supplierName: resolvedSupplierName
+				});
+			} });
+		}
+	};
+}
+//#endregion
+export { createPurchaseLifecycle };

package/dist/lifecycle/purchase-lifecycle.types.d.mts

@@ -0,0 +1,32 @@
+import { c as PurchaseUnitOfWork, s as PurchaseSupplierLookup } from "../purchase-payment.types-hVKAeW3G.mjs";
+import { PurchaseEngine } from "@classytic/purchase/engine";
+import { flushPending } from "@classytic/purchase";
+import { EventTransport } from "@classytic/primitives/events";
+//#region src/lifecycle/purchase-lifecycle.types.d.ts
+/**
+ * Host side effects for a COMMITTED receive — notifications, cache invalidation, anything
+ * outward-facing.
+ *
+ * A hook rather than ports for each concern: which side effects a deployment wants is not the
+ * package's business, and enumerating them here would mean editing the package every time a
+ * vertical adds one. It runs post-commit, so it can safely announce the receive.
+ */
+interface PurchaseReceivedHook {
+  (purchase: Record<string, unknown>, context: {
+    actorId?: string | undefined;
+    supplierName?: string | undefined;
+  }): Promise<void> | void;
+}
+interface PurchaseLifecycleDeps {
+  /** Getter, not a handle — nothing may allocate the engine during composition. */
+  engine: () => PurchaseEngine;
+  withTransaction: PurchaseUnitOfWork;
+  supplier: PurchaseSupplierLookup;
+  /** Where the kernel's queued `purchase:order.{approved,received}` are drained, post-commit. */
+  eventTransport: EventTransport;
+  /** Derived from the kernel's contract so it cannot drift from `flushPending`. */
+  logger: Parameters<typeof flushPending>[2];
+  onReceived?: PurchaseReceivedHook | undefined;
+}
+//#endregion
+export { PurchaseLifecycleDeps, PurchaseReceivedHook };

package/dist/lifecycle/purchase-lifecycle.types.mjs

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

package/dist/payment/purchase-payment.application.d.mts

@@ -0,0 +1,8 @@
+import { n as PurchasePaymentApplicationDeps, t as PayPurchaseCommand } from "../purchase-payment.types-hVKAeW3G.mjs";
+//#region src/payment/purchase-payment.application.d.ts
+declare function createPurchasePaymentApplication(deps: PurchasePaymentApplicationDeps): {
+  /** Pay a purchase order — the whole compound operation, atomically. */
+  pay({ purchaseId, payment, actorId }: PayPurchaseCommand): Promise<unknown>;
+};
+//#endregion
+export { createPurchasePaymentApplication };

package/dist/payment/purchase-payment.application.mjs

@@ -0,0 +1,154 @@
+import { PENDING_EVENTS, flushPending } from "@classytic/purchase";
+import { ConflictError, NotFoundError, ValidationError } from "@classytic/arc/utils";
+import { convertMinorToBaseMinor } from "@classytic/purchase/domain";
+//#region src/payment/purchase-payment.application.ts
+/**
+* Purchase-payment APPLICATION SERVICE — the compound "pay a PO" operation.
+*
+* Lifted from be-prod (`modules/inventory/purchase-order/purchase-payment.application.ts`),
+* where it was ~210 lines no other host could pay a supplier with. The gym's equivalent gap
+* — payment confirmation living in a host — is why an order could be created and never
+* confirmed, with nothing erroring.
+*
+* Owns the unit of work (one `withTransaction`):
+*   1. guards — exists, payable state, integer minor units, cap by amount due
+*   2. tax attribution for partial payments, via the PACK's port
+*   3. `PurchasePaymentRecordingPort.record()` — the payment-side write; revenue and ledger
+*      knowledge lives ONLY in the injected adapter
+*   4. the kernel's `purchaseOrder.pay()` — atomic `$add` CAS, FSM-pinned
+*   5. queued `purchase:order.paid` domain events, drained post-commit
+*
+* The kernel never sees revenue or ledger; an HTTP action never sees the orchestration. A
+* test injects a fake recording port and exercises the whole unit.
+*
+* ORDER IS LOAD-BEARING. The payment record is written INSIDE the session and BEFORE the CAS,
+* so a lost CAS rolls the record back. Recording after a successful CAS would leave a paid PO
+* with no cash record if the second write failed — a reconciliation gap that nothing reports.
+*/
+/**
+* Guard the transaction date at the boundary — `new Date('garbage')` is an Invalid Date that
+* survives every type check and only explodes later, inside accounting, on a document nobody
+* can trace back to this request.
+*/
+function resolveTransactionDate(input) {
+	if (input === void 0) return /* @__PURE__ */ new Date();
+	const parsed = new Date(input);
+	if (Number.isNaN(parsed.getTime())) throw new ValidationError(`transactionDate ${JSON.stringify(input)} is not a valid date`);
+	return parsed;
+}
+function createPurchasePaymentApplication(deps) {
+	return { 
+	/** Pay a purchase order — the whole compound operation, atomically. */
+async pay({ purchaseId, payment, actorId }) {
+		/**
+		* Managed-session contract (purchase 0.2+): given `ctx.session`, the kernel QUEUES its
+		* domain events instead of publishing mid-transaction. Publishing inside the
+		* transaction announces a payment that a later abort un-makes.
+		*/
+		const pendingEvents = [];
+		return deps.withTransaction(async (session) => {
+			const engine = deps.engine();
+			const query = engine.models.PurchaseOrder.findById(purchaseId);
+			const purchase = await (session ? query.session(session) : query);
+			if (!purchase) throw new NotFoundError("Purchase");
+			/**
+			* A precise message before the CAS. The kernel's filter would also reject a
+			* cancelled PO, but as a no-match — indistinguishable from a concurrency loss.
+			*/
+			if (purchase.status === "cancelled") throw new ConflictError("Cancelled purchases cannot be paid");
+			/**
+			* `amount` is integer MINOR units (schemaVersion 2). Defaulting to `dueAmount` is
+			* unit-consistent because the document persists minor units too — the one place
+			* this could silently break is a host that still sends major units, which the
+			* integer guard below does NOT catch (12.50 fails, but 1250 major would pass as
+			* 12.50 base). That is why the wire schema, not this guard, is the unit authority.
+			*/
+			const amount = payment.amount ?? purchase.dueAmount;
+			if (!Number.isInteger(amount) || amount <= 0) throw new ValidationError("Payment amount must be a positive integer in minor units");
+			/**
+			* Cap guard — read against this snapshot. A concurrent payment still composes
+			* correctly in the kernel's `$add` CAS (no lost increment); a small overshoot
+			* between the read and the write is a UX issue, not a correctness one.
+			*/
+			if (amount > purchase.dueAmount) throw new ValidationError("Payment amount exceeds due amount");
+			const supplierId = purchase.supplier ? String(purchase.supplier) : void 0;
+			const supplier = await deps.supplier.getById(supplierId);
+			const purchaseTaxTotal = Number.isFinite(purchase.taxTotal) ? purchase.taxTotal : 0;
+			const dominantRatePercent = purchase.items.reduce((max, item) => (item.taxRate ?? 0) > max ? item.taxRate ?? 0 : max, 0);
+			const attributed = deps.taxAttribution.attribute({
+				purchaseTaxTotalMinor: purchaseTaxTotal,
+				paymentAmountMinor: amount,
+				purchaseGrandTotalMinor: purchase.grandTotal,
+				dominantRatePercent
+			});
+			const paymentTax = attributed.taxMinor;
+			const taxDetails = attributed.details;
+			/**
+			* A pack is host-supplied code, so its output is an INPUT here. An
+			* over-attribution overstates a recoverable-tax position that a filing depends on,
+			* and a non-integer minor amount corrupts every downstream sum — both must fail
+			* loudly rather than propagate a plausible number.
+			*/
+			if (!Number.isInteger(paymentTax) || paymentTax < 0) throw new ValidationError("Tax attribution must return a non-negative integer");
+			if (paymentTax > purchaseTaxTotal) throw new ValidationError("Tax attribution exceeds the order tax total");
+			/**
+			* Base-currency conversion via the PO's FROZEN snapshot — the same kernel VO the
+			* receive / GR-IR / vendor-bill legs use, so the cash record agrees with the
+			* inventory and A/P values. Re-fetching a live rate here would make them disagree.
+			*/
+			const fx = purchase.fx ?? null;
+			const baseAmountMinor = convertMinorToBaseMinor(amount, fx);
+			const baseTaxMinor = convertMinorToBaseMinor(paymentTax, fx);
+			const { transactionId } = await deps.recordPayment.record({
+				amountMinor: amount,
+				taxMinor: paymentTax,
+				baseAmountMinor,
+				baseTaxMinor,
+				fx,
+				currency: purchase.currency ?? deps.baseCurrency,
+				method: payment.method || "cash",
+				purchase: {
+					id: String(purchase._id),
+					invoiceNumber: purchase.invoiceNumber,
+					branchId: String(purchase.branch)
+				},
+				...supplier ? { supplier: {
+					id: String(supplier._id),
+					name: supplier.name
+				} } : {},
+				paymentDetails: payment.details ?? {},
+				taxDetails,
+				purchaseTaxTotalMinor: purchaseTaxTotal,
+				notes: [
+					`Purchase payment: ${purchase.invoiceNumber}`,
+					supplier?.name ? `Supplier: ${supplier.name}` : null,
+					payment.notes
+				].filter(Boolean).join(". "),
+				actorId,
+				date: resolveTransactionDate(payment.transactionDate),
+				session
+			});
+			/**
+			* 2. Atomic CAS via the kernel's `pay()` — `$add` paidAmount, recompute dueAmount
+			*    and paymentStatus post-increment, push the transactionId. FSM-pinned and
+			*    concurrency-safe by construction, which is why nothing here recomputes a
+			*    payment status itself.
+			*/
+			return engine.repositories.purchaseOrder.pay(purchaseId, {
+				amount,
+				transactionId,
+				...payment.method ? { method: payment.method } : {}
+			}, {
+				...actorId ? { actorId } : {},
+				...session ? {
+					session,
+					[PENDING_EVENTS]: pendingEvents
+				} : {}
+			});
+		}, { onCommit: async () => {
+			await flushPending(deps.eventTransport, pendingEvents, deps.logger);
+		} });
+	} };
+}
+//#endregion
+export { createPurchasePaymentApplication };

package/dist/payment/purchase-payment.tax.d.mts

@@ -0,0 +1,30 @@
+import { i as PurchasePaymentTaxAttribution } from "../purchase-payment.types-hVKAeW3G.mjs";
+//#region src/payment/purchase-payment.tax.d.ts
+/** What the pack names the tax it is attributing. */
+interface ProRataTaxLabels {
+  /** `vat`, `gst`, `sales_tax`, … */
+  type: string;
+  /** Taxing authority identifier as the host's books expect it. */
+  jurisdiction: string;
+  /** Whether the order's line rates are tax-inclusive. Defaults to exclusive. */
+  isInclusive?: boolean | undefined;
+}
+/**
+ * PAYMENT-basis attribution: `taxTotal × amount / grandTotal`, rounded once.
+ *
+ * Computed as a single expression rather than `total × (amount / grandTotal)` — the two-step
+ * form rounds a float ratio and then multiplies, which drifts by a minor unit on ordinary
+ * inputs and makes a sum of payments disagree with the order's own tax total.
+ *
+ * Zero when the order carries no tax or no total; a rate of zero yields an amount with no
+ * `details`, because there is nothing to describe.
+ */
+declare function proRataTaxAttribution(labels: ProRataTaxLabels): PurchasePaymentTaxAttribution;
+/**
+ * INVOICE-basis attribution — a payment attributes no tax because posting the bill already
+ * did. Explicit rather than "just leave the port off": a host states its recognition basis,
+ * and a reader of the wiring can see which one.
+ */
+declare function invoiceBasisTaxAttribution(): PurchasePaymentTaxAttribution;
+//#endregion
+export { ProRataTaxLabels, invoiceBasisTaxAttribution, proRataTaxAttribution };

package/dist/payment/purchase-payment.tax.mjs

@@ -0,0 +1,37 @@
+//#region src/payment/purchase-payment.tax.ts
+/**
+* PAYMENT-basis attribution: `taxTotal × amount / grandTotal`, rounded once.
+*
+* Computed as a single expression rather than `total × (amount / grandTotal)` — the two-step
+* form rounds a float ratio and then multiplies, which drifts by a minor unit on ordinary
+* inputs and makes a sum of payments disagree with the order's own tax total.
+*
+* Zero when the order carries no tax or no total; a rate of zero yields an amount with no
+* `details`, because there is nothing to describe.
+*/
+function proRataTaxAttribution(labels) {
+	return { attribute({ purchaseTaxTotalMinor, paymentAmountMinor, purchaseGrandTotalMinor, dominantRatePercent }) {
+		if (purchaseTaxTotalMinor <= 0 || purchaseGrandTotalMinor <= 0) return { taxMinor: 0 };
+		const taxMinor = Math.round(purchaseTaxTotalMinor * paymentAmountMinor / purchaseGrandTotalMinor);
+		if (dominantRatePercent <= 0) return { taxMinor };
+		return {
+			taxMinor,
+			details: {
+				type: labels.type,
+				rate: dominantRatePercent / 100,
+				isInclusive: labels.isInclusive ?? false,
+				jurisdiction: labels.jurisdiction
+			}
+		};
+	} };
+}
+/**
+* INVOICE-basis attribution — a payment attributes no tax because posting the bill already
+* did. Explicit rather than "just leave the port off": a host states its recognition basis,
+* and a reader of the wiring can see which one.
+*/
+function invoiceBasisTaxAttribution() {
+	return { attribute: () => ({ taxMinor: 0 }) };
+}
+//#endregion
+export { invoiceBasisTaxAttribution, proRataTaxAttribution };

package/dist/payment/purchase-payment.types.d.mts

@@ -0,0 +1,2 @@
+import { a as PurchasePaymentTaxDetails, c as PurchaseUnitOfWork, i as PurchasePaymentTaxAttribution, l as RecordPurchasePaymentInput, n as PurchasePaymentApplicationDeps, o as PurchasePaymentTaxInput, r as PurchasePaymentRecordingPort, s as PurchaseSupplierLookup, t as PayPurchaseCommand } from "../purchase-payment.types-hVKAeW3G.mjs";
+export { PayPurchaseCommand, PurchasePaymentApplicationDeps, PurchasePaymentRecordingPort, PurchasePaymentTaxAttribution, PurchasePaymentTaxDetails, PurchasePaymentTaxInput, PurchaseSupplierLookup, PurchaseUnitOfWork, RecordPurchasePaymentInput };

package/dist/payment/purchase-payment.types.mjs

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

package/dist/purchase-payment.types-hVKAeW3G.d.mts

@@ -0,0 +1,153 @@
+import { PurchaseEngine } from "@classytic/purchase/engine";
+import { flushPending } from "@classytic/purchase";
+import { ClientSession } from "mongoose";
+import { EventTransport } from "@classytic/primitives/events";
+import { FxSnapshot } from "@classytic/primitives/currency";
+//#region src/payment/purchase-payment.types.d.ts
+/** How a pack describes an attributed tax amount. Shape only — no type or jurisdiction value. */
+interface PurchasePaymentTaxDetails {
+  /** `vat`, `gst`, `sales_tax`, … — the PACK's vocabulary, never this package's. */
+  type: string;
+  /** Fractional rate (0.15), not percent. */
+  rate: number;
+  isInclusive: boolean;
+  /** Whatever identifies the taxing authority to the host's books. */
+  jurisdiction: string;
+}
+interface PurchasePaymentTaxInput {
+  /** Whole-order tax total, DOCUMENT-currency minor units. */
+  purchaseTaxTotalMinor: number;
+  /** This payment, DOCUMENT-currency minor units. */
+  paymentAmountMinor: number;
+  /** Order grand total, DOCUMENT-currency minor units — the pro-rata denominator. */
+  purchaseGrandTotalMinor: number;
+  /** Highest line rate on the order, as a PERCENT (15, not 0.15) — the kernel's field unit. */
+  dominantRatePercent: number;
+}
+/**
+ * When tax is recognised and what it is called. See the neutrality note above.
+ *
+ * `taxMinor` MUST NOT exceed `purchaseTaxTotalMinor`, and MUST be an integer — the
+ * application service enforces both, because an over-attribution silently overstates a
+ * recoverable-tax position that a filing later depends on.
+ */
+interface PurchasePaymentTaxAttribution {
+  attribute(input: PurchasePaymentTaxInput): {
+    taxMinor: number;
+    details?: PurchasePaymentTaxDetails | undefined;
+  };
+}
+interface RecordPurchasePaymentInput {
+  /** Payment amount in integer MINOR units of the DOCUMENT currency — what updates
+   *  paidAmount/dueAmount on the PO. */
+  amountMinor: number;
+  /** Attributed tax portion of this payment, DOCUMENT-currency minor units. */
+  taxMinor: number;
+  /**
+   * Payment amount converted to the deployment's BASE currency via the PO's frozen
+   * FxSnapshot (equal to `amountMinor` on base-currency POs).
+   *
+   * Financial adapters (revenue / ledger) MUST consume the base fields. Recording a
+   * document amount as a book value is the mis-recording class this split exists to kill,
+   * and its magnitude is the FX rate — invisible on a base-currency deployment, ~120× on a
+   * USD document in a BDT book.
+   */
+  baseAmountMinor: number;
+  /** Attributed tax in BASE-currency minor units. */
+  baseTaxMinor: number;
+  /** Frozen conversion record — null on base-currency POs. */
+  fx: FxSnapshot | null;
+  currency: string;
+  method: string;
+  purchase: {
+    id: string;
+    invoiceNumber: string;
+    branchId: string;
+  };
+  supplier?: {
+    id: string;
+    name?: string | undefined;
+  } | undefined;
+  /**
+   * Rail-specific references. Deliberately an open bag: `walletNumber` is a mobile-money
+   * concept, `bankName` a wire concept, and a pack adds its own without this package
+   * enumerating the world's payment rails.
+   */
+  paymentDetails: Record<string, string | undefined>;
+  taxDetails?: PurchasePaymentTaxDetails | undefined;
+  /** Whole-order tax total (minor units) — provenance for reconciliation. */
+  purchaseTaxTotalMinor: number;
+  notes?: string | undefined;
+  actorId?: string | undefined;
+  date: Date;
+  /** Session of the surrounding unit of work — the write MUST enlist in it. */
+  session: ClientSession | null;
+}
+/**
+ * Payment-side recording seam. The application service calls this INSIDE its transaction;
+ * the adapter's write must enlist in `input.session` so a later kernel-CAS failure rolls the
+ * payment record back with everything else.
+ *
+ * Revenue and ledger knowledge lives ONLY behind this port — the kernel never sees either.
+ */
+interface PurchasePaymentRecordingPort {
+  record(input: RecordPurchasePaymentInput): Promise<{
+    transactionId: string;
+  }>;
+}
+/**
+ * The surrounding unit of work. A host owns whether its deployment has transactions at all
+ * (a standalone mongod has no sessions), which is why `session` is nullable and the port is
+ * injected rather than opened here.
+ */
+interface PurchaseUnitOfWork {
+  <T>(work: (session: ClientSession | null) => Promise<T>,
+  /**
+   * `onCommit` receives the work's RESULT — the lifecycle's receive hook needs the persisted
+   * document, and a callback that took nothing would force a host to smuggle it out through a
+   * closure variable assigned inside the transaction.
+   */
+  options: {
+    onCommit: (result: T) => Promise<void>;
+  }): Promise<T>;
+}
+/** Supplier name/id for the payment record's provenance. Not a party contract — a lookup. */
+interface PurchaseSupplierLookup {
+  getById(id: string | undefined): Promise<{
+    _id: unknown;
+    name?: string | undefined;
+  } | null>;
+}
+interface PurchasePaymentApplicationDeps {
+  /**
+   * Engine GETTER, not an engine. Captured as `slot.get`, never `slot.get()` — reading the
+   * slot during composition throws by name instead of allocating before arc owns the
+   * lifecycle.
+   */
+  engine: () => PurchaseEngine;
+  recordPayment: PurchasePaymentRecordingPort;
+  withTransaction: PurchaseUnitOfWork;
+  supplier: PurchaseSupplierLookup;
+  taxAttribution: PurchasePaymentTaxAttribution;
+  /** ISO 4217 functional currency — the fallback for a PO that stored none. */
+  baseCurrency: string;
+  /** Where the kernel's queued `purchase:order.paid` is drained to, post-commit. */
+  eventTransport: EventTransport;
+  /** Derived from the kernel's own contract so it cannot drift from `flushPending`. */
+  logger: Parameters<typeof flushPending>[2];
+}
+interface PayPurchaseCommand {
+  purchaseId: string;
+  payment: {
+    /** Integer MINOR units. Defaults to the PO's `dueAmount` (same unit) when absent. */
+    amount?: number | undefined;
+    method?: string | undefined;
+    transactionDate?: string | undefined;
+    notes?: string | undefined;
+    /** Rail references — forwarded to the recording port verbatim. */
+    details?: Record<string, string | undefined> | undefined;
+  };
+  actorId?: string | undefined;
+}
+//#endregion
+export { PurchasePaymentTaxDetails as a, PurchaseUnitOfWork as c, PurchasePaymentTaxAttribution as i, RecordPurchasePaymentInput as l, PurchasePaymentApplicationDeps as n, PurchasePaymentTaxInput as o, PurchasePaymentRecordingPort as r, PurchaseSupplierLookup as s, PayPurchaseCommand as t };

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

@@ -0,0 +1,12 @@
+import { PurchaseReceiptContext, PurchaseReceiptLineError, PurchaseReceiptScope, PurchaseStockReceiptDeps, ReceivePurchaseIntoStockInput } from "./purchase-stock-receipt.types.mjs";
+//#region src/receipt/purchase-stock-receipt.d.ts
+declare function createPurchaseStockReceipt<TCtx extends PurchaseReceiptScope = PurchaseReceiptContext>(deps: PurchaseStockReceiptDeps<TCtx>): {
+  /**
+   * 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.
+   */
+  receive({ purchase, supplierName }: ReceivePurchaseIntoStockInput): Promise<PurchaseReceiptLineError[]>;
+};
+//#endregion
+export { createPurchaseStockReceipt };