@spinekit/purchase 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.3.0 - 2026-08-24
+
+### Added
+
+- **`@spinekit/purchase/import` subpath** — `PurchaseImportApplication` and `createPurchaseImportApplication`: drives the BD import clearance flow on a procurement order (claim the CAS slot, resolve AT/AIT split via `bd-tax`, post journal via ledger-bd, publish `ImportCleared` event). Application layer only; the resource action wiring lives in `@spinekit/inventory/integrations/import-clearance`.
+- **`@spinekit/purchase/import/types` subpath** — `PurchaseImportInput`, `PurchaseImportResult`, `PurchaseImportDeps` type-only export for hosts that need the contract without the implementation.
+
+## 0.2.0 - 2026-08-23
+
+### Changed
+
+- **`PurchaseStockReceiptDeps.skuRef` now accepts `string | Promise<string>`** — the correct key is the variant's stamped `skuRef` on the product document; a host resolving it must be allowed a read. Sync legacy derivations remain assignable — no existing host breaks. `createPurchaseStockReceipt` now `await`s the call.
+
 ## 0.1.1 - 2026-08-21
 
 ### Changed

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

@@ -0,0 +1,51 @@
+import { ClearImportCommand, ClearImportResult, PurchaseImportApplicationDeps } from "./purchase-import.types.mjs";
+//#region src/import/purchase-import.application.d.ts
+/** Thrown for every refusal below, so a host maps one error type to a 4xx. */
+declare class ImportClearanceError extends Error {
+  readonly code: 'PURCHASE_NOT_FOUND' | 'NOT_AN_IMPORT' | 'NOT_RECEIVED' | 'ALREADY_CLEARED' | 'INVALID_ASSESSMENT';
+  constructor(code: 'PURCHASE_NOT_FOUND' | 'NOT_AN_IMPORT' | 'NOT_RECEIVED' | 'ALREADY_CLEARED' | 'INVALID_ASSESSMENT', message: string);
+}
+/** Cost-line codes for the capitalized duties. Stable — a reversal matches on them. */
+declare const IMPORT_DUTY_CODES: {
+  readonly customsDuty: 'CUSTOMS_DUTY';
+  readonly regulatoryDuty: 'REGULATORY_DUTY';
+  readonly supplementaryDuty: 'SUPPLEMENTARY_DUTY';
+};
+/**
+ * The clearance is identified by the purchase AND the Bill of Entry number.
+ *
+ * Deterministic, never random: a random fallback defeats deduplication while
+ * looking correctly wired. One purchase can legitimately clear under more than
+ * one BoE (a split consignment), so the purchase alone is too coarse; the BoE
+ * alone is too coarse across purchases.
+ */
+declare function importClearanceKey(purchaseId: string, billOfEntryNumber: string): string;
+declare function createPurchaseImportClearance(deps: PurchaseImportApplicationDeps): (command: ClearImportCommand) => Promise<ClearImportResult>;
+/**
+ * The arc action handler for the clearance — body validation, command
+ * assembly, and the error-to-wire mapping. Host-independent: every host
+ * mounting `clear-import` needs exactly this sequence, so it lives with the
+ * action rather than being re-typed per deployment. The host supplies only
+ * the per-request builder (its engines and tenancy are in there) and the
+ * permission gate at the resource seam.
+ */
+interface ClearImportWireBody {
+  billOfEntryNumber?: string;
+  billOfEntryDate?: string;
+  assessableValue?: number;
+  rates?: Record<string, number>;
+}
+declare function createClearImportActionHandler(deps: {
+  /** Build the request-scoped action — ports are tenant-bound per request. */
+  build: (req: unknown) => (command: ClearImportCommand) => Promise<ClearImportResult>;
+  /** Actor for the clearance stamp, resolved from the request. */
+  actorId: (req: unknown) => string;
+  /** Wire error constructors — arc's, supplied so this file stays arc-free. */
+  errors: {
+    validation: (message: string) => Error;
+    notFound: (message: string) => Error;
+    domain: (code: string, message: string, status: number) => Error;
+  };
+}): (id: string, data: unknown, req: unknown) => Promise<ClearImportResult>;
+//#endregion
+export { ClearImportWireBody, IMPORT_DUTY_CODES, ImportClearanceError, createClearImportActionHandler, createPurchaseImportClearance, importClearanceKey };

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

@@ -0,0 +1,204 @@
+//#region src/import/purchase-import.application.ts
+/** Thrown for every refusal below, so a host maps one error type to a 4xx. */
+var ImportClearanceError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "ImportClearanceError";
+	}
+};
+/** Cost-line codes for the capitalized duties. Stable — a reversal matches on them. */
+const IMPORT_DUTY_CODES = {
+	customsDuty: "CUSTOMS_DUTY",
+	regulatoryDuty: "REGULATORY_DUTY",
+	supplementaryDuty: "SUPPLEMENTARY_DUTY"
+};
+/**
+* The clearance is identified by the purchase AND the Bill of Entry number.
+*
+* Deterministic, never random: a random fallback defeats deduplication while
+* looking correctly wired. One purchase can legitimately clear under more than
+* one BoE (a split consignment), so the purchase alone is too coarse; the BoE
+* alone is too coarse across purchases.
+*/
+function importClearanceKey(purchaseId, billOfEntryNumber) {
+	return `import-clearance:${purchaseId}:${billOfEntryNumber.trim().toUpperCase()}`;
+}
+/**
+* Every amount the assessment must agree on before anything is written.
+*
+* The calculator is a port, so this action cannot assume it is the verified
+* BD implementation — a host could wire a stub, a spreadsheet export, or a
+* second jurisdiction's pack. An internally inconsistent cascade would post a
+* balanced journal entry with the wrong split, which is unobservable
+* downstream, so the arithmetic is checked HERE rather than trusted.
+*/
+function assertCoherent(a, duties) {
+	const negatives = Object.entries(a).filter(([, v]) => typeof v === "number" && v < 0);
+	if (negatives.length > 0) throw new ImportClearanceError("INVALID_ASSESSMENT", `Assessment returned negative amounts: ${negatives.map(([k, v]) => `${k}=${v}`).join(", ")}.`);
+	const expectedBase = a.assessableValue + duties;
+	if (a.vatAtBase !== expectedBase) throw new ImportClearanceError("INVALID_ASSESSMENT", `vatAtBase ${a.vatAtBase} != assessableValue + duties ${expectedBase}. VAT and AT are assessed on the duty-inclusive value; a disagreeing base means the cascade was not applied in order.`);
+	const expectedTotal = duties + a.vat + a.advanceTax + a.advanceIncomeTax;
+	if (a.totalCustomsPayment !== expectedTotal) throw new ImportClearanceError("INVALID_ASSESSMENT", `totalCustomsPayment ${a.totalCustomsPayment} != duties + VAT + AT + AIT ${expectedTotal}. The goods value is paid to the supplier, never at customs, so it must not be in this total.`);
+	if (a.landedInventoryCost !== a.assessableValue + duties) throw new ImportClearanceError("INVALID_ASSESSMENT", `landedInventoryCost ${a.landedInventoryCost} != assessableValue + duties ${a.assessableValue + duties}.`);
+}
+function createPurchaseImportClearance(deps) {
+	const { order: orderPort, duty, landedCost, recordCustoms, receipt, withTransaction } = deps;
+	return async function clearImport(command) {
+		const { purchaseId, billOfEntry } = command;
+		const boeNumber = billOfEntry.number.trim();
+		if (!boeNumber) throw new ImportClearanceError("INVALID_ASSESSMENT", "Bill of Entry number is required.");
+		if (!Number.isInteger(billOfEntry.assessableValue) || billOfEntry.assessableValue < 0) throw new ImportClearanceError("INVALID_ASSESSMENT", `assessableValue must be a non-negative integer in minor units, received ${billOfEntry.assessableValue}. A major-unit value here would under-assess the whole cascade by the minor-unit factor.`);
+		return withTransaction(async (session) => {
+			const order = await orderPort.load(purchaseId, session);
+			if (!order) throw new ImportClearanceError("PURCHASE_NOT_FOUND", `Purchase ${purchaseId} not found.`);
+			/**
+			* Only an import clears customs. Refusing here rather than recording a
+			* zero-duty clearance keeps the two tax treatments from quietly
+			* converging: a domestic purchase with a Bill of Entry means one of the
+			* two documents is wrong, and guessing which one is not this action's
+			* call.
+			*/
+			if (order.taxTreatment !== "import") throw new ImportClearanceError("NOT_AN_IMPORT", `Purchase ${purchaseId} has taxTreatment '${order.taxTreatment ?? "domestic"}'. A Bill of Entry applies only to an import; set the treatment on the order first if it was misfiled.`);
+			/**
+			* Pre-flight only — the real guard is the CAS in `markCleared` below.
+			* This exists so the ordinary case (an operator re-submitting a form)
+			* gets a message naming the existing Bill of Entry, rather than a
+			* lost-race error for a race it never entered.
+			*/
+			if (order.alreadyClearedUnder) throw new ImportClearanceError("ALREADY_CLEARED", `Purchase ${purchaseId} is already cleared under Bill of Entry ${order.alreadyClearedUnder}.`);
+			/**
+			* Duties capitalize into the RECEIVED stock, so there must be some. A
+			* clearance before receipt is refused rather than parked: customs
+			* release the goods, so a Bill of Entry with nothing received means the
+			* receipt was missed, and allocating across zero lines would silently
+			* capitalize nothing while reporting success.
+			*/
+			const received = await receipt.getReceived(purchaseId, session);
+			if (!received || received.pickingIds.length === 0) throw new ImportClearanceError("NOT_RECEIVED", `Purchase ${purchaseId} has no receipt to allocate duties across. Customs release the goods, so record the receipt before the clearance.`);
+			const assessment = duty.assess({
+				assessableValue: billOfEntry.assessableValue,
+				...billOfEntry.rates
+			});
+			const dutiesCapitalized = assessment.customsDuty + assessment.regulatoryDuty + assessment.supplementaryDuty;
+			assertCoherent(assessment, dutiesCapitalized);
+			/**
+			* CLAIM BEFORE POSTING, and the ordering is deliberate.
+			*
+			* Claiming first means a crash between the claim and the postings
+			* leaves an order stamped as cleared with nothing posted — an operator
+			* has to reverse and re-enter. Posting first would mean a crash leaves
+			* the postings with no stamp, and the retry re-runs them: the customs
+			* recording port is idempotent on its key, but the landed-cost
+			* document is not, so the duties would capitalize twice.
+			*
+			* The asymmetry decides it. A blocked re-entry is a support ticket; a
+			* doubled customs posting is real money in the wrong place, found at
+			* filing. Inside a transaction both halves roll back together and the
+			* question is moot; on a deployment without sessions this is the safe
+			* failure.
+			*/
+			const { claimed } = await orderPort.markCleared({
+				purchaseId,
+				billOfEntryNumber: boeNumber,
+				billOfEntryDate: billOfEntry.date,
+				assessedValue: assessment.assessableValue,
+				totalCustomsPayment: assessment.totalCustomsPayment,
+				actorId: command.actorId,
+				session
+			});
+			if (!claimed) throw new ImportClearanceError("ALREADY_CLEARED", `Purchase ${purchaseId} was cleared concurrently by another request. Nothing was posted by this one.`);
+			/**
+			* DUTIES ONLY. Not `landedInventoryCost` — that includes the assessable
+			* value, which the receipt already booked. Zero-amount components are
+			* dropped so a nil-rated duty does not create an allocation row that a
+			* reversal then has to reconcile.
+			*/
+			const costLines = [
+				{
+					code: IMPORT_DUTY_CODES.customsDuty,
+					amount: assessment.customsDuty
+				},
+				{
+					code: IMPORT_DUTY_CODES.regulatoryDuty,
+					amount: assessment.regulatoryDuty
+				},
+				{
+					code: IMPORT_DUTY_CODES.supplementaryDuty,
+					amount: assessment.supplementaryDuty
+				}
+			].filter((line) => line.amount > 0).map((line) => ({
+				...line,
+				note: `BoE ${boeNumber}`
+			}));
+			const { landedCostId } = costLines.length > 0 ? await landedCost.applyDuties({
+				purchaseId,
+				pickingIds: received.pickingIds,
+				reference: `BoE ${boeNumber}`,
+				costLines,
+				session
+			}) : { landedCostId: "" };
+			const { postingRef } = await recordCustoms.record({
+				purchaseId,
+				billOfEntryNumber: boeNumber,
+				billOfEntryDate: billOfEntry.date,
+				assessableValue: billOfEntry.assessableValue,
+				rates: billOfEntry.rates,
+				vat: assessment.vat,
+				advanceTax: assessment.advanceTax,
+				advanceIncomeTax: assessment.advanceIncomeTax,
+				dutiesCapitalized,
+				totalCustomsPayment: assessment.totalCustomsPayment,
+				vatAtBase: assessment.vatAtBase,
+				idempotencyKey: importClearanceKey(purchaseId, boeNumber),
+				session
+			});
+			return {
+				purchaseId,
+				billOfEntryNumber: boeNumber,
+				assessment,
+				landedCostId,
+				postingRef,
+				dutiesCapitalized,
+				valuationVariance: assessment.assessableValue - received.bookedCost
+			};
+		}, { onCommit: async () => {} });
+	};
+}
+function createClearImportActionHandler(deps) {
+	const { build, actorId, errors } = deps;
+	return async function clearImportHandler(id, data, req) {
+		const body = data ?? {};
+		if (!body.billOfEntryNumber || !body.billOfEntryDate || body.assessableValue === void 0) throw errors.validation("billOfEntryNumber, billOfEntryDate and assessableValue (integer minor units) are required.");
+		const rates = body.rates ?? {};
+		if (typeof rates.cdRate !== "number") throw errors.validation("rates.cdRate is required (percent). A Bill of Entry always states the customs duty rate — 0 is a valid value for exempt goods, absence is not.");
+		try {
+			return await build(req)({
+				purchaseId: id,
+				billOfEntry: {
+					number: body.billOfEntryNumber,
+					date: new Date(body.billOfEntryDate),
+					assessableValue: body.assessableValue,
+					rates: {
+						cdRate: rates.cdRate,
+						...rates.rdRate !== void 0 ? { rdRate: rates.rdRate } : {},
+						...rates.sdRate !== void 0 ? { sdRate: rates.sdRate } : {},
+						...rates.atRate !== void 0 ? { atRate: rates.atRate } : {},
+						...rates.vatRate !== void 0 ? { vatRate: rates.vatRate } : {},
+						...rates.aitRate !== void 0 ? { aitRate: rates.aitRate } : {}
+					}
+				},
+				actorId: actorId(req)
+			});
+		} catch (err) {
+			if (err instanceof ImportClearanceError) {
+				if (err.code === "PURCHASE_NOT_FOUND") throw errors.notFound(err.message);
+				throw errors.domain(err.code, err.message, err.code === "ALREADY_CLEARED" ? 409 : 400);
+			}
+			throw err;
+		}
+	};
+}
+//#endregion
+export { IMPORT_DUTY_CODES, ImportClearanceError, createClearImportActionHandler, createPurchaseImportClearance, importClearanceKey };

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

@@ -0,0 +1,231 @@
+import { ClientSession } from "mongoose";
+//#region src/import/purchase-import.types.d.ts
+/**
+ * The customs cascade, as computed by the country pack.
+ *
+ * Structurally identical to `@classytic/bd-tax`'s `ImportTaxStack`, declared
+ * here so this package takes no country dependency. A host wires the two
+ * together; a second jurisdiction supplies its own calculator against the
+ * same shape.
+ *
+ * Every amount is integer MINOR units, matching the rest of this package.
+ */
+interface ImportDutyAssessment {
+  /** Customs-assessed value of the goods (CIF + landing charge). */
+  assessableValue: number;
+  customsDuty: number;
+  regulatoryDuty: number;
+  supplementaryDuty: number;
+  /** VAT prepayment. NOT input VAT — see the module docblock. */
+  advanceTax: number;
+  /** Reclaimable import VAT. */
+  vat: number;
+  /** The base VAT and AT were computed on (AV + CD + RD + SD). */
+  vatAtBase: number;
+  advanceIncomeTax: number;
+  /** AV + CD + RD + SD. Includes the goods; see the double-count note. */
+  landedInventoryCost: number;
+  /** What is actually paid at the customs point. Excludes the goods value. */
+  totalCustomsPayment: number;
+}
+/** Rates as declared on the Bill of Entry. Percentages, not fractions. */
+interface ImportDutyRates {
+  cdRate: number;
+  rdRate?: number | undefined;
+  sdRate?: number | undefined;
+  /**
+   * Commercial importers and manufacturers importing their own raw materials
+   * attract different Advance Tax rates, and some items are exempt. Left
+   * undefined the country pack applies its own default — which is a rate, not
+   * a zero.
+   */
+  atRate?: number | undefined;
+  vatRate?: number | undefined;
+  aitRate?: number | undefined;
+}
+/**
+ * Computes the cascade. REQUIRED, never defaulted.
+ *
+ * A default calculator would have to invent a jurisdiction's duty structure,
+ * and the result would be a filing-grade number with no basis. The same rule
+ * the payment application applies to tax attribution: attributing something
+ * plausible is worse than refusing, because nothing downstream can tell the
+ * difference.
+ */
+interface ImportDutyCalculator {
+  assess(input: ImportDutyRates & {
+    assessableValue: number;
+  }): ImportDutyAssessment;
+}
+/**
+ * Capitalizes the duty increment across the receipt's lines.
+ *
+ * Deliberately the EXISTING landed-cost machinery rather than a second
+ * allocator: it already owns per-line allocation by value/quantity/weight,
+ * FX-stamped cost lines, persisted allocations so a reversal undoes the exact
+ * same split, and the accounting bridge that capitalizes into inventory. A
+ * bespoke allocator here would be a second implementation of a solved problem
+ * and would drift from the one `reverse()` understands.
+ */
+interface ImportLandedCostPort {
+  /**
+   * @param costLines Duty components only. The port must NOT be handed the
+   *   assessable value — see the double-count note in the module docblock.
+   * @returns The applied landed-cost document id, for provenance.
+   */
+  applyDuties(input: {
+    purchaseId: string;
+    /** Receipt/picking refs the duties allocate across. */
+    pickingIds: readonly string[];
+    reference: string;
+    costLines: readonly {
+      code: string;
+      amount: number;
+      note?: string;
+    }[];
+    session: ClientSession | null;
+  }): Promise<{
+    landedCostId: string;
+  }>;
+}
+/**
+ * Posts the three NON-inventory legs and the customs credit.
+ *
+ * Kept as a port for the same reason `PurchasePaymentRecordingPort` is: the
+ * chart of accounts, the tax regime's eligibility rules, and whether a
+ * clearance is paid from a bank or accrued to a C&F agent are all deployment
+ * facts. The package owns which amounts go where CONCEPTUALLY; the host owns
+ * the account codes.
+ */
+interface ImportCustomsRecordingPort {
+  record(input: {
+    purchaseId: string;
+    billOfEntryNumber: string;
+    billOfEntryDate: Date;
+    /**
+     * The declared assessment inputs, alongside the computed amounts. A
+     * recording implementation built on a posting RECIPE re-derives the
+     * cascade from these through the same country pack — carrying them means
+     * the recipe and the action cannot be fed different facts.
+     */
+    assessableValue: number;
+    rates: ImportDutyRates;
+    /** Reclaimable input VAT. */
+    vat: number;
+    /** VAT prepayment — a distinct account from input VAT. */
+    advanceTax: number;
+    /** Income-tax asset. */
+    advanceIncomeTax: number;
+    /** Duties capitalized via the landed-cost port. Credited, not debited. */
+    dutiesCapitalized: number;
+    /** Must equal duties + vat + advanceTax + advanceIncomeTax. */
+    totalCustomsPayment: number;
+    /** The base VAT was computed on — a ledger-derived return needs it. */
+    vatAtBase: number;
+    /** Deterministic; the same clearance recorded twice is one posting. */
+    idempotencyKey: string;
+    session: ClientSession | null;
+  }): Promise<{
+    postingRef: string;
+  }>;
+}
+/** What the receipt already booked, so the assessed value can be reconciled. */
+interface ImportReceiptLookup {
+  /**
+   * @returns The picking refs and the cost the receipt booked (integer minor
+   *   units), or null when the purchase has not been received. A clearance
+   *   before receipt is refused rather than queued — customs release the
+   *   goods, so a Bill of Entry without a receipt means the two documents
+   *   disagree about reality.
+   */
+  getReceived(purchaseId: string, session: ClientSession | null): Promise<{
+    pickingIds: readonly string[];
+    bookedCost: number;
+  } | null>;
+}
+interface PurchaseUnitOfWork {
+  <T>(work: (session: ClientSession | null) => Promise<T>, options: {
+    onCommit: (result: T) => Promise<void>;
+  }): Promise<T>;
+}
+interface PurchaseImportApplicationDeps {
+  order: ImportClearancePort;
+  duty: ImportDutyCalculator;
+  landedCost: ImportLandedCostPort;
+  recordCustoms: ImportCustomsRecordingPort;
+  receipt: ImportReceiptLookup;
+  withTransaction: PurchaseUnitOfWork;
+}
+/**
+ * Reads the order's tax treatment and CLAIMS the clearance.
+ *
+ * A port rather than an engine handle because this deployment has two purchase
+ * documents — flow's procurement order (what the warehouse UI raises) and
+ * `@classytic/purchase`'s GR/IR order — and an import can arrive on either.
+ * Binding to one engine's repository shape would have silently restricted the
+ * action to that path while type-checking perfectly against it.
+ */
+interface ImportClearancePort {
+  load(purchaseId: string, session: ClientSession | null): Promise<{
+    taxTreatment?: 'domestic' | 'import' | undefined;
+    /** The BoE this order was already cleared under, when it was. */
+    alreadyClearedUnder?: string | undefined;
+  } | null>;
+  /**
+   * Stamp the clearance, returning whether THIS caller won.
+   *
+   * Must be a compare-and-set in the query FILTER — `{ _id, importClearance:
+   * { $exists: false } }` — not a read followed by a write. The `load` check
+   * above is a pre-flight for a friendly error message, not the guard: two
+   * concurrent clearances both pass it, and the loser must be told it lost
+   * rather than post a second customs entry.
+   *
+   * @returns `claimed: false` when another clearance won the race.
+   */
+  markCleared(input: {
+    purchaseId: string;
+    billOfEntryNumber: string;
+    billOfEntryDate: Date;
+    assessedValue: number;
+    totalCustomsPayment: number;
+    actorId?: string | undefined;
+    session: ClientSession | null;
+  }): Promise<{
+    claimed: boolean;
+  }>;
+}
+interface ClearImportCommand {
+  purchaseId: string;
+  billOfEntry: {
+    /** The BoE number. Part of the idempotency identity. */
+    number: string;
+    /** Clearance date — the date the assessment is effective on. */
+    date: Date;
+    /**
+     * Customs-assessed value in integer MINOR units. Supplied, never derived
+     * from the PO: customs assess on their own valuation and the difference
+     * from the invoice is the thing worth seeing.
+     */
+    assessableValue: number;
+    rates: ImportDutyRates;
+  };
+  actorId?: string | undefined;
+}
+interface ClearImportResult {
+  purchaseId: string;
+  billOfEntryNumber: string;
+  assessment: ImportDutyAssessment;
+  landedCostId: string;
+  postingRef: string;
+  /** CD + RD + SD — what was capitalized. */
+  dutiesCapitalized: number;
+  /**
+   * Assessed value minus what the receipt booked. Non-zero is NORMAL (customs
+   * assess CIF plus a landing charge; the receipt booked the invoice), and it
+   * is surfaced rather than absorbed so an operator can see valuation drift
+   * instead of discovering it in a stock-vs-ledger reconciliation.
+   */
+  valuationVariance: number;
+}
+//#endregion
+export { ClearImportCommand, ClearImportResult, ImportClearancePort, ImportCustomsRecordingPort, ImportDutyAssessment, ImportDutyCalculator, ImportDutyRates, ImportLandedCostPort, ImportReceiptLookup, PurchaseImportApplicationDeps, PurchaseUnitOfWork };

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

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

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

@@ -64,7 +64,7 @@ async receive({ purchase, supplierName }) {
 				resolved.push({
 					productId,
 					variantSku,
-					skuRef: deps.skuRef(productId, variantSku),
+					skuRef: await deps.skuRef(productId, variantSku),
 					quantity: Number(item.quantity ?? 0),
 					costMinor: Number(item.costPrice ?? 0),
 					destinationLocationCode

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

@@ -147,8 +147,15 @@ interface PurchaseStockReceiptDeps<TCtx extends PurchaseReceiptScope = PurchaseR
    * 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;
+  /**
+   * The host's `productId` (+ variant) -> `skuRef` resolution.
+   *
+   * May be async: the correct key is the variant's STAMPED `skuRef` (ADR
+   * `spine/docs/stock-identity-and-product-variants.md`), which lives on the
+   * product DOC — a host resolving it must be allowed a read. A sync legacy
+   * derivation remains assignable, so no existing host breaks.
+   */
+  skuRef(productId: string, variantSku: string | null): string | Promise<string>;
   /** Counterparty location goods arrive FROM — unbounded by design. */
   vendorLocationId: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spinekit/purchase",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Arc module for @classytic/purchase — supplier purchase orders (draft→approve→receive with CAS + compensation + pendingStockReceipt crash heal) composed into arc apps. Paisa money wire; catalog/stockReceipt/sequence kernel ports injected; accounting posting + approval stay host seams.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -66,6 +66,14 @@
     "./resources/supplier/types": {
       "types": "./dist/resources/supplier/supplier.types.d.mts",
       "default": "./dist/resources/supplier/supplier.types.mjs"
+    },
+    "./import": {
+      "types": "./dist/import/purchase-import.application.d.mts",
+      "default": "./dist/import/purchase-import.application.mjs"
+    },
+    "./import/types": {
+      "types": "./dist/import/purchase-import.types.d.mts",
+      "default": "./dist/import/purchase-import.types.mjs"
     }
   },
   "files": [
@@ -97,7 +105,7 @@
     "typescript": "^7.0.2",
     "vitest": "^3.2.4",
     "zod": "^4.3.6",
-    "@spinekit/kit": "0.1.0"
+    "@spinekit/kit": "0.2.0"
   },
   "author": "Classytic",
   "homepage": "https://www.npmjs.com/package/@spinekit/purchase",