@classytic/primitives 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.30.0 — 2026-10-11
+
+### 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/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 };

package/dist/outbox.d.mts

@@ -141,6 +141,23 @@ declare class OutboxOwnershipError extends Error {
   readonly currentOwner: string | null;
   constructor(eventId: string, attemptedBy: string, currentOwner: string | null);
 }
+/**
+ * Thrown by `save` when a row with this event id already exists with a DIFFERENT payload.
+ * A same-id, same-payload save is an idempotent success; a different payload is two
+ * occurrences minted onto one id, and dropping either one loses money silently.
+ */
+declare class OutboxConflictError extends Error {
+  readonly name = "OutboxConflictError";
+  readonly code = "outbox.conflict";
+  readonly eventId: string;
+  readonly eventType: string;
+  constructor(eventId: string, eventType: string);
+}
+/**
+ * Order-independent fingerprint of an event payload as it travels (JSON: `Date` becomes its
+ * ISO string, `undefined` drops). Stores compare it on a duplicate id; see {@link OutboxConflictError}.
+ */
+declare function outboxPayloadFingerprint(event: DomainEvent): string;
 /** Thrown when an event missing `type` or `meta.id` is passed to the outbox. */
 declare class InvalidOutboxEventError extends Error {
   readonly name = "InvalidOutboxEventError";
@@ -235,7 +252,8 @@ interface OutboxStore {
   /**
    * Save an event to the outbox (typically called inside a business
    * transaction). MUST reject events missing `type` or `meta.id` — throw
-   * rather than persist.
+   * rather than persist. A second save of an existing `meta.id` is a no-op when
+   * the payload matches, and throws {@link OutboxConflictError} when it does not.
    */
   save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
   /**
@@ -267,6 +285,12 @@ interface OutboxStore {
    * @throws {@link OutboxOwnershipError} on ownership mismatch
    */
   acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
+  /**
+   * Mark every listed event delivered in ONE write — what a unit of work's post-commit flush
+   * calls, so N delivered events cost one command, not N. Unleased rows only (no fencing);
+   * unknown or already-delivered ids are ignored.
+   */
+  acknowledgeMany?(eventIds: readonly string[]): Promise<void>;
   /**
    * Record a relay failure. When implemented, the relay calls this instead
    * of stopping the batch — enables retry scheduling and DLQ.
@@ -335,4 +359,4 @@ interface OutboxStore {
   oldestPendingAgeMs?(): Promise<number | null>;
 }
 //#endregion
-export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxClaimedEvent, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStatus, OutboxStore, OutboxWriteOptions };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxClaimedEvent, OutboxConflictError, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStatus, OutboxStore, OutboxWriteOptions, outboxPayloadFingerprint };

package/dist/outbox.mjs

@@ -1,5 +1,23 @@
+import { canonicalDigest } from "./canonical.mjs";
 //#region src/events/outbox.ts
 /**
+* Transactional outbox CONTRACT — the canonical owner. `@classytic/arc`
+* re-exports this; it keeps no copy of its own.
+*
+* Contract surface only: {@link OutboxStore}, its option types, the
+* {@link OutboxFailurePolicy} retry/DLQ contract, and the error classes.
+*
+* The split exists because a domain package MUST NOT peer-dep arc. Owning the
+* contract here lets a package write `implements OutboxStore` and hand the
+* result to arc's `new EventOutbox({ store })`, and since arc re-exports these
+* exact classes, `instanceof OutboxOwnershipError` works across the boundary.
+*
+* Runtimes live elsewhere: the DURABLE one (`EventOutbox` relay, Mongo store,
+* backoff, Fastify wiring) in `@classytic/arc/events`; the dependency-free
+* in-process reference (kernel bus + memory store, for tests/dev) in
+* `@classytic/primitives/event-infra`.
+*/
+/**
 * Thrown by a store when `acknowledge` / `fail` is called by a consumer that
 * does not own the event's current lease.
 *
@@ -19,6 +37,30 @@ var OutboxOwnershipError = class extends Error {
 		this.currentOwner = currentOwner;
 	}
 };
+/**
+* Thrown by `save` when a row with this event id already exists with a DIFFERENT payload.
+* A same-id, same-payload save is an idempotent success; a different payload is two
+* occurrences minted onto one id, and dropping either one loses money silently.
+*/
+var OutboxConflictError = class extends Error {
+	name = "OutboxConflictError";
+	code = "outbox.conflict";
+	eventId;
+	eventType;
+	constructor(eventId, eventType) {
+		super(`Outbox already holds event "${eventId}" (${eventType}) with a different payload — two occurrences share one id. Derive the occurrence from the aggregate id plus the step.`);
+		this.eventId = eventId;
+		this.eventType = eventType;
+	}
+};
+/**
+* Order-independent fingerprint of an event payload as it travels (JSON: `Date` becomes its
+* ISO string, `undefined` drops). Stores compare it on a duplicate id; see {@link OutboxConflictError}.
+*/
+function outboxPayloadFingerprint(event) {
+	const wire = JSON.parse(JSON.stringify(event.payload ?? null));
+	return canonicalDigest(wire);
+}
 /** Thrown when an event missing `type` or `meta.id` is passed to the outbox. */
 var InvalidOutboxEventError = class extends Error {
 	name = "InvalidOutboxEventError";
@@ -90,4 +132,4 @@ const OUTBOX_STATUSES = [
 	"dead_letter"
 ];
 //#endregion
-export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxOwnershipError };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxConflictError, OutboxOwnershipError, outboxPayloadFingerprint };

package/dist/split-allocation.d.mts

@@ -60,7 +60,7 @@ interface SplitResult {
   readonly method: SplitMethod;
   readonly parts: readonly SplitPart[];
 }
-type SplitAllocationErrorCode = 'INVALID_TOTAL' | 'EMPTY_SUBJECTS' | 'INVALID_WEIGHT' | 'INVALID_PERCENT' | 'ZERO_WEIGHT_SUM' | 'DUPLICATE_SUBJECT_ID';
+type SplitAllocationErrorCode = 'INVALID_TOTAL' | 'EMPTY_SUBJECTS' | 'INVALID_WEIGHT' | 'INVALID_PERCENT' | 'ZERO_WEIGHT_SUM' | 'DUPLICATE_SUBJECT_ID' | 'DISCOUNT_EXCEEDS_BASE';
 declare class SplitAllocationError extends Error {
   readonly name = "SplitAllocationError";
   readonly code: SplitAllocationErrorCode;
@@ -80,5 +80,23 @@ declare class SplitAllocationError extends Error {
 declare function allocate(total: number, subjects: readonly SplitSubject[], method: SplitMethod): SplitResult;
 /** True if `sum(parts[i].amount) === result.total`. Useful as an assertion in host code. */
 declare function isBalanced(result: SplitResult): boolean;
+/** A line a document-level discount may be spread over. */
+interface DiscountSubject {
+  readonly id: string;
+  /** The line's value before the discount, integer minor units (non-negative). */
+  readonly weight: number;
+  /** `false` for a line the discount was never computed on (a delivery charge, an auto-added fee). Absent ⇒ eligible. */
+  readonly discountable?: boolean;
+}
+/**
+ * THE discount allocation: spread a document-level discount over its eligible lines, by value,
+ * exact largest remainder. Every document that splits one discount — the order, its invoice,
+ * its credit notes, a return's value — calls this, so they agree to the minor unit.
+ *
+ * Returns a FULL map in input order: every subject id, `0` for an ineligible or zero-weight one.
+ * `0` discount allocates zeros; a discount equal to the eligible base allocates all of it; a
+ * discount above it throws `DISCOUNT_EXCEEDS_BASE` — the figures disagree.
+ */
+declare function allocateDiscount(discount: number, subjects: readonly DiscountSubject[]): ReadonlyMap<string, number>;
 //#endregion
-export { SplitAllocationError, SplitAllocationErrorCode, SplitMethod, SplitPart, SplitResult, SplitSubject, allocate, isBalanced };
+export { DiscountSubject, SplitAllocationError, SplitAllocationErrorCode, SplitMethod, SplitPart, SplitResult, SplitSubject, allocate, allocateDiscount, isBalanced };

package/dist/split-allocation.mjs

@@ -88,6 +88,7 @@ function resolveWeights(subjects, method) {
 function distribute(total, weights) {
 	const weightSum = weights.reduce((a, b) => a + b, 0);
 	if (weightSum === 0) return weights.map(() => 0);
+	if (weights.every(Number.isSafeInteger) && Number.isSafeInteger(weightSum)) return distributeExact(total, weights, weightSum);
 	const raw = weights.map((w) => total * w / weightSum);
 	const floored = raw.map((r) => Math.floor(r));
 	const residue = total - floored.reduce((a, b) => a + b, 0);
@@ -107,9 +108,64 @@ function distribute(total, weights) {
 	}
 	return result;
 }
+/**
+* Largest remainder in exact integer arithmetic, for integer weights (minor-unit amounts). Shares
+* and remainders are compared as BigInt quotients of one denominator, so neither the floor nor the
+* remainder ranking can drift once `total × weight` passes 2^53.
+*/
+function distributeExact(total, weights, weightSum) {
+	const t = BigInt(total);
+	const d = BigInt(weightSum);
+	const shares = weights.map((w) => {
+		const n = t * BigInt(w);
+		return {
+			floor: n / d,
+			rem: n % d
+		};
+	});
+	const result = shares.map((s) => Number(s.floor));
+	const residue = total - result.reduce((a, b) => a + b, 0);
+	const order = shares.map((s, i) => ({
+		i,
+		rem: s.rem
+	})).sort((a, b) => a.rem === b.rem ? a.i - b.i : a.rem > b.rem ? -1 : 1);
+	for (let k = 0; k < residue; k++) {
+		const entry = order[k];
+		if (entry === void 0) throw new Error("split-allocation invariant: residue exceeds the subject count");
+		result[entry.i] = (result[entry.i] ?? 0) + 1;
+	}
+	return result;
+}
 /** True if `sum(parts[i].amount) === result.total`. Useful as an assertion in host code. */
 function isBalanced(result) {
 	return result.parts.reduce((acc, p) => acc + p.amount, 0) === result.total;
 }
+/**
+* THE discount allocation: spread a document-level discount over its eligible lines, by value,
+* exact largest remainder. Every document that splits one discount — the order, its invoice,
+* its credit notes, a return's value — calls this, so they agree to the minor unit.
+*
+* Returns a FULL map in input order: every subject id, `0` for an ineligible or zero-weight one.
+* `0` discount allocates zeros; a discount equal to the eligible base allocates all of it; a
+* discount above it throws `DISCOUNT_EXCEEDS_BASE` — the figures disagree.
+*/
+function allocateDiscount(discount, subjects) {
+	if (!Number.isInteger(discount) || discount < 0) throw new SplitAllocationError("INVALID_TOTAL", `discount must be a non-negative integer, got ${discount}`);
+	const out = /* @__PURE__ */ new Map();
+	for (const s of subjects) {
+		if (out.has(s.id)) throw new SplitAllocationError("DUPLICATE_SUBJECT_ID", `duplicate subject id: ${s.id}`);
+		if (!Number.isFinite(s.weight) || s.weight < 0) throw new SplitAllocationError("INVALID_WEIGHT", `subject ${s.id}: weight must be a non-negative number`);
+		out.set(s.id, 0);
+	}
+	const eligible = subjects.filter((s) => s.discountable !== false && s.weight > 0);
+	const base = eligible.reduce((sum, s) => sum + s.weight, 0);
+	if (discount > base) throw new SplitAllocationError("DISCOUNT_EXCEEDS_BASE", `discount ${discount} exceeds the discountable base ${base}`);
+	if (discount === 0) return out;
+	for (const part of allocate(discount, eligible.map((s) => ({
+		id: s.id,
+		weight: s.weight
+	})), "by-value").parts) out.set(part.id, part.amount);
+	return out;
+}
 //#endregion
-export { SplitAllocationError, allocate, isBalanced };
+export { SplitAllocationError, allocate, allocateDiscount, isBalanced };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -96,6 +96,11 @@
       "types": "./dist/memory-outbox.d.mts",
       "default": "./dist/memory-outbox.mjs"
     },
+    "./durable-events": {
+      "@classytic/source": "./src/events/durable.ts",
+      "types": "./dist/durable-events.d.mts",
+      "default": "./dist/durable-events.mjs"
+    },
     "./event-infra": {
       "@classytic/source": "./src/events/event-infra.ts",
       "types": "./dist/event-infra.d.mts",