@classytic/primitives 0.29.0 → 0.31.0

package/CHANGELOG.md

@@ -3,6 +3,49 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.31.0 — 2026-10-11
+
+### Added — `./quantity`: the 6-decimal quantity grid for fractional stock and sale quantities
+- `snapQuantity(qty, step?, mode)` (half-even by default), `isOnStep`, `compareQuantity`, `quantitiesEqual`,
+  `quantityToGrid`, `quantityStepToGrid`, `QUANTITY_SCALE` (1,000,000) and `QuantityError`
+  (`NOT_FINITE` / `INVALID_STEP` / `UNSAFE_QUANTITY`).
+- `isOnQuantityGrid(value)`: STRICT, for input boundaries. `isOnStep` snaps first, so
+  `isOnStep(2.3500004, 0.001)` is true; `isOnQuantityGrid(2.3500004)` is false.
+
+### Added — `./usage-pricing`
+- `priceUsage(rating, measured)` prices a measured amount against a `UsageRating` (per-unit, tiered, volume,
+  package; a started unit counts whole; breakdown included), plus `UsageMeasure` / `isUsageMeasure` and
+  `UsagePricingError`.
+
+### Added — the stock unit group on item facts
+- `uomGroupRef` (optional) on `ItemStockSource`, `ProductFacet` and `ItemStockFacts`, and `unitOfMeasureDeclared`
+  (optional) on `ProductFacet` and `ItemStockFacts`. `resolveStockFacts` takes the Item's group, falls back to
+  the product's only when no Item exists, and marks an ungrouped Item under a grouped product
+  `unitOfMeasureDeclared` instead of borrowing the product's group. All fields optional: existing values of these
+  types still type-check.
+
+### Changed — `resolvePriceBasisTotal` accepts a fractional quantity
+- A whole quantity is computed exactly as before, across the full safe-integer range (pinned by a regression
+  test against the previous formula).
+- A fractional quantity on the 6-decimal grid (e.g. `2.35`) is priced exactly: price × quantity on the grid,
+  divided by the measured basis, rounded ONCE half-even. Previously it threw `INVALID_QUANTITY`.
+- Still refused (`INVALID_QUANTITY`): a negative, non-finite or off-grid quantity (a 7th decimal), or a
+  fraction too large to scale exactly.
+
+## 0.30.0 — never published separately; shipped in 0.31.0
+
+### Added — `./durable-events`: the declaration and the ONE kernel dispatch
+- `EventDurability`, `DurableEventSpec`, `FactExpectation`; `eventIdFor` / `durableEventMeta` (`${name}:v${version}:${occurrence}`); `requireDurableContext` + `NonDurablePublishError`; `UnmanagedSessionError`.
+- `dispatchDomainEvent(channels, unit, event, durability)` saves the outbox row in the session, defers to commit, and acknowledges after an inline publish.
+- `flushDeferredEvents` delivers a committed queue and acknowledges every delivered row in ONE `acknowledgeMany`.
+Pinned by `tests/unit/durable-events.test.ts`.
+
+### Added — `./outbox`: `OutboxConflictError`, `outboxPayloadFingerprint`, optional `OutboxStore.acknowledgeMany`
+
+### ⚠ Changed
+- `createChildEvent` no longer inherits the parent's `idempotencyKey`. A child is its own occurrence; an inherited key made a store drop the second of two child types.
+- `MemoryOutboxStore.save`: the same id with the same payload is a no-op, and a different payload throws `OutboxConflictError`.
+
 ## 0.29.0 — 2026-10-08
 
 ### Added — `./signed-token`: ES256 compact JWS over WebCrypto

package/dist/approval.d.mts

@@ -32,7 +32,9 @@
  * isApproved(chain); // → true
  */
 type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'skipped';
-type ChainOrder = 'sequential' | 'parallel';
+declare const CHAIN_ORDERS: readonly ["sequential", "parallel"];
+type ChainOrder = (typeof CHAIN_ORDERS)[number];
+declare const APPROVAL_THRESHOLD_OPS: readonly ["gt", "gte", "lt", "lte", "eq"];
 interface Approver {
   readonly id: string;
   readonly name?: string;
@@ -43,6 +45,11 @@ interface ApprovalDecision {
   readonly decision: 'approved' | 'rejected';
   readonly note?: string;
   readonly decidedAt: Date;
+  /**
+   * The org the approver acted from, when it differs from the document's (a cross-branch
+   * decision). The document's own org is the document's tenant field, so both are on the row.
+   */
+  readonly actorOrganizationId?: string;
 }
 /**
  * Optional threshold gate. The primitive does not evaluate this — it's
@@ -52,7 +59,7 @@ interface ApprovalDecision {
  */
 interface ApprovalThreshold {
   readonly field: string;
-  readonly op: 'gt' | 'gte' | 'lt' | 'lte' | 'eq';
+  readonly op: (typeof APPROVAL_THRESHOLD_OPS)[number];
   readonly value: number;
 }
 interface ApprovalStep {
@@ -86,9 +93,13 @@ interface ApprovalChain {
 interface ApprovalRequest {
   readonly by: string;
   readonly at: Date;
-  /** What the approval covers. A later amount above `basis.amount` is not covered. */
+  /**
+   * What the approval covers. A later amount above `basis.amount` is not covered. `unit` states the
+   * amount is integer base-currency minor units; a stored amount without it is of unknown unit.
+   */
   readonly basis?: {
     readonly amount?: number;
+    readonly unit?: 'minor';
     readonly category?: string;
   };
 }
@@ -178,15 +189,72 @@ declare function attachRequest(chain: ApprovalChain, request: ApprovalRequest):
  * For `parallel` chains: returns the first pending step (all pending steps
  * are active simultaneously; host typically iterates with {@link pendingSteps}).
  */
-declare function nextPendingStep(chain: ApprovalChain): ApprovalStep | null;
+declare function nextPendingStep<S extends {
+  readonly status: ApprovalStatus;
+}>(chain: {
+  readonly steps: readonly S[];
+}): S | null;
 /** All steps currently eligible to receive a decision. */
-declare function pendingSteps(chain: ApprovalChain): readonly ApprovalStep[];
+declare function pendingSteps<S extends {
+  readonly status: ApprovalStatus;
+}>(chain: {
+  readonly order: ChainOrder;
+  readonly steps: readonly S[];
+}): readonly S[];
+/**
+ * The verbs every approval-bearing resource mounts at `POST /:id/action`.
+ * Servers (arc-approval) and clients (SDK, UI) both read these; never write the strings.
+ */
+declare const APPROVAL_ACTIONS: {
+  readonly submit: "submit_for_approval";
+  readonly decide: "decide";
+};
+type ApprovalActionName = (typeof APPROVAL_ACTIONS)[keyof typeof APPROVAL_ACTIONS];
+/** Where a submit sources its chain: inline `chain`, the policy matrix, or inferred. */
+declare const APPROVAL_CHAIN_SOURCES: readonly ["auto", "literal", "policy"];
+type ApprovalChainSource = (typeof APPROVAL_CHAIN_SOURCES)[number];
+declare const APPROVAL_DECISIONS: readonly ["approved", "rejected"];
+type ApprovalDecisionKind = (typeof APPROVAL_DECISIONS)[number];
+/** Longest decision note the server accepts. */
+declare const APPROVAL_NOTE_MAX_LENGTH = 1000;
+/** `submit_for_approval` body. */
+type ApprovalSubmitBody = {
+  readonly source?: ApprovalChainSource;
+  readonly chain?: CreateChainInput;
+};
+/** `decide` body. The approver is the authenticated actor — never a body field. */
+type ApprovalDecideBody = {
+  readonly stepId: string;
+  readonly decision: ApprovalDecisionKind;
+  readonly note?: string;
+};
+/** The chain fields {@link decidableStepIds} reads — satisfied by a stored chain and by its JSON form. */
+interface DecidableChain {
+  readonly order: ChainOrder;
+  readonly status: ApprovalStatus;
+  readonly steps: readonly {
+    readonly id: string;
+    readonly status: ApprovalStatus;
+    readonly approvers: readonly {
+      readonly id: string;
+    }[];
+    readonly decisions: readonly {
+      readonly approverId: string;
+    }[];
+  }[];
+}
+/**
+ * The steps `actorId` may decide now: active, naming the actor as an approver, not yet
+ * decided by them. The ONE answer to "may this actor decide" for server and UI alike.
+ */
+declare function decidableStepIds(chain: DecidableChain, actorId: string | null | undefined): string[];
 interface DecisionInput {
   readonly stepId: string;
   readonly approverId: string;
   readonly decision: 'approved' | 'rejected';
   readonly note?: string;
   readonly decidedAt?: Date;
+  readonly actorOrganizationId?: string;
 }
 /**
  * Apply a decision to a step. Returns a new chain — original is not mutated.
@@ -266,4 +334,4 @@ declare function isPending(chain: ApprovalChain): boolean;
  */
 declare function decisionCount(chain: ApprovalChain): number;
 //#endregion
-export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalRequest, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, AssertApprovedOptions, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, assertApproved, assertApprovedIfPresent, attachRequest, createChain, decisionCount, isApproved, isNotRequired, isPending, isRejected, nextPendingStep, notRequiredChain, pendingSteps, skipStep };
+export { APPROVAL_ACTIONS, APPROVAL_CHAIN_SOURCES, APPROVAL_DECISIONS, APPROVAL_NOTE_MAX_LENGTH, APPROVAL_THRESHOLD_OPS, ApprovalActionName, ApprovalChain, ApprovalChainSource, ApprovalDecideBody, ApprovalDecision, ApprovalDecisionKind, ApprovalError, ApprovalErrorCode, ApprovalRequest, ApprovalStatus, ApprovalStep, ApprovalSubmitBody, ApprovalThreshold, Approver, AssertApprovedOptions, CHAIN_ORDERS, ChainOrder, CreateChainInput, CreateStepInput, DecidableChain, DecisionInput, applyDecision, assertApproved, assertApprovedIfPresent, attachRequest, createChain, decidableStepIds, decisionCount, isApproved, isNotRequired, isPending, isRejected, nextPendingStep, notRequiredChain, pendingSteps, skipStep };

package/dist/approval.mjs

@@ -1,4 +1,12 @@
 //#region src/workflow/approval.ts
+const CHAIN_ORDERS = ["sequential", "parallel"];
+const APPROVAL_THRESHOLD_OPS = [
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"eq"
+];
 var ApprovalError = class extends Error {
 	name = "ApprovalError";
 	code;
@@ -125,6 +133,31 @@ function pendingSteps(chain) {
 	return chain.steps.filter((s) => s.status === "pending");
 }
 /**
+* The verbs every approval-bearing resource mounts at `POST /:id/action`.
+* Servers (arc-approval) and clients (SDK, UI) both read these; never write the strings.
+*/
+const APPROVAL_ACTIONS = {
+	submit: "submit_for_approval",
+	decide: "decide"
+};
+/** Where a submit sources its chain: inline `chain`, the policy matrix, or inferred. */
+const APPROVAL_CHAIN_SOURCES = [
+	"auto",
+	"literal",
+	"policy"
+];
+const APPROVAL_DECISIONS = ["approved", "rejected"];
+/** Longest decision note the server accepts. */
+const APPROVAL_NOTE_MAX_LENGTH = 1e3;
+/**
+* The steps `actorId` may decide now: active, naming the actor as an approver, not yet
+* decided by them. The ONE answer to "may this actor decide" for server and UI alike.
+*/
+function decidableStepIds(chain, actorId) {
+	if (!actorId || chain.status !== "pending") return [];
+	return pendingSteps(chain).filter((s) => s.approvers.some((a) => a.id === actorId) && !s.decisions.some((d) => d.approverId === actorId)).map((s) => s.id);
+}
+/**
 * Apply a decision to a step. Returns a new chain — original is not mutated.
 * Throws if the step is unknown, not active, the approver isn't listed, or
 * the approver has already decided.
@@ -142,7 +175,8 @@ function applyDecision(chain, input) {
 		approverId: input.approverId,
 		decision: input.decision,
 		...input.note !== void 0 ? { note: input.note } : {},
-		decidedAt: input.decidedAt ?? /* @__PURE__ */ new Date()
+		decidedAt: input.decidedAt ?? /* @__PURE__ */ new Date(),
+		...input.actorOrganizationId !== void 0 ? { actorOrganizationId: input.actorOrganizationId } : {}
 	};
 	const updatedStep = computeStepStatus({
 		...step,
@@ -271,4 +305,4 @@ function computeChainStatus(steps) {
 	return steps.every((s) => s.status === "approved" || s.status === "skipped") ? "approved" : "pending";
 }
 //#endregion
-export { ApprovalError, applyDecision, assertApproved, assertApprovedIfPresent, attachRequest, createChain, decisionCount, isApproved, isNotRequired, isPending, isRejected, nextPendingStep, notRequiredChain, pendingSteps, skipStep };
+export { APPROVAL_ACTIONS, APPROVAL_CHAIN_SOURCES, APPROVAL_DECISIONS, APPROVAL_NOTE_MAX_LENGTH, APPROVAL_THRESHOLD_OPS, ApprovalError, CHAIN_ORDERS, applyDecision, assertApproved, assertApprovedIfPresent, attachRequest, createChain, decidableStepIds, decisionCount, isApproved, isNotRequired, isPending, isRejected, nextPendingStep, notRequiredChain, pendingSteps, skipStep };

package/dist/durable-events.d.mts

@@ -0,0 +1,83 @@
+import { DomainEvent, EventMeta, EventTransport } from "./events.mjs";
+import { ErrorLogger } from "./event-infra.mjs";
+import { OutboxStore } from "./outbox.mjs";
+//#region src/events/durable.d.ts
+/** Required on every definition; no default, so neither side escapes by omission. */
+type EventDurability = 'ephemeral' | 'durable';
+/**
+ * A fact a durable event must eventually produce — attached at composition by its CONSUMER.
+ * Members are methods so a typed definition stays assignable to an `unknown`-payload registry.
+ */
+interface FactExpectation<P> {
+  /** `'journal-entry'`, `'stock-move'`, … — matched to a mounted probe. */
+  readonly kind: string;
+  /** The consumer's own key function: the keys its fact rows carry for this event. */
+  keys(payload: P, meta: EventMeta): readonly string[];
+  readonly graceMinutes: number;
+  /** `'unknown'` is a finding, never "does not apply". */
+  applies?(payload: P): boolean | 'unknown';
+}
+type DurableEventSpec<P> = {
+  readonly durability: 'ephemeral';
+} | {
+  readonly durability: 'durable';
+  /** Aggregate id plus step (`fulfillmentId`, `${paymentId}:captured`) — never the order alone. */
+  occurrence(payload: P): string;
+  readonly produces?: readonly FactExpectation<P>[];
+};
+/** Where a publish happens. `deliveryOf` is the parent event id, set around a relayed delivery. */
+interface DurableContext {
+  readonly session?: unknown;
+  readonly outbox?: OutboxStore | undefined;
+  readonly deliveryOf?: string | undefined;
+}
+declare class NonDurablePublishError extends Error {
+  readonly name = "NonDurablePublishError";
+  readonly code = "events.non_durable_publish";
+  readonly eventType: string;
+  constructor(eventType: string, reason: string);
+}
+/** An open session with neither an outbox nor a post-commit queue: publishing leaks, dropping loses. */
+declare class UnmanagedSessionError extends Error {
+  readonly name = "UnmanagedSessionError";
+  readonly code = "events.unmanaged_session";
+  constructor(eventType: string);
+}
+/** `${name}:v${version}:${occurrence}` — the same occurrence always yields the same id. */
+declare function eventIdFor(name: string, version: number, occurrence: string): string;
+/** The meta a durable event is created with: a fixed id, and the same value as its idempotency key. */
+declare function durableEventMeta(name: string, version: number, occurrence: string): Required<Pick<EventMeta, 'id' | 'idempotencyKey'>>;
+/** Throws unless a durable type is in a unit of work (session + transactional store) or a durable delivery. */
+declare function requireDurableContext(def: {
+  readonly name: string;
+  readonly durability: EventDurability;
+}, ctx: DurableContext): void;
+interface DispatchChannels {
+  readonly outbox: OutboxStore | undefined;
+  readonly transport: EventTransport | undefined;
+  /** With an outbox: `'relay'` = the row is the delivery; `'inline'` (default) = publish live, then acknowledge. */
+  readonly dispatch?: 'inline' | 'relay' | undefined;
+  /** Prefix for log lines, e.g. the kernel name. */
+  readonly label: string;
+  readonly logger?: ErrorLogger | undefined;
+}
+interface DispatchUnit extends Omit<DurableContext, 'outbox'> {
+  /** The post-commit queue of an open unit of work; its owner calls {@link flushDeferredEvents}. */
+  readonly pending?: DomainEvent[] | undefined;
+}
+/** `published` and `relay` are delivered or owned; `publish_failed` leaves a pending row (or nothing, with no outbox). */
+type DispatchOutcome = 'deferred' | 'committed' | 'relay' | 'published' | 'publish_failed' | 'no_transport';
+/**
+ * Emit one domain event. The outbox save runs first, in the session, and its failure propagates.
+ * In a unit of work delivery waits for {@link flushDeferredEvents}; otherwise an inline publish is
+ * acknowledged so the relay does not deliver it again, and a failed one stays pending for the relay.
+ */
+declare function dispatchDomainEvent(channels: DispatchChannels, unit: DispatchUnit, event: DomainEvent, durability: EventDurability): Promise<DispatchOutcome>;
+/**
+ * Deliver a committed unit of work's queue. Under `'relay'` the rows are the delivery and nothing
+ * is published. Returns each published event's outcome (`null` = delivered and acknowledged).
+ * Delivered rows are acknowledged with one `acknowledgeMany` when the store has it.
+ */
+declare function flushDeferredEvents(channels: DispatchChannels, queue: DomainEvent[]): Promise<ReadonlyMap<string, Error | null>>;
+//#endregion
+export { DispatchChannels, DispatchOutcome, DispatchUnit, DurableContext, DurableEventSpec, EventDurability, FactExpectation, NonDurablePublishError, UnmanagedSessionError, dispatchDomainEvent, durableEventMeta, eventIdFor, flushDeferredEvents, requireDurableContext };

package/dist/durable-events.mjs

@@ -0,0 +1,115 @@
+//#region src/events/durable.ts
+var NonDurablePublishError = class extends Error {
+	name = "NonDurablePublishError";
+	code = "events.non_durable_publish";
+	eventType;
+	constructor(eventType, reason) {
+		super(`Durable event "${eventType}" cannot be published here: ${reason}.`);
+		this.eventType = eventType;
+	}
+};
+/** An open session with neither an outbox nor a post-commit queue: publishing leaks, dropping loses. */
+var UnmanagedSessionError = class extends Error {
+	name = "UnmanagedSessionError";
+	code = "events.unmanaged_session";
+	constructor(eventType) {
+		super(`Event "${eventType}" was emitted inside a caller-owned session with no outbox and no post-commit queue. Wire an outbox or run the write in the engine unit of work.`);
+	}
+};
+/** `${name}:v${version}:${occurrence}` — the same occurrence always yields the same id. */
+function eventIdFor(name, version, occurrence) {
+	if (typeof name !== "string" || name.length === 0) throw new TypeError("eventIdFor: event name must be a non-empty string");
+	if (!Number.isInteger(version) || version < 1) throw new TypeError(`eventIdFor(${name}): version must be a positive integer, got ${String(version)}`);
+	if (typeof occurrence !== "string" || occurrence.length === 0) throw new TypeError(`eventIdFor(${name}): occurrence must be a non-empty string, got ${typeof occurrence === "string" ? "\"\"" : typeof occurrence}`);
+	return `${name}:v${version}:${occurrence}`;
+}
+/** The meta a durable event is created with: a fixed id, and the same value as its idempotency key. */
+function durableEventMeta(name, version, occurrence) {
+	const id = eventIdFor(name, version, occurrence);
+	return {
+		id,
+		idempotencyKey: id
+	};
+}
+/** Throws unless a durable type is in a unit of work (session + transactional store) or a durable delivery. */
+function requireDurableContext(def, ctx) {
+	if (def.durability === "ephemeral") return;
+	if (!ctx.outbox) throw new NonDurablePublishError(def.name, "no outbox is wired");
+	if (ctx.deliveryOf !== void 0) return;
+	if (ctx.session === void 0) throw new NonDurablePublishError(def.name, "no unit of work is open (no session) and this is not a durable delivery");
+	if (ctx.outbox.transactionalSave !== true) throw new NonDurablePublishError(def.name, "the outbox store does not declare transactionalSave");
+}
+/**
+* Emit one domain event. The outbox save runs first, in the session, and its failure propagates.
+* In a unit of work delivery waits for {@link flushDeferredEvents}; otherwise an inline publish is
+* acknowledged so the relay does not deliver it again, and a failed one stays pending for the relay.
+*/
+async function dispatchDomainEvent(channels, unit, event, durability) {
+	requireDurableContext({
+		name: event.type,
+		durability
+	}, {
+		session: unit.session,
+		outbox: channels.outbox,
+		deliveryOf: unit.deliveryOf
+	});
+	const log = channels.logger ?? console;
+	if (channels.outbox) await channels.outbox.save(event, unit.session === void 0 ? {} : { session: unit.session });
+	else if (unit.session !== void 0 && !unit.pending) throw new UnmanagedSessionError(event.type);
+	if (unit.pending) {
+		unit.pending.push(event);
+		return "deferred";
+	}
+	if (unit.session !== void 0) return "committed";
+	if (channels.outbox && channels.dispatch === "relay") return "relay";
+	if (!channels.transport) return "no_transport";
+	try {
+		await channels.transport.publish(event);
+	} catch (err) {
+		log.error(`[${channels.label}] publish failed for ${event.type} ${event.meta.id}:`, err);
+		return "publish_failed";
+	}
+	await acknowledgeDelivered(channels, event, log);
+	return "published";
+}
+/**
+* Deliver a committed unit of work's queue. Under `'relay'` the rows are the delivery and nothing
+* is published. Returns each published event's outcome (`null` = delivered and acknowledged).
+* Delivered rows are acknowledged with one `acknowledgeMany` when the store has it.
+*/
+async function flushDeferredEvents(channels, queue) {
+	const outcomes = /* @__PURE__ */ new Map();
+	const events = queue.splice(0);
+	if (channels.outbox && channels.dispatch === "relay" || !channels.transport) return outcomes;
+	const log = channels.logger ?? console;
+	for (const event of events) {
+		try {
+			await channels.transport.publish(event);
+		} catch (err) {
+			outcomes.set(event.meta.id, err instanceof Error ? err : new Error(String(err)));
+			log.error(`[${channels.label}] publish failed for ${event.type} ${event.meta.id}:`, err);
+			continue;
+		}
+		outcomes.set(event.meta.id, null);
+	}
+	const delivered = events.filter((e) => outcomes.get(e.meta.id) === null);
+	const outbox = channels.outbox;
+	if (outbox?.acknowledgeMany && delivered.length > 0) try {
+		await outbox.acknowledgeMany(delivered.map((e) => e.meta.id));
+	} catch (err) {
+		log.error(`[${channels.label}] outbox acknowledgeMany failed for ${delivered.length} events:`, err);
+	}
+	else for (const event of delivered) await acknowledgeDelivered(channels, event, log);
+	return outcomes;
+}
+/** A failed acknowledge only risks a redelivery, which consumers absorb by id; it never fails the caller. */
+async function acknowledgeDelivered(channels, event, log) {
+	if (!channels.outbox) return;
+	try {
+		await channels.outbox.acknowledge(event.meta.id);
+	} catch (err) {
+		log.error(`[${channels.label}] outbox acknowledge failed for ${event.type} ${event.meta.id}:`, err);
+	}
+}
+//#endregion
+export { NonDurablePublishError, UnmanagedSessionError, dispatchDomainEvent, durableEventMeta, eventIdFor, flushDeferredEvents, requireDurableContext };

package/dist/events.d.mts

@@ -86,7 +86,7 @@ interface EventMeta {
    * `meta.id` (which is fresh per emit — a retry would produce a new id).
    *
    * Typical sources: HTTP `Idempotency-Key` header, outbox `dedupeKey`, or
-   * `{aggregate.type}:{aggregate.id}:{action}`. Inherited by child events.
+   * `{aggregate.type}:{aggregate.id}:{action}`. NOT inherited by child events.
    */
   idempotencyKey?: string;
   /**
@@ -215,11 +215,11 @@ declare function createEvent<T>(type: string, payload: T, meta?: Partial<EventMe
  *  - `causationId` is set to the parent's `id` (direct cause)
  *  - `correlationId` is inherited from the parent if set, else falls back
  *    to the parent's `id` (root correlation)
- *  - `userId` / `organizationId` / `source` / `idempotencyKey` are inherited
- *    when set on the parent so the whole chain stays scoped to the
- *    originating principal, tenant, emitter, and logical operation
- *  - `aggregate` is NOT inherited — child events typically belong to a
- *    different aggregate than their parent
+ *  - `userId` / `organizationId` / `source` are inherited when set on the
+ *    parent so the chain stays scoped to the originating principal, tenant
+ *    and emitter
+ *  - `idempotencyKey` and `aggregate` are NOT inherited — a child is its own
+ *    occurrence (see `@classytic/primitives/durable-events` `eventIdFor`)
  *
  * Caller-supplied `meta` wins over inherited fields — pass `{ userId: newActor }`
  * to override when a subsystem acts on behalf of a different principal.

package/dist/events.mjs

@@ -22,11 +22,11 @@ function createEvent(type, payload, meta) {
 *  - `causationId` is set to the parent's `id` (direct cause)
 *  - `correlationId` is inherited from the parent if set, else falls back
 *    to the parent's `id` (root correlation)
-*  - `userId` / `organizationId` / `source` / `idempotencyKey` are inherited
-*    when set on the parent so the whole chain stays scoped to the
-*    originating principal, tenant, emitter, and logical operation
-*  - `aggregate` is NOT inherited — child events typically belong to a
-*    different aggregate than their parent
+*  - `userId` / `organizationId` / `source` are inherited when set on the
+*    parent so the chain stays scoped to the originating principal, tenant
+*    and emitter
+*  - `idempotencyKey` and `aggregate` are NOT inherited — a child is its own
+*    occurrence (see `@classytic/primitives/durable-events` `eventIdFor`)
 *
 * Caller-supplied `meta` wins over inherited fields — pass `{ userId: newActor }`
 * to override when a subsystem acts on behalf of a different principal.
@@ -51,7 +51,6 @@ function createChildEvent(parent, type, payload, meta) {
 	if (parent.meta.userId !== void 0) inherited.userId = parent.meta.userId;
 	if (parent.meta.organizationId !== void 0) inherited.organizationId = parent.meta.organizationId;
 	if (parent.meta.source !== void 0) inherited.source = parent.meta.source;
-	if (parent.meta.idempotencyKey !== void 0) inherited.idempotencyKey = parent.meta.idempotencyKey;
 	return {
 		type,
 		payload,

package/dist/item-facts.d.mts

@@ -9,6 +9,8 @@ interface ItemStockSource {
   displayName: string;
   /** The canonical STOCK unit — what quants and moves are balanced in. */
   uom: string;
+  /** The stock unit's UoM group (`_id` or `code`); its base unit is `uom` and its rounding is the posting step. */
+  uomGroupRef?: string | undefined;
   trackingMode: TrackingMode;
   trackingPolicy?: ShelfLifePolicy | undefined;
   /**
@@ -29,6 +31,10 @@ interface ProductFacet {
   sku: string;
   displayName: string;
   uom?: string | undefined;
+  /** Fallback group for a product-only deployment; never read when an Item exists. */
+  uomGroupRef?: string | undefined;
+  /** The product declares a unit of measure, even if its group was lost on the way here. */
+  unitOfMeasureDeclared?: boolean | undefined;
   trackingMode?: TrackingMode | undefined;
   trackingPolicy?: ShelfLifePolicy | undefined;
   catchWeight?: boolean | undefined;
@@ -46,6 +52,14 @@ interface ItemStockFacts {
   trackingMode: TrackingMode;
   trackingPolicy?: ShelfLifePolicy;
   uom: string;
+  /** UoM group whose rounding a posting snaps to. Absent ⇒ the bare quantity grid. */
+  uomGroupRef?: string;
+  /**
+   * A source declared a unit of measure, so a missing `uomGroupRef` must be
+   * REFUSED by the stock engine, never read as "no rounding". Not set by `uom`
+   * alone: every Item has a `uom`.
+   */
+  unitOfMeasureDeclared?: boolean;
   catchWeight?: boolean;
   weightUom?: string;
   weight?: number;
@@ -64,6 +78,11 @@ interface ItemStockFacts {
  * `isActive` follows the ITEM when one exists: a product withdrawn from sale is
  * still stock on a shelf, whereas a retired item is not stockable at all. Taking
  * the product's flag would make unlisting a product silently orphan its stock.
+ *
+ * `uomGroupRef` follows the ITEM when one exists. A product group under an Item
+ * that declares none is never borrowed (its step is in a unit the Item may not
+ * count in): the facts carry `unitOfMeasureDeclared: true` and no group, so the
+ * stock engine refuses the posting until the Item declares its own.
  */
 declare function resolveStockFacts(input: {
   item?: ItemStockSource | null | undefined;

package/dist/item-facts.mjs

@@ -2,6 +2,7 @@
 /** Unit assumed when neither side declares one. A deployment-wide guess, and a bad one — set a real `uom` on the Item. */
 const FALLBACK_UOM = "unit";
 const defined = (key, value) => value === void 0 ? {} : { [key]: value };
+const declaresGroup = (p) => !!p && (p.uomGroupRef !== void 0 || p.unitOfMeasureDeclared === true);
 /**
 * Merge an Item with its Product facet.
 *
@@ -13,6 +14,11 @@ const defined = (key, value) => value === void 0 ? {} : { [key]: value };
 * `isActive` follows the ITEM when one exists: a product withdrawn from sale is
 * still stock on a shelf, whereas a retired item is not stockable at all. Taking
 * the product's flag would make unlisting a product silently orphan its stock.
+*
+* `uomGroupRef` follows the ITEM when one exists. A product group under an Item
+* that declares none is never borrowed (its step is in a unit the Item may not
+* count in): the facts carry `unitOfMeasureDeclared: true` and no group, so the
+* stock engine refuses the posting until the Item declares its own.
 */
 function resolveStockFacts(input) {
 	const { item, product } = input;
@@ -24,6 +30,8 @@ function resolveStockFacts(input) {
 			sku: p.sku,
 			displayName: p.displayName,
 			uom: p.uom ?? FALLBACK_UOM,
+			...defined("uomGroupRef", p.uomGroupRef),
+			...p.unitOfMeasureDeclared === true ? { unitOfMeasureDeclared: true } : {},
 			trackingMode: p.trackingMode ?? "none",
 			...defined("trackingPolicy", p.trackingPolicy),
 			...defined("catchWeight", p.catchWeight),
@@ -39,6 +47,8 @@ function resolveStockFacts(input) {
 		sku: product?.sku ?? item.sku,
 		displayName: product?.displayName ?? item.displayName,
 		uom: item.uom,
+		...defined("uomGroupRef", item.uomGroupRef),
+		...item.uomGroupRef === void 0 && declaresGroup(product) ? { unitOfMeasureDeclared: true } : {},
 		trackingMode: item.trackingMode,
 		...defined("trackingPolicy", item.trackingPolicy),
 		...defined("catchWeight", item.catchWeight),

package/dist/memory-outbox.d.mts

@@ -48,6 +48,7 @@ declare class MemoryOutboxStore implements OutboxStore {
   claimPending(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
   claimPendingFenced(options?: OutboxClaimOptions): Promise<OutboxClaimedEvent[]>;
   acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
+  acknowledgeMany(eventIds: readonly string[]): Promise<void>;
   fail(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
   getDeadLettered(limit: number): Promise<DeadLetteredEvent[]>;
   purge(olderThanMs: number): Promise<number>;

package/dist/memory-outbox.mjs

@@ -1,4 +1,4 @@
-import { InvalidOutboxEventError, OutboxOwnershipError } from "./outbox.mjs";
+import { InvalidOutboxEventError, OutboxConflictError, OutboxOwnershipError, outboxPayloadFingerprint } from "./outbox.mjs";
 //#region src/events/memory-outbox.ts
 const DEFAULT_LEASE_MS = 3e4;
 var MemoryOutboxStore = class {
@@ -29,6 +29,11 @@ var MemoryOutboxStore = class {
 	async save(event, options) {
 		if (!event?.type || typeof event.type !== "string") throw new InvalidOutboxEventError("event.type is required");
 		if (!event.meta?.id || typeof event.meta.id !== "string") throw new InvalidOutboxEventError("event.meta.id is required");
+		const existing = this.entries.find((e) => e.event.meta.id === event.meta.id);
+		if (existing) {
+			if (outboxPayloadFingerprint(existing.event) === outboxPayloadFingerprint(event)) return;
+			throw new OutboxConflictError(event.meta.id, event.type);
+		}
 		if (options?.dedupeKey) {
 			if (this.seenDedupeKeys.has(options.dedupeKey)) return;
 			this.seenDedupeKeys.add(options.dedupeKey);
@@ -90,6 +95,16 @@ var MemoryOutboxStore = class {
 		entry.deliveredAt = Date.now();
 		entry.leaseOwner = null;
 	}
+	async acknowledgeMany(eventIds) {
+		const ids = new Set(eventIds);
+		const now = Date.now();
+		for (const entry of this.entries) {
+			if (!ids.has(entry.event.meta.id) || entry.status === "delivered") continue;
+			entry.status = "delivered";
+			entry.deliveredAt = now;
+			entry.leaseOwner = null;
+		}
+	}
 	async fail(eventId, error, options) {
 		const entry = this.entries.find((e) => e.event.meta.id === eventId);
 		if (!entry) return;

package/dist/monetization.d.mts

@@ -297,6 +297,8 @@ declare function unitPriceOf(m: Monetization): Money | null;
  * `defaultPassOf` picked.
  */
 declare function compareAtPriceOf(m: Monetization): Money | null;
+/** On sale: a compare-at price above the selling price, same currency. The ONE on-sale predicate. */
+declare function isOnSale(m: Monetization): boolean;
 /**
  * `@classytic/revenue`'s coarse wire enum. `purchase` is the paid-once case that
  * the rest of the ecosystem calls `one_time`. Kept as its own type so revenue's
@@ -316,4 +318,4 @@ declare function toRevenueMonetizationType(kind: MonetizationKind): RevenueMonet
 /** Revenue wire type → canonical kind (`purchase` → `one_time`). */
 declare function fromRevenueMonetizationType(type: RevenueMonetizationType): MonetizationKind;
 //#endregion
-export { AccessPass, BundleMonetization, DurationUnit, FreeMonetization, MONETIZATION_KINDS, Monetization, MonetizationKind, MoneyByCurrency, OneTimeMonetization, OneTimePricing, PassMonetization, PriceTier, RevenueMonetizationType, SubscriptionMonetization, SubscriptionPlan, UPFRONT_COLLECTION_MODES, UpfrontCollectionMode, UsageMonetization, UsageRating, UsageTier, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+export { AccessPass, BundleMonetization, DurationUnit, FreeMonetization, MONETIZATION_KINDS, Monetization, MonetizationKind, MoneyByCurrency, OneTimeMonetization, OneTimePricing, PassMonetization, PriceTier, RevenueMonetizationType, SubscriptionMonetization, SubscriptionPlan, UPFRONT_COLLECTION_MODES, UpfrontCollectionMode, UsageMonetization, UsageRating, UsageTier, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOnSale, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };

package/dist/monetization.mjs

@@ -164,6 +164,12 @@ function compareAtPriceOf(m) {
 	if (m.type === "pass") return defaultPassOf(m)?.compareAtPrice ?? null;
 	return null;
 }
+/** On sale: a compare-at price above the selling price, same currency. The ONE on-sale predicate. */
+function isOnSale(m) {
+	const compareAt = compareAtPriceOf(m);
+	const price = unitPriceOf(m);
+	return compareAt !== null && price !== null && compareAt.currency === price.currency && compareAt.amount > price.amount;
+}
 /**
 * Canonical kind → revenue wire type. Everything that is not `free` or
 * `subscription` settles as a `purchase` in revenue's ledger vocabulary
@@ -184,4 +190,4 @@ function fromRevenueMonetizationType(type) {
 	return "one_time";
 }
 //#endregion
-export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };
+export { MONETIZATION_KINDS, UPFRONT_COLLECTION_MODES, approxTermDays, compareAtPriceOf, defaultPassOf, fromRevenueMonetizationType, isBundleMonetization, isFreeMonetization, isMonetizationKind, isOnSale, isOneTimeMonetization, isPassMonetization, isSubscriptionMonetization, isUpfrontCollectionMode, isUsageMonetization, monetizationKindOf, toRevenueMonetizationType, unitPriceOf };