@spinekit/promo 0.1.0

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,52 @@
+# @spinekit/promo
+
+> Promotions — programs, vouchers, rules, rewards, and cart evaluation — as composable arc resources.
+
+Part of **Spine**, Classytic's ERP — the arc-module layer that composes the
+framework-agnostic `@classytic/promo` kernel into an [`@classytic/arc`](https://www.npmjs.com/package/@classytic/arc)
+application via `createApp({ modules })`.
+
+## Install
+
+```sh
+npm install @spinekit/promo @classytic/promo @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 { createPromoModule } from '@spinekit/promo';
+import { createPromoEngine } from '@classytic/promo';
+
+const engine = createPromoEngine({ mongoose: connection, tenant: false });
+const app = await createApp({
+  modules: [
+    createPromoModule({
+      engine,                        // BYO — carries tenancy + event transport
+      permissions,                   // granular gates per entity (see PromoPermissions)
+      // resolveActor, prefixes, extraRoutes as needed
+    }),
+  ],
+});
+```
+
+Mounts `/promotions/{programs,vouchers,rules,rewards,evaluate}` — adapter CRUD,
+Stripe-pattern FSM actions (activate/pause/archive, cancel, commit/rollback),
+code-centric voucher routes, and preview/evaluate.
+
+**Company-wide by default** (`tenantField: false`): in a single-tenant
+multi-branch deployment, a voucher generated at one branch redeems at any
+other. **Wire-error contract included**: the kernel's hierarchical codes map to
+stable UPPER_SNAKE codes + HTTP statuses (`PROMO_CODE_TO_WIRE`) so every host
+serves the identical public contract.
+
+The engine is exported at `fastify.arc.modules.promo` — order-placement
+choreography (reserve → commit/rollback) stays host policy over that export.
+
+## License
+
+MIT © Classytic

package/dist/errors.d.mts

@@ -0,0 +1,35 @@
+import { ErrorMapper } from "@classytic/arc/plugins";
+import { FastifyReply, FastifyRequest } from "fastify";
+//#region src/errors.d.ts
+declare const PROMO_CODE_TO_WIRE: Record<string, string>;
+/** Fallback status for legacy/unmapped codes arriving without HttpError.status. */
+declare function statusForCode(code: string | undefined): number;
+/** Normalise a thrown promo error into the stable wire `{ code, statusCode }`. */
+declare function toWireError(err: unknown): {
+  code: string;
+  statusCode: number;
+};
+/**
+ * Wrap a raw promo route: domain errors map to the wire contract; anything
+ * not already an ArcError becomes one so handleRaw's envelope stays clean.
+ */
+declare function promoRoute<T>(fn: (req: FastifyRequest, reply: FastifyReply) => Promise<T>, statusCode?: number): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+/** Same mapping shaped for arc's declarative `actions:` handlers. */
+declare function promoAction<T>(fn: (id: string, data: Record<string, unknown>, req: FastifyRequest) => Promise<T>): (id: string, data: Record<string, unknown>, req: FastifyRequest) => Promise<T>;
+/**
+ * The kernel→wire error contract, registered on the module so EVERY path
+ * serves it — not only handlers wrapped in `promoRoute`/`promoAction`.
+ *
+ * A `PromoError` raised outside a wrapper (controller override, host action,
+ * evaluation bridge) previously reached the wire with the kernel's RAW code
+ * instead of the public alias in {@link PROMO_CODE_TO_WIRE}, so the same
+ * failure answered with two different codes depending on the path that raised
+ * it. Registering the base class fixes that everywhere, and a host can no
+ * longer mount promo and forget to wire the table.
+ *
+ * Arc dispatches by `instanceof` and every kernel error extends `PromoError`,
+ * so ONE mapper covers the whole family — including classes added later.
+ */
+declare const promoErrorMappers: ErrorMapper[];
+//#endregion
+export { PROMO_CODE_TO_WIRE, promoAction, promoErrorMappers, promoRoute, statusForCode, toWireError };

package/dist/errors.mjs

@@ -0,0 +1,121 @@
+import { PromoError } from "@classytic/promo";
+import { ArcError, defineErrorMapper, handleRaw } from "@classytic/arc/utils";
+//#region src/errors.ts
+/**
+* Promo kernel ↔ wire error contract.
+*
+* `@classytic/promo` 0.4+ throws hierarchical lowercase codes
+* (`promo.<entity>.<problem>`) carrying an authoritative HttpError `status`.
+* The public wire contract (SDK + clients) discriminates on stable
+* UPPER_SNAKE codes — this table is that mapping, owned by the MODULE so
+* every host serves the identical contract (lifted at parity from be-prod).
+*/
+const PROMO_CODE_TO_WIRE = {
+	"promo.program.not_found": "PROGRAM_NOT_FOUND",
+	"promo.voucher.not_found": "VOUCHER_NOT_FOUND",
+	"promo.evaluation.not_found": "EVALUATION_NOT_FOUND",
+	"promo.rule.not_found": "RULE_NOT_FOUND",
+	"promo.reward.not_found": "REWARD_NOT_FOUND",
+	"promo.program.invalid_transition": "INVALID_TRANSITION",
+	"promo.voucher.expired": "VOUCHER_EXPIRED",
+	"promo.voucher.exhausted": "VOUCHER_EXHAUSTED",
+	"promo.gift_card.insufficient_balance": "INSUFFICIENT_BALANCE",
+	"promo.gift_card.exhausted": "INSUFFICIENT_BALANCE",
+	"promo.validation.invalid_input": "VALIDATION_ERROR",
+	"promo.voucher.duplicate_redemption": "DUPLICATE_REDEMPTION",
+	"promo.voucher.duplicate_code": "DUPLICATE_CODE",
+	"promo.program.usage_cap_exceeded": "PROGRAM_USAGE_CAP_EXCEEDED",
+	"promo.evaluation.cart_hash_mismatch": "CART_HASH_MISMATCH",
+	"promo.tenant.missing_context": "TENANT_ISOLATION",
+	"promo.concurrency.write_conflict": "WRITE_CONFLICT",
+	"promo.engine.model_collision": "MODEL_COLLISION"
+};
+/** Fallback status for legacy/unmapped codes arriving without HttpError.status. */
+function statusForCode(code) {
+	switch (code) {
+		case "PROGRAM_NOT_FOUND":
+		case "VOUCHER_NOT_FOUND":
+		case "EVALUATION_NOT_FOUND":
+		case "RULE_NOT_FOUND":
+		case "REWARD_NOT_FOUND": return 404;
+		case "INVALID_TRANSITION": return 422;
+		case "VOUCHER_EXPIRED":
+		case "VOUCHER_EXHAUSTED": return 410;
+		case "DUPLICATE_REDEMPTION":
+		case "DUPLICATE_CODE":
+		case "CART_HASH_MISMATCH":
+		case "PROGRAM_USAGE_CAP_EXCEEDED":
+		case "WRITE_CONFLICT": return 409;
+		case "TENANT_ISOLATION": return 403;
+		default: return 400;
+	}
+}
+/** Normalise a thrown promo error into the stable wire `{ code, statusCode }`. */
+function toWireError(err) {
+	const e = err;
+	const wireCode = (e.code && PROMO_CODE_TO_WIRE[e.code]) ?? e.code ?? "PROMO_ERROR";
+	return {
+		code: wireCode,
+		statusCode: e.status ?? e.statusCode ?? statusForCode(wireCode)
+	};
+}
+/**
+* Wrap a raw promo route: domain errors map to the wire contract; anything
+* not already an ArcError becomes one so handleRaw's envelope stays clean.
+*/
+function promoRoute(fn, statusCode = 200) {
+	return handleRaw(async (req, reply) => {
+		try {
+			return await fn(req, reply);
+		} catch (err) {
+			if (err instanceof ArcError) throw err;
+			const { code, statusCode: status } = toWireError(err);
+			throw new ArcError(err.message, {
+				code,
+				statusCode: status
+			});
+		}
+	}, statusCode);
+}
+/** Same mapping shaped for arc's declarative `actions:` handlers. */
+function promoAction(fn) {
+	return async (id, data, req) => {
+		try {
+			return await fn(id, data, req);
+		} catch (err) {
+			if (err instanceof ArcError) throw err;
+			const { code, statusCode } = toWireError(err);
+			throw new ArcError(err.message, {
+				code,
+				statusCode
+			});
+		}
+	};
+}
+/**
+* The kernel→wire error contract, registered on the module so EVERY path
+* serves it — not only handlers wrapped in `promoRoute`/`promoAction`.
+*
+* A `PromoError` raised outside a wrapper (controller override, host action,
+* evaluation bridge) previously reached the wire with the kernel's RAW code
+* instead of the public alias in {@link PROMO_CODE_TO_WIRE}, so the same
+* failure answered with two different codes depending on the path that raised
+* it. Registering the base class fixes that everywhere, and a host can no
+* longer mount promo and forget to wire the table.
+*
+* Arc dispatches by `instanceof` and every kernel error extends `PromoError`,
+* so ONE mapper covers the whole family — including classes added later.
+*/
+const promoErrorMappers = [defineErrorMapper({
+	type: PromoError,
+	toResponse: (error) => {
+		const { code, statusCode } = toWireError(error);
+		return {
+			status: statusCode,
+			code,
+			message: error.message
+		};
+	}
+})];
+//#endregion
+export { PROMO_CODE_TO_WIRE, promoAction, promoErrorMappers, promoRoute, statusForCode, toWireError };

package/dist/index.d.mts

@@ -0,0 +1,6 @@
+import { a as PromoPermissions, i as PromoModuleDeps, n as PromoActorCtx, r as PromoEngineLike, t as CrudGates } from "./types-D07igQha.mjs";
+import { PromoFactoryCtx } from "./resources.mjs";
+//#region src/module.d.ts
+declare function createPromoModule<TEngine extends PromoEngineLike>(deps: PromoModuleDeps<TEngine>): import("@classytic/arc/factory").ArcModule<unknown>;
+//#endregion
+export { type CrudGates, type PromoActorCtx, type PromoEngineLike, type PromoFactoryCtx, type PromoModuleDeps, type PromoPermissions, createPromoModule };

package/dist/index.mjs

@@ -0,0 +1,76 @@
+import { promoErrorMappers } from "./errors.mjs";
+import { buildFactoryCtx, createEvaluationResource, createProgramResource, createRewardResource, createRuleResource, createVoucherResource } from "./resources.mjs";
+import { definePromo } from "@classytic/promo";
+import { defineEngineModule } from "@spinekit/kit/engine-module";
+//#region src/module.ts
+/**
+* `createPromoModule` — @spinekit/promo's single composition surface.
+*
+* ```ts
+* const promoModule = createPromoModule({
+*   engine: ensurePromoEngine(),          // BYO — carries tenancy + transport
+*   permissions: appPermissions.promotions,
+* });
+* createApp({ modules: [promoModule] });
+* ```
+*
+* Bootstrap RETURNS the engine → recorded at `fastify.arc.modules.promo`
+* (layer-2 module export) for cross-module wiring (order placement's
+* reserve/commit/rollback choreography reads it — that orchestration itself
+* stays HOST policy; see be-prod's promo-placement.ts).
+*
+* Composed over `defineEngineModule` (`@spinekit/kit/engine-module`) — the ONE
+* primitive for mounting a kernel engine as an arc module. This file used to
+* spell the four-piece dance (`deferredEngine` + `defineSpineModule` +
+* bootstrap/closeOwned threading) by hand; the primitive owns all of it —
+* BYO-vs-owned teardown, shared-slot fill/clear, in-flight-boot race guard,
+* and `owns` derivation from the resources arm — so only the promo-specific
+* pieces remain here.
+*/
+function createPromoModule(deps) {
+	const { module } = defineEngineModule({
+		name: "promo",
+		/**
+		* Module-OWNED when the host supplies `connection` + shape/runtime; BYO when it supplies
+		* `engine`. Both are accepted, and the difference is TEARDOWN: the primitive closes only what
+		* it allocated, so only the owned form can be reclaimed here. The BYO arm stays for hosts
+		* still mid-migration. A host passing a THUNK (`() => ensurePromoEngine()`) allocates nothing
+		* at compose — the five promo models register at `bootstrap` (post-connect), never while the
+		* graph is composed.
+		*/
+		...deps.engine !== void 0 ? { supplied: deps.engine } : {},
+		/**
+		* The host's slot, so a host can READ the engine (be-prod's promo.port.ts)
+		* while the module keeps ownership — filled at bootstrap, emptied at teardown.
+		*/
+		...deps.slot !== void 0 ? { slot: deps.slot } : {},
+		boot: () => {
+			const { connection, engineShape, engineRuntime } = deps;
+			if (!connection || !engineShape || !engineRuntime) throw new Error("createPromoModule needs either `engine` (BYO) or `connection` + `engineShape` + `engineRuntime` (module-owned). Supplying neither would allocate nothing and every promo route would read an empty slot at the first request.");
+			return definePromo(engineShape()).bind(connection, engineRuntime());
+		},
+		resources: (engine) => {
+			const fx = buildFactoryCtx(deps, engine);
+			return [
+				createProgramResource(fx),
+				createVoucherResource(fx),
+				createRuleResource(fx),
+				createRewardResource(fx),
+				createEvaluationResource(fx)
+			];
+		},
+		extend: () => ({
+			errorMappers: promoErrorMappers,
+			/**
+			* Host teardown COMPOSES with the owned engine close — `defineSpineModule`
+			* runs the host's `onClose` FIRST (it may drain work that still needs the
+			* engine), then the owned close. Same ordering the pre-migration config
+			* spread produced; nothing is silently replaced.
+			*/
+			...deps.onClose !== void 0 ? { onClose: deps.onClose } : {}
+		})
+	});
+	return module;
+}
+//#endregion
+export { createPromoModule };

package/dist/placement/promo-placement.d.mts

@@ -0,0 +1,147 @@
+import { r as PromoEngineLike } from "../types-D07igQha.mjs";
+import { EngineRef } from "@spinekit/kit/engine-slot";
+import { StructuredLogger } from "@classytic/primitives/context";
+//#region src/placement/promo-placement.d.ts
+/** Canonical line item shape for the promo engine. Matches `EvaluateInput.items`. */
+interface PromoLineItem {
+  productId: string;
+  sku: string;
+  quantity: number;
+  /** Minor units (e.g. paisa for BDT). */
+  unitPrice: number;
+  lineTotal: number;
+}
+interface ReservePromoInput {
+  /** Live engine or a thunk — resolved per call, never at module load. */
+  engine: EngineRef<PromoEngineLike>;
+  /** Uppercased promo codes submitted by the client. */
+  codes: string[] | undefined;
+  /** Order lines AFTER server-side catalog resolution — NOT client-claimed. */
+  lines: PromoLineItem[];
+  /** Subtotal in minor units, computed from `lines`. */
+  subtotal: number;
+  /** Optional customer ID — enables per-customer usage caps. */
+  customerId?: string;
+  /** Optional customer tags — enables tag-scoped programs. */
+  customerTags?: string[];
+  /** Actor performing the placement (user, cashier, or 'system'). */
+  actorId: string;
+  /** Branch organization ID (BA org) — carried for audit only; promos are company-wide. */
+  organizationId?: string;
+  /**
+   * Logger for structured error + audit reporting.
+   *
+   * Typed as the KERNEL's `StructuredLogger` rather than a local union. This
+   * declared `FastifyBaseLogger | Pick<Console, …>` on the assumption that the
+   * two were interchangeable; when `@classytic/promo` narrowed its own logger
+   * contract the assumption stopped holding, and the port that bridges them
+   * could no longer pass what it receives. Deriving from the callee's type is
+   * what keeps that from happening again — a hand-written structural copy
+   * stops matching silently.
+   */
+  logger?: StructuredLogger;
+}
+interface PromoReservation {
+  /**
+   * Evaluation ID returned by the engine when codes were supplied and
+   * matched a program. `undefined` when there are no codes or when every
+   * code was rejected (in which case the placement proceeds without
+   * discount — rejectedCodes can be surfaced back to the client).
+   */
+  evaluationId: string | undefined;
+  /** Total discount the engine computed, in minor units. */
+  totalDiscount: number;
+  /** Codes the engine actually applied. */
+  appliedCodes: string[];
+  /** Codes the engine rejected, with reason — useful for post-placement UX. */
+  rejectedCodes: Array<{
+    code: string;
+    reason: string;
+  }>;
+}
+interface PromoCommitResult {
+  /** True when an evaluation existed AND commit succeeded. */
+  committed: boolean;
+  /** True when there was no evaluation to commit (no codes / all rejected). */
+  skipped: boolean;
+  /** Engine error message if commit failed. Reservation is already rolled back. */
+  error?: string;
+  /** The discount locked to the order, in minor units. */
+  totalDiscount?: number;
+  /** Codes the engine applied — echoed for client display. */
+  appliedCodes?: string[];
+  /** Codes the engine rejected — echoed for client display. */
+  rejectedCodes?: Array<{
+    code: string;
+    reason: string;
+  }>;
+}
+/** Canonical line builder for placement pipelines — see `placement.service.ts`. */
+declare function buildPromoLines(resolvedLines: Array<{
+  skuRef: string;
+  quantity: number;
+  snapshot: {
+    productId?: string;
+    unitPrice?: number;
+  } | undefined;
+}>): PromoLineItem[];
+/** Subtotal from canonical lines — always drives the engine input. */
+declare function computePromoSubtotal(lines: PromoLineItem[]): number;
+/**
+ * Reserve a promo evaluation for an order-in-flight.
+ *
+ * Returns an empty reservation (`evaluationId: undefined`) when:
+ *   - The client submitted no codes.
+ *   - The client submitted codes but every one was rejected.
+ *
+ * In both cases `rejectedCodes` still lists what failed so the caller can
+ * echo it back to the client without any additional engine round-trip.
+ */
+declare function reservePromo(input: ReservePromoInput): Promise<PromoReservation>;
+/**
+ * Commit a reserved evaluation to an order. Idempotent for empty
+ * reservations. On commit failure (voucher exhausted between evaluate and
+ * commit, engine error), automatically rolls back the reservation so no
+ * drift is left behind.
+ */
+declare function commitPromo(reservation: PromoReservation, orderId: string, input: {
+  engine: EngineRef<PromoEngineLike>;
+  actorId: string;
+  organizationId?: string;
+  logger?: ReservePromoInput['logger'];
+}): Promise<PromoCommitResult>;
+/**
+ * Release a reservation. Call when the surrounding pipeline fails AFTER
+ * `reservePromo` but BEFORE `commitPromo` (e.g. order insert throws).
+ * Idempotent — safe to call even if the reservation is already gone.
+ */
+declare function rollbackPromo(reservation: PromoReservation, input: {
+  engine: EngineRef<PromoEngineLike>;
+  actorId: string;
+  organizationId?: string;
+  logger?: ReservePromoInput['logger'];
+}): Promise<void>;
+/**
+ * Bind the placement verbs to one engine.
+ *
+ * The functions above stay individually exported and engine-parameterised so they remain
+ * directly testable; this is the convenience a composer wants — bind once, call three
+ * times, no chance of two call sites disagreeing about which engine they meant.
+ */
+declare function createPromoPlacement(deps: {
+  engine: EngineRef<PromoEngineLike>;
+}): {
+  reservePromo: (input: Omit<ReservePromoInput, 'engine'>) => Promise<PromoReservation>;
+  commitPromo: (reservation: PromoReservation, orderId: string, input: {
+    actorId: string;
+    organizationId?: string;
+    logger?: ReservePromoInput['logger'];
+  }) => Promise<PromoCommitResult>;
+  rollbackPromo: (reservation: PromoReservation, input: {
+    actorId: string;
+    organizationId?: string;
+    logger?: ReservePromoInput['logger'];
+  }) => Promise<void>;
+};
+//#endregion
+export { PromoCommitResult, PromoLineItem, PromoReservation, ReservePromoInput, buildPromoLines, commitPromo, computePromoSubtotal, createPromoPlacement, reservePromo, rollbackPromo };

package/dist/placement/promo-placement.mjs

@@ -0,0 +1,198 @@
+import { resolveEngineRef } from "@spinekit/kit/engine-slot";
+//#region src/placement/promo-placement.ts
+const LOG_PREFIX = "[promo-placement]";
+const SYSTEM_ACTOR_ID = "system";
+const resolveActorId = (actorId) => actorId && actorId.trim().length > 0 ? actorId : SYSTEM_ACTOR_ID;
+/**
+* Build the promo engine context.
+*
+* Promos are company-wide (see `promo.resources.ts` and the `tenant: false`
+* engine boot). Passing `organizationId` would make the repos inject a
+* per-branch filter on reads — programs seeded at company level would
+* become invisible to branch-scoped calls.
+*
+* The `organizationId` arriving into these helpers is carried only for
+* audit logging (which branch triggered the commit), never forwarded to
+* the engine itself.
+*/
+const buildCtx = (input) => ({ actorRef: input.actorId });
+/** Canonical line builder for placement pipelines — see `placement.service.ts`. */
+function buildPromoLines(resolvedLines) {
+	return resolvedLines.map((line) => {
+		const unitPrice = line.snapshot?.unitPrice ?? 0;
+		return {
+			productId: line.snapshot?.productId ?? line.skuRef,
+			sku: line.skuRef,
+			quantity: line.quantity,
+			unitPrice,
+			lineTotal: unitPrice * line.quantity
+		};
+	});
+}
+/** Subtotal from canonical lines — always drives the engine input. */
+function computePromoSubtotal(lines) {
+	return lines.reduce((sum, l) => sum + l.lineTotal, 0);
+}
+/**
+* Reserve a promo evaluation for an order-in-flight.
+*
+* Returns an empty reservation (`evaluationId: undefined`) when:
+*   - The client submitted no codes.
+*   - The client submitted codes but every one was rejected.
+*
+* In both cases `rejectedCodes` still lists what failed so the caller can
+* echo it back to the client without any additional engine round-trip.
+*/
+async function reservePromo(input) {
+	const codes = (input.codes ?? []).map((c) => c.toUpperCase()).filter(Boolean);
+	if (codes.length === 0) return {
+		evaluationId: void 0,
+		totalDiscount: 0,
+		appliedCodes: [],
+		rejectedCodes: []
+	};
+	const actorId = resolveActorId(input.actorId);
+	const ctx = buildCtx({ actorId });
+	try {
+		const result = await (await resolveEngineRef(input.engine)).services.evaluation.evaluate({
+			items: input.lines,
+			subtotal: input.subtotal,
+			codes,
+			customerId: input.customerId,
+			customerTags: input.customerTags
+		}, ctx);
+		return {
+			evaluationId: result.appliedCodes.length > 0 && result.totalDiscount > 0 ? result.evaluationId : void 0,
+			totalDiscount: result.totalDiscount,
+			appliedCodes: result.appliedCodes,
+			rejectedCodes: result.rejectedCodes
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		input.logger?.warn?.({
+			err,
+			codes,
+			actorId,
+			organizationId: input.organizationId
+		}, `${LOG_PREFIX} reserve failed — continuing placement without discount`);
+		return {
+			evaluationId: void 0,
+			totalDiscount: 0,
+			appliedCodes: [],
+			rejectedCodes: codes.map((code) => ({
+				code,
+				reason: `Engine error: ${message}`
+			}))
+		};
+	}
+}
+/**
+* Commit a reserved evaluation to an order. Idempotent for empty
+* reservations. On commit failure (voucher exhausted between evaluate and
+* commit, engine error), automatically rolls back the reservation so no
+* drift is left behind.
+*/
+async function commitPromo(reservation, orderId, input) {
+	if (!reservation.evaluationId) return {
+		committed: false,
+		skipped: true,
+		totalDiscount: 0,
+		appliedCodes: reservation.appliedCodes,
+		rejectedCodes: reservation.rejectedCodes
+	};
+	const actorId = resolveActorId(input.actorId);
+	const ctx = buildCtx({ actorId });
+	const evaluationId = reservation.evaluationId;
+	try {
+		await (await resolveEngineRef(input.engine)).services.evaluation.commit(evaluationId, orderId, ctx);
+		input.logger?.info?.({
+			audit: true,
+			op: "promo.evaluation.commit",
+			evaluationId,
+			orderId,
+			actorId,
+			organizationId: input.organizationId,
+			totalDiscount: reservation.totalDiscount
+		}, `${LOG_PREFIX} committed`);
+		return {
+			committed: true,
+			skipped: false,
+			totalDiscount: reservation.totalDiscount,
+			appliedCodes: reservation.appliedCodes,
+			rejectedCodes: reservation.rejectedCodes
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		input.logger?.error?.({
+			err,
+			orderId,
+			evaluationId,
+			actorId,
+			organizationId: input.organizationId
+		}, `${LOG_PREFIX} commit failed — rolling back reservation`);
+		await rollbackPromo(reservation, {
+			...input,
+			actorId
+		}).catch(() => {});
+		return {
+			committed: false,
+			skipped: false,
+			error: message,
+			totalDiscount: 0,
+			appliedCodes: reservation.appliedCodes,
+			rejectedCodes: reservation.rejectedCodes
+		};
+	}
+}
+/**
+* Release a reservation. Call when the surrounding pipeline fails AFTER
+* `reservePromo` but BEFORE `commitPromo` (e.g. order insert throws).
+* Idempotent — safe to call even if the reservation is already gone.
+*/
+async function rollbackPromo(reservation, input) {
+	if (!reservation.evaluationId) return;
+	const actorId = resolveActorId(input.actorId);
+	const ctx = buildCtx({ actorId });
+	try {
+		await (await resolveEngineRef(input.engine)).services.evaluation.rollback(reservation.evaluationId, ctx);
+		input.logger?.info?.({
+			audit: true,
+			op: "promo.evaluation.rollback",
+			evaluationId: reservation.evaluationId,
+			actorId,
+			organizationId: input.organizationId
+		}, `${LOG_PREFIX} rolled back`);
+	} catch (err) {
+		input.logger?.warn?.({
+			err,
+			evaluationId: reservation.evaluationId,
+			actorId,
+			organizationId: input.organizationId
+		}, `${LOG_PREFIX} rollback failed — reservation will expire via TTL`);
+	}
+}
+/**
+* Bind the placement verbs to one engine.
+*
+* The functions above stay individually exported and engine-parameterised so they remain
+* directly testable; this is the convenience a composer wants — bind once, call three
+* times, no chance of two call sites disagreeing about which engine they meant.
+*/
+function createPromoPlacement(deps) {
+	return {
+		reservePromo: (input) => reservePromo({
+			...input,
+			engine: deps.engine
+		}),
+		commitPromo: (reservation, orderId, input) => commitPromo(reservation, orderId, {
+			...input,
+			engine: deps.engine
+		}),
+		rollbackPromo: (reservation, input) => rollbackPromo(reservation, {
+			...input,
+			engine: deps.engine
+		})
+	};
+}
+//#endregion
+export { buildPromoLines, commitPromo, computePromoSubtotal, createPromoPlacement, reservePromo, rollbackPromo };

package/dist/placement/promo.port.d.mts

@@ -0,0 +1,11 @@
+import { r as PromoEngineLike } from "../types-D07igQha.mjs";
+import { PromoPort } from "@classytic/promo";
+import { EngineRef } from "@spinekit/kit/engine-slot";
+//#region src/placement/promo.port.d.ts
+/** Build the port for one engine. A factory, not a frozen singleton — the singleton form
+ *  forced the placement verbs to resolve a module-global engine. */
+declare function createPromoPort(deps: {
+  engine: EngineRef<PromoEngineLike>;
+}): PromoPort;
+//#endregion
+export { createPromoPort };

package/dist/placement/promo.port.mjs

@@ -0,0 +1,31 @@
+import { createPromoPlacement } from "./promo-placement.mjs";
+//#region src/placement/promo.port.ts
+/** Build the port for one engine. A factory, not a frozen singleton — the singleton form
+*  forced the placement verbs to resolve a module-global engine. */
+function createPromoPort(deps) {
+	const placement = createPromoPlacement(deps);
+	const UNATTRIBUTED_ACTOR = "unattributed";
+	return Object.freeze({
+		reserve: (input) => placement.reservePromo({
+			lines: input.lines,
+			subtotal: input.subtotal,
+			codes: input.codes ?? [],
+			...input.customerId !== void 0 ? { customerId: input.customerId } : {},
+			actorId: input.actorId === void 0 ? UNATTRIBUTED_ACTOR : String(input.actorId),
+			...input.organizationId !== void 0 ? { organizationId: String(input.organizationId) } : {},
+			...input.logger !== void 0 ? { logger: input.logger } : {}
+		}),
+		commit: (reservation, orderId, scope) => placement.commitPromo(reservation, orderId, {
+			actorId: scope.actorId === void 0 ? UNATTRIBUTED_ACTOR : String(scope.actorId),
+			...scope.organizationId !== void 0 ? { organizationId: String(scope.organizationId) } : {},
+			...scope.logger !== void 0 ? { logger: scope.logger } : {}
+		}),
+		rollback: (reservation, scope) => placement.rollbackPromo(reservation, {
+			actorId: scope.actorId === void 0 ? UNATTRIBUTED_ACTOR : String(scope.actorId),
+			...scope.organizationId !== void 0 ? { organizationId: String(scope.organizationId) } : {},
+			...scope.logger !== void 0 ? { logger: scope.logger } : {}
+		})
+	});
+}
+//#endregion
+export { createPromoPort };

package/dist/resources.d.mts

@@ -0,0 +1,38 @@
+import { i as PromoModuleDeps, n as PromoActorCtx, r as PromoEngineLike } from "./types-D07igQha.mjs";
+import { PromoModels, PromoRepositories, PromoServices } from "@classytic/promo";
+import { z } from "zod";
+import { FastifyRequest } from "fastify";
+//#region src/resources.d.ts
+/** Internal wiring bundle shared by the five factories. */
+interface PromoFactoryCtx {
+  deps: PromoModuleDeps;
+  engineModels: PromoModels;
+  engineRepos: PromoRepositories;
+  engineServices: PromoServices;
+  actor: (req: FastifyRequest) => PromoActorCtx;
+}
+declare function buildFactoryCtx(deps: PromoModuleDeps, engine: PromoEngineLike): PromoFactoryCtx;
+declare function createProgramResource(fx: PromoFactoryCtx): import("@classytic/arc").ResourceDefinition<unknown>;
+declare function createVoucherResource(fx: PromoFactoryCtx): import("@classytic/arc").ResourceDefinition<unknown>;
+declare function createRuleResource(fx: PromoFactoryCtx): import("@classytic/arc").ResourceDefinition<unknown>;
+declare function createRewardResource(fx: PromoFactoryCtx): import("@classytic/arc").ResourceDefinition<unknown>;
+declare function createEvaluationResource(fx: PromoFactoryCtx): import("@classytic/arc").ResourceDefinition<unknown> & {
+  readonly actions: {
+    commit: {
+      handler: (id: string, data: Record<string, unknown>, req: FastifyRequest) => Promise<unknown>;
+      permissions: import("@spinekit/kit/permissions").PermissionGate;
+      schema: z.ZodObject<{
+        orderId: z.ZodString;
+        cartHash: z.ZodOptional<z.ZodString>;
+      }, z.core.$strip>;
+    };
+    rollback: {
+      handler: (id: string, data: Record<string, unknown>, req: FastifyRequest) => Promise<{
+        message: string;
+      }>;
+      permissions: import("@spinekit/kit/permissions").PermissionGate;
+    };
+  };
+};
+//#endregion
+export { PromoFactoryCtx, buildFactoryCtx, createEvaluationResource, createProgramResource, createRewardResource, createRuleResource, createVoucherResource };

package/dist/resources.mjs

@@ -0,0 +1,266 @@
+import { promoAction, promoRoute } from "./errors.mjs";
+import { ArcError } from "@classytic/arc/utils";
+import { defineResource, mergeResourceConfig } from "@classytic/arc";
+import { getUserId } from "@classytic/arc/scope";
+import { QueryParser } from "@classytic/mongokit";
+import { createMongooseAdapter } from "@classytic/mongokit/adapter";
+import { z } from "zod";
+//#region src/resources.ts
+/**
+* The five promo resource factories — lifted at wire parity from be-prod's
+* promotions fork. Program & Voucher: adapter CRUD + FSM actions (Stripe
+* pattern) + code-centric routes. Rule & Reward: first-class top-level CRUD
+* filtered by `?programId=`. Evaluation: pure service orchestration (no
+* model) — id-scoped commit/rollback actions + preview/evaluate routes.
+*/
+function defaultActor(req) {
+	return { actorRef: getUserId(req.scope) ?? "anonymous" };
+}
+function buildFactoryCtx(deps, engine) {
+	return {
+		deps,
+		engineModels: engine.models,
+		engineRepos: engine.repositories,
+		engineServices: engine.services,
+		actor: deps.resolveActor ?? defaultActor
+	};
+}
+function createProgramResource(fx) {
+	const { deps, engineModels, engineRepos, actor } = fx;
+	const gates = deps.permissions.programs;
+	const programRepo = engineRepos.program;
+	const ruleRepo = engineRepos.rule;
+	const rewardRepo = engineRepos.reward;
+	return defineResource(mergeResourceConfig({
+		name: "promo-program",
+		displayName: "Promo Programs",
+		tag: "Promotions",
+		prefix: deps.prefixes?.program ?? "/promotions/programs",
+		tenantField: false,
+		adapter: createMongooseAdapter(engineModels.Program, engineRepos.program),
+		permissions: {
+			list: gates.list,
+			get: gates.get,
+			create: gates.create,
+			update: gates.update,
+			delete: gates.delete
+		},
+		actions: {
+			activate: {
+				handler: promoAction(async (id, _d, req) => programRepo.activate?.(id, actor(req))),
+				permissions: gates.transition
+			},
+			pause: {
+				handler: promoAction(async (id, _d, req) => programRepo.pause?.(id, actor(req))),
+				permissions: gates.transition
+			},
+			archive: {
+				handler: promoAction(async (id, _d, req) => programRepo.archive?.(id, actor(req))),
+				permissions: gates.transition
+			}
+		},
+		routes: [{
+			method: "GET",
+			path: "/:id/full",
+			summary: "Get full program with rules + rewards",
+			permissions: gates.get,
+			rawHandler: promoRoute(async (req) => {
+				const { id } = req.params;
+				const [program, rules, rewards] = await Promise.all([
+					programRepo.getById(id, { lean: true }),
+					ruleRepo.findAll({ programId: id }),
+					rewardRepo.findAll({ programId: id })
+				]);
+				if (!program) throw new ArcError("Program not found", {
+					code: "PROGRAM_NOT_FOUND",
+					statusCode: 404
+				});
+				return {
+					...program,
+					rules,
+					rewards
+				};
+			})
+		}, ...deps.extraRoutes?.program ?? []]
+	}));
+}
+function createVoucherResource(fx) {
+	const { deps, engineModels, engineRepos, engineServices, actor } = fx;
+	const gates = deps.permissions.vouchers;
+	const voucherRepo = engineRepos.voucher;
+	const voucherService = engineServices.voucher;
+	return defineResource(mergeResourceConfig({
+		name: "promo-voucher",
+		displayName: "Promo Vouchers",
+		tag: "Promotions",
+		prefix: deps.prefixes?.voucher ?? "/promotions/vouchers",
+		tenantField: false,
+		adapter: createMongooseAdapter(engineModels.Voucher, engineRepos.voucher),
+		/**
+		* A voucher is STORED VALUE, and it is minted only by `/generate` and
+		* `/generate-single` — which allocate a unique code, stamp the batch and apply the
+		* program's expiry. Raw CRUD writes bypass every one of those invariants, so they are
+		* not a second door with a stricter lock; they are not a door at all.
+		*
+		* This is why `PromoPermissions['vouchers']` declares `list | get | cancel | generate`
+		* and no CRUD write gates: the gate set IS the intended surface. But the adapter mounts
+		* all five slots regardless, and an OMITTED permission mounts the route WITHOUT auth —
+		* so before this was gated, `POST /promotions/vouchers` let an unauthenticated caller
+		* mint arbitrary voucher codes. Nothing threw; the routes simply answered.
+		*
+		* Found the moment `ARC_STRICT_PERMISSIONS=true` was switched on for the first time.
+		*
+		* Expressed as a POSITIVE `crud` allow-list (arc's documented going-forward form) rather
+		* than a `disabledRoutes` deny-list: the two are equivalent (`crud: { list, get }` ⇒
+		* `disabledRoutes: [create, update, delete]`), but the allow-list states the intended
+		* surface directly, so a new write op cannot leak in by someone shortening a deny-list —
+		* every slot is opt-in.
+		*/
+		crud: {
+			list: true,
+			get: true
+		},
+		permissions: {
+			list: gates.list,
+			get: gates.get
+		},
+		actions: { cancel: {
+			handler: promoAction(async (id, _d, req) => voucherRepo.cancel?.(id, actor(req))),
+			permissions: gates.cancel
+		} },
+		routes: [
+			{
+				method: "POST",
+				path: "/generate",
+				summary: "Generate batch voucher codes",
+				permissions: gates.generate,
+				rawHandler: promoRoute(async (req) => voucherService.generateCodes?.(req.body, actor(req)), 201)
+			},
+			{
+				method: "POST",
+				path: "/generate-single",
+				summary: "Generate single voucher code",
+				permissions: gates.generate,
+				rawHandler: promoRoute(async (req) => voucherService.generateSingleCode?.(req.body, actor(req)), 201)
+			},
+			{
+				method: "POST",
+				path: "/validate/:code",
+				summary: "Validate voucher code",
+				permissions: deps.permissions.evaluation.validateCode ?? deps.permissions.evaluation.preview,
+				rawHandler: promoRoute(async (req) => {
+					const { code } = req.params;
+					return voucherService.validateCode?.(code, actor(req));
+				})
+			},
+			{
+				method: "GET",
+				path: "/code/:code",
+				summary: "Get voucher by code",
+				permissions: gates.get,
+				rawHandler: promoRoute(async (req) => {
+					const { code } = req.params;
+					const data = await voucherRepo.getByCode?.(code);
+					if (!data) throw new ArcError("Voucher not found", {
+						code: "VOUCHER_NOT_FOUND",
+						statusCode: 404
+					});
+					return data;
+				})
+			}
+		]
+	}));
+}
+function crudResource(fx, cfg) {
+	return defineResource(mergeResourceConfig({
+		name: cfg.name,
+		displayName: cfg.displayName,
+		tag: "Promotions",
+		prefix: cfg.prefix,
+		tenantField: false,
+		adapter: createMongooseAdapter(fx.engineModels[cfg.modelKey], fx.engineRepos[cfg.repoKey]),
+		queryParser: new QueryParser({
+			maxLimit: 100,
+			allowedFilterFields: ["programId", "code"],
+			allowedSortFields: ["createdAt", "updatedAt"]
+		}),
+		permissions: {
+			list: cfg.gates.list,
+			get: cfg.gates.get,
+			create: cfg.gates.create,
+			update: cfg.gates.update,
+			delete: cfg.gates.delete
+		}
+	}));
+}
+function createRuleResource(fx) {
+	return crudResource(fx, {
+		name: "promo-rule",
+		displayName: "Promo Rules",
+		prefix: fx.deps.prefixes?.rule ?? "/promotions/rules",
+		modelKey: "Rule",
+		repoKey: "rule",
+		gates: fx.deps.permissions.rules
+	});
+}
+function createRewardResource(fx) {
+	return crudResource(fx, {
+		name: "promo-reward",
+		displayName: "Promo Rewards",
+		prefix: fx.deps.prefixes?.reward ?? "/promotions/rewards",
+		modelKey: "Reward",
+		repoKey: "reward",
+		gates: fx.deps.permissions.rewards
+	});
+}
+function createEvaluationResource(fx) {
+	const { deps, engineServices, actor } = fx;
+	const gates = deps.permissions.evaluation;
+	const evaluation = engineServices.evaluation;
+	return defineResource({
+		name: "promo-evaluation",
+		displayName: "Promo Evaluation",
+		tag: "Promotions",
+		prefix: deps.prefixes?.evaluation ?? "/promotions/evaluate",
+		disableDefaultRoutes: true,
+		actions: {
+			commit: {
+				handler: promoAction(async (id, data, req) => {
+					const { orderId, cartHash } = data;
+					return evaluation.commit?.(id, orderId, actor(req), cartHash ? { cartHash } : {});
+				}),
+				permissions: gates.evaluate,
+				schema: z.object({
+					orderId: z.string(),
+					cartHash: z.string().optional()
+				})
+			},
+			rollback: {
+				handler: promoAction(async (id, _d, req) => {
+					await evaluation.rollback?.(id, actor(req));
+					return { message: "Rolled back" };
+				}),
+				permissions: gates.evaluate
+			}
+		},
+		routes: [
+			{
+				method: "POST",
+				path: "/preview",
+				summary: "Preview evaluation (no side effects)",
+				permissions: gates.preview,
+				rawHandler: promoRoute(async (req) => evaluation.preview?.(req.body, actor(req)))
+			},
+			{
+				method: "POST",
+				path: "/",
+				summary: "Evaluate cart (creates pending evaluation)",
+				permissions: gates.evaluate,
+				rawHandler: promoRoute(async (req) => evaluation.evaluate?.(req.body, actor(req)), 201)
+			},
+			...deps.extraRoutes?.evaluation ?? []
+		]
+	});
+}
+//#endregion
+export { buildFactoryCtx, createEvaluationResource, createProgramResource, createRewardResource, createRuleResource, createVoucherResource };

package/dist/types-D07igQha.d.mts

@@ -0,0 +1,132 @@
+import { PromoEngine, definePromo } from "@classytic/promo";
+import { EngineRef, EngineSlot } from "@spinekit/kit/engine-slot";
+import { FastifyRequest } from "fastify";
+import { Connection } from "mongoose";
+import { PermissionGate } from "@spinekit/kit/permissions";
+//#region src/types.d.ts
+/**
+ * Immutable engine configuration — the DESCRIBE half.
+ *
+ * Derived from `definePromo`'s own parameter, never restated: a hand-written copy type-checks
+ * against a signature that has since changed, and the drift is invisible until runtime.
+ */
+type PromoEngineShape = Parameters<typeof definePromo>[0];
+/** Live collaborators — the BIND half. */
+type PromoEngineRuntime = Parameters<ReturnType<typeof definePromo>['bind']>[1];
+/**
+ * The slice of the kernel's engine this module requires — DERIVED from
+ * `PromoEngine`, never restated.
+ *
+ * It exists as a narrowing (not an alias for `PromoEngine`) so a host can pass a test
+ * double or a superset without constructing a full engine. `Pick` rather than a
+ * re-declared interface is the whole point: if the kernel renames `services` or changes
+ * `PromoRepositories`, this breaks HERE at build time. A hand-written twin would keep
+ * compiling against a shape the kernel no longer has.
+ *
+ * DELIBERATELY OMITTED: `events`, `syncIndexes()` and `destroy()`. This module never
+ * drives engine lifecycle — the host owns it. If a future arm needs `destroy()`, widen
+ * this Pick rather than casting at the call site.
+ */
+type PromoEngineLike = Pick<PromoEngine, 'models' | 'repositories' | 'services'>;
+/** Per-CRUD-slot gates (arc resource permissions shape). */
+interface CrudGates {
+  list: PermissionGate;
+  get: PermissionGate;
+  create: PermissionGate;
+  update: PermissionGate;
+  delete: PermissionGate;
+}
+interface PromoPermissions {
+  programs: CrudGates & {
+    transition: PermissionGate;
+  };
+  vouchers: {
+    list: PermissionGate;
+    get: PermissionGate;
+    cancel: PermissionGate;
+    generate: PermissionGate;
+  };
+  rules: CrudGates;
+  rewards: CrudGates;
+  evaluation: {
+    /** Read-only preview (display math — no side effects). */
+    preview: PermissionGate;
+    /** Evaluate/commit/rollback (mutates reservations). */
+    evaluate: PermissionGate;
+    /**
+     * Validate a voucher code at CHECKOUT (`POST /vouchers/validate/:code`).
+     *
+     * A checkout-time READ authority (a cashier/shopper confirming a code), NOT the
+     * voucher-admin `get` gate. Optional so existing hosts need not add it; when
+     * absent the route falls back to `preview` (the other checkout read authority),
+     * never to `vouchers.get` — validating a code is not a voucher-management action,
+     * and gating it as one silently locked cashiers out of the very flow the code
+     * exists for.
+     */
+    validateCode?: PermissionGate;
+  };
+}
+/** Actor context for promo service calls (kernel `actorRef` convention). */
+interface PromoActorCtx {
+  actorRef: string;
+}
+interface PromoModuleDeps<TEngine extends PromoEngineLike = PromoEngineLike> {
+  /**
+   * The promo engine, host-initialized. Exported at `arc.modules.promo`.
+   *
+   * Accepts an {@link EngineRef}: a LIVE engine (legacy, resolved immediately) or a
+   * THUNK `() => ensurePromoEngine()`. The thunk keeps the five promo models out of
+   * the compose-time set — the module allocates nothing while the graph is composed
+   * and resolves the engine in `bootstrap` (post-connect), like order/accounting/pos.
+   */
+  engine?: EngineRef<TEngine>;
+  /**
+   * ── Module-OWNED construction (preferred) ──────────────────────────────
+   *
+   * Supply these INSTEAD of `engine` and this module describes, binds, publishes and CLOSES the
+   * engine. That is what makes ownership single: `deferredEngine` only tears down what it
+   * allocated (`owned = supplied === undefined`), so a host-supplied `engine` leaves teardown with
+   * the host — and be-prod expressed that teardown in a separate Fastify plugin, split from the
+   * module that mounted the resources. Two systems, one engine, and the module graph did not
+   * describe who owned it.
+   *
+   * The split was not theoretical: the plugin called `ensurePromoEngine()` EAGERLY at
+   * registration, so the five promo models registered before arc had ordered the module graph —
+   * exactly the allocation the deferred thunk was added to prevent. The thunk was correct and the
+   * plugin walked straight past it.
+   *
+   * `shape` is immutable configuration, `runtime` the live collaborators (DESCRIBE then BIND).
+   */
+  connection?: Connection;
+  engineShape?: () => PromoEngineShape;
+  engineRuntime?: () => PromoEngineRuntime;
+  /**
+   * A slot to publish the bound engine into, SHARED with the host.
+   *
+   * Lets a host READ the engine (`slot.get()`) without OWNING it — this module fills it at
+   * bootstrap and empties it at teardown. Without it a host that merely needs to read has to
+   * construct, which is the ownership inversion this arm exists to remove.
+   */
+  slot?: EngineSlot<TEngine>;
+  /**
+   * Host contribution arm — declared so a host never has to spread the returned module.
+   * COMPOSES with the module-owned engine close (host runs FIRST, then the engine is
+   * closed) — see `defineSpineModule`'s teardown-composition docblock; it never replaces it.
+   */
+  onClose?: (fastify: unknown) => void | Promise<void>;
+  permissions: PromoPermissions;
+  /**
+   * Derive the kernel actor context from the request. Default: arc's
+   * scope-first actor (`request.scope` userId/clientId) falling back to
+   * `'anonymous'`.
+   * `organizationId` is intentionally NOT part of the context — promo is
+   * company-wide; passing it would re-scope reads/writes per branch.
+   */
+  resolveActor?: (req: FastifyRequest) => PromoActorCtx;
+  /** Mount prefixes. Defaults: /promotions/{programs,vouchers,rules,rewards,evaluate}. */
+  prefixes?: Partial<Record<'program' | 'voucher' | 'rule' | 'reward' | 'evaluation', string>>;
+  /** App-policy routes appended per resource surface. */
+  extraRoutes?: Partial<Record<'program' | 'voucher' | 'evaluation', ReadonlyArray<import('@classytic/arc/types').RouteDefinition>>>;
+}
+//#endregion
+export { PromoPermissions as a, PromoModuleDeps as i, PromoActorCtx as n, PromoEngineLike as r, CrudGates as t };

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@spinekit/promo",
+  "version": "0.1.0",
+  "description": "Arc module for @classytic/promo — programs, vouchers, rules, rewards, and cart evaluation as composable arc resources. BYO engine; company-wide by default (tenantField: false — a voucher generated at one branch redeems at any other); ships the promo-kernel↔wire error contract (stable UPPER_SNAKE codes + HTTP statuses).",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Classytic",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json",
+    "./placement": {
+      "types": "./dist/placement/promo-placement.d.mts",
+      "default": "./dist/placement/promo-placement.mjs"
+    },
+    "./port": {
+      "types": "./dist/placement/promo.port.d.mts",
+      "default": "./dist/placement/promo.port.mjs"
+    },
+    "./resources": {
+      "types": "./dist/resources.d.mts",
+      "default": "./dist/resources.mjs"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.mts",
+      "default": "./dist/errors.mjs"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://www.npmjs.com/package/@spinekit/promo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/spine.git",
+    "directory": "packages/spine-promo"
+  },
+  "keywords": [
+    "arc",
+    "classytic",
+    "spine",
+    "erp",
+    "promo",
+    "promotions",
+    "voucher",
+    "discount",
+    "coupon",
+    "evaluation"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "peerDependencies": {
+    "@classytic/arc": ">=2.34.0",
+    "@classytic/mongokit": ">=3.34.0",
+    "@classytic/primitives": ">=0.23.0",
+    "@classytic/promo": ">=0.7.0",
+    "@spinekit/kit": ">=0.1.0",
+    "mongoose": ">=9.4.1",
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@classytic/arc": "^2.34.0",
+    "@classytic/arc-testkit": "^0.4.0",
+    "@classytic/mongokit": ">=3.34.0",
+    "@classytic/primitives": ">=0.23.0",
+    "@classytic/promo": ">=0.7.0",
+    "@spinekit/kit": "workspace:*",
+    "@types/node": "^24.3.0",
+    "fastify": "^5.12.0",
+    "mongoose": "^9.7.2",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^3.2.4",
+    "zod": "^4.3.6"
+  }
+}