@classytic/primitives 0.28.0 → 0.30.0

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.
@@ -294,5 +294,43 @@ declare function createScopedEvent<T>(source: string, type: string, payload: T,
  *   - exact match otherwise
  */
 declare function matchEventPattern(pattern: string, type: string): boolean;
+/**
+ * Subscriptions indexed for dispatch — the same answer as scanning every pattern with
+ * `matchEventPattern` (same values, same order: first occurrence by pattern registration,
+ * deduped), in amortized O(1) per event instead of O(patterns).
+ *
+ * A wildcard can only match at a separator, so an event name has at most one candidate prefix
+ * per `.`/`:` — a lookup walks its own name, never the subscription table. Resolved lists are
+ * memoized per name (names are a small, closed set) and dropped on any add/remove.
+ */
+interface EventRouter<T> {
+  add(pattern: string, value: T): void;
+  /** `true` when the pair was registered. A pattern left with no values is dropped. */
+  remove(pattern: string, value: T): boolean;
+  /** Every value whose pattern matches `type` — registration order, each value once. */
+  route(type: string): readonly T[];
+  clear(): void;
+  /** Registered patterns, in registration order. */
+  patterns(): IterableIterator<[string, ReadonlySet<T>]>;
+  /** Number of registered patterns. */
+  readonly size: number;
+}
+declare function createEventRouter<T>(): EventRouter<T>;
+/** One difference between two versions of an event's payload schema. */
+interface EventSchemaChange {
+  /** Dotted path to the field (`''` = the payload root; `[]` = array items; `{}` = record values). */
+  readonly path: string;
+  readonly kind: 'added' | 'removed' | 'now-optional' | 'type-widened' | 'type-narrowed' | 'values-widened' | 'values-narrowed';
+  /** Would a consumer written against the OLD schema break on a payload valid under the NEW one? */
+  readonly breaking: boolean;
+  readonly detail: string;
+}
+/**
+ * What changed between two versions of an event payload's JSON Schema, and whether each change
+ * breaks an existing CONSUMER (forward compatibility: the producer evolves, old consumers keep
+ * reading). Payloads are open for extension — adding a field never breaks, whatever
+ * `additionalProperties` says, because consumers ignore fields they do not know.
+ */
+declare function diffEventSchema(before: unknown, after: unknown, path?: string): EventSchemaChange[];
 //#endregion
-export { DeadLetteredEvent, DomainEvent, EventHandler, EventLogger, EventMeta, EventScopeContext, EventTransport, PublishManyResult, createChildEvent, createEvent, createScopedEvent, matchEventPattern, scopedEventMeta };
+export { DeadLetteredEvent, DomainEvent, EventHandler, EventLogger, EventMeta, EventRouter, EventSchemaChange, EventScopeContext, EventTransport, PublishManyResult, createChildEvent, createEvent, createEventRouter, createScopedEvent, diffEventSchema, matchEventPattern, scopedEventMeta };

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,
@@ -127,5 +126,173 @@ function randomEventId() {
 		return (c === "x" ? r : r & 3 | 8).toString(16);
 	});
 }
+/** Past this many distinct names the memo is reset — dynamic names must not grow it without bound. */
+const ROUTE_MEMO_LIMIT = 4096;
+function createEventRouter() {
+	const byPattern = /* @__PURE__ */ new Map();
+	const order = /* @__PURE__ */ new Map();
+	let seq = 0;
+	const memo = /* @__PURE__ */ new Map();
+	const resolve = (type) => {
+		const hits = [];
+		if (byPattern.has("*")) hits.push("*");
+		if (byPattern.has(type)) hits.push(type);
+		for (let i = 0; i < type.length; i++) {
+			const c = type.charCodeAt(i);
+			if (c !== 46 && c !== 58) continue;
+			const wildcard = `${type.slice(0, i + 1)}*`;
+			if (wildcard !== type && byPattern.has(wildcard)) hits.push(wildcard);
+		}
+		if (hits.length > 1) hits.sort((a, b) => order.get(a) - order.get(b));
+		const seen = /* @__PURE__ */ new Set();
+		for (const pattern of hits) for (const v of byPattern.get(pattern)) seen.add(v);
+		return Object.freeze([...seen]);
+	};
+	return {
+		add(pattern, value) {
+			let set = byPattern.get(pattern);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				byPattern.set(pattern, set);
+				order.set(pattern, seq++);
+			}
+			if (!set.has(value)) {
+				set.add(value);
+				memo.clear();
+			}
+		},
+		remove(pattern, value) {
+			const set = byPattern.get(pattern);
+			if (!set?.delete(value)) return false;
+			if (set.size === 0) {
+				byPattern.delete(pattern);
+				order.delete(pattern);
+			}
+			memo.clear();
+			return true;
+		},
+		route(type) {
+			const cached = memo.get(type);
+			if (cached) return cached;
+			const resolved = resolve(type);
+			if (memo.size >= ROUTE_MEMO_LIMIT) memo.clear();
+			memo.set(type, resolved);
+			return resolved;
+		},
+		clear() {
+			byPattern.clear();
+			order.clear();
+			memo.clear();
+		},
+		patterns: () => byPattern.entries(),
+		get size() {
+			return byPattern.size;
+		}
+	};
+}
+const jsonType = (v) => v === null ? "null" : Array.isArray(v) ? "array" : Number.isInteger(v) ? "integer" : typeof v;
+/** The JSON types a node admits; `null` means unconstrained. */
+function typesOf(node) {
+	const branches = node.anyOf ?? node.oneOf;
+	if (branches) {
+		const all = /* @__PURE__ */ new Set();
+		for (const b of branches) {
+			const t = typesOf(b);
+			if (t === null) return null;
+			for (const x of t) all.add(x);
+		}
+		return all;
+	}
+	if (node.const !== void 0) return /* @__PURE__ */ new Set([jsonType(node.const)]);
+	if (node.enum) return new Set(node.enum.map(jsonType));
+	if (node.type === void 0) return null;
+	return new Set([node.type].flat());
+}
+/** The finite values a node admits (`enum` / `const`), or `null` when open. */
+function valuesOf(node) {
+	if (node.const !== void 0) return /* @__PURE__ */ new Set([JSON.stringify(node.const)]);
+	if (node.enum) return new Set(node.enum.map((v) => JSON.stringify(v)));
+	return null;
+}
+/** `integer` is a kind of `number`. */
+const admits = (types, t) => types.has(t) || t === "integer" && types.has("number");
+/**
+* What changed between two versions of an event payload's JSON Schema, and whether each change
+* breaks an existing CONSUMER (forward compatibility: the producer evolves, old consumers keep
+* reading). Payloads are open for extension — adding a field never breaks, whatever
+* `additionalProperties` says, because consumers ignore fields they do not know.
+*/
+function diffEventSchema(before, after, path = "") {
+	const a = before ?? {};
+	const b = after ?? {};
+	const changes = [];
+	const at = (field) => path ? `${path}.${field}` : field;
+	const ta = typesOf(a);
+	const tb = typesOf(b);
+	if (tb === null ? ta !== null : ta !== null && [...tb].some((t) => !admits(ta, t))) changes.push({
+		path,
+		kind: "type-widened",
+		breaking: true,
+		detail: `${ta ? [...ta].join("|") : "any"} → ${tb ? [...tb].join("|") : "any"}`
+	});
+	else if (ta !== null && tb !== null && [...ta].some((t) => !admits(tb, t))) changes.push({
+		path,
+		kind: "type-narrowed",
+		breaking: false,
+		detail: `${[...ta].join("|")} → ${[...tb].join("|")}`
+	});
+	const va = valuesOf(a);
+	const vb = valuesOf(b);
+	if (va !== null) {
+		const added = vb === null ? ["(any)"] : [...vb].filter((v) => !va.has(v));
+		const removed = vb === null ? [] : [...va].filter((v) => !vb.has(v));
+		if (added.length > 0) changes.push({
+			path,
+			kind: "values-widened",
+			breaking: true,
+			detail: `new values ${added.join(", ")}`
+		});
+		if (removed.length > 0) changes.push({
+			path,
+			kind: "values-narrowed",
+			breaking: false,
+			detail: `dropped ${removed.join(", ")}`
+		});
+	}
+	const pa = a.properties ?? {};
+	const pb = b.properties ?? {};
+	const ra = new Set(a.required ?? []);
+	const rb = new Set(b.required ?? []);
+	for (const field of Object.keys(pa)) {
+		if (!(field in pb)) {
+			const required = ra.has(field);
+			changes.push({
+				path: at(field),
+				kind: "removed",
+				breaking: required,
+				detail: required ? "required field removed" : "optional field removed"
+			});
+			continue;
+		}
+		if (ra.has(field) && !rb.has(field)) changes.push({
+			path: at(field),
+			kind: "now-optional",
+			breaking: true,
+			detail: "was required"
+		});
+		changes.push(...diffEventSchema(pa[field], pb[field], at(field)));
+	}
+	for (const field of Object.keys(pb)) if (!(field in pa)) changes.push({
+		path: at(field),
+		kind: "added",
+		breaking: false,
+		detail: rb.has(field) ? "required" : "optional"
+	});
+	if (a.items || b.items) changes.push(...diffEventSchema(a.items, b.items, `${path}[]`));
+	const aa = typeof a.additionalProperties === "object" ? a.additionalProperties : void 0;
+	const ba = typeof b.additionalProperties === "object" ? b.additionalProperties : void 0;
+	if (aa || ba) changes.push(...diffEventSchema(aa, ba, `${path}{}`));
+	return changes;
+}
 //#endregion
-export { createChildEvent, createEvent, createScopedEvent, matchEventPattern, scopedEventMeta };
+export { createChildEvent, createEvent, createEventRouter, createScopedEvent, diffEventSchema, matchEventPattern, scopedEventMeta };

package/dist/idempotency.d.mts

@@ -1,5 +1,9 @@
 //#region src/workflow/idempotency.d.ts
 /**
+ * @deprecated Moved to `@classytic/repo-core/idempotency` — the claim contract plus its store
+ * port, `runIdempotent`, the reference store and the conformance suite, beside `./lock`. This
+ * copy has no consumers and is removed in the next minor.
+ *
  * Idempotency claim + lease — the CONTRACT, not the store.
  *
  * ## Why this exists

package/dist/idempotency.mjs

@@ -1,6 +1,10 @@
 import { canonicalDigest, canonicalJson } from "./canonical.mjs";
 //#region src/workflow/idempotency.ts
 /**
+* @deprecated Moved to `@classytic/repo-core/idempotency` — the claim contract plus its store
+* port, `runIdempotent`, the reference store and the conformance suite, beside `./lock`. This
+* copy has no consumers and is removed in the next minor.
+*
 * Idempotency claim + lease — the CONTRACT, not the store.
 *
 * ## Why this exists

package/dist/item-stock.d.mts

@@ -0,0 +1,43 @@
+import { SkuFields, StockKey, StockKeySource } from "./item-identity.mjs";
+//#region src/inventory/item-stock.d.ts
+/** One stock row as the summary reads it. */
+interface StockRow {
+  readonly quantity?: number;
+  /** Explicitly `false` deactivates the row. Absent means active. */
+  readonly isActive?: boolean;
+  /** Display cost of one unit, as the source reports it. */
+  readonly costPrice?: number;
+  /** On-hand value at the source's valuation, integer MINOR units; absent = unvalued. */
+  readonly valueMinor?: number;
+  /** Units at or below which the item reads as low (the item-level row's). */
+  readonly reorderPoint?: number;
+}
+/** What a reader shows for an item's stock in one place. */
+interface ItemStock {
+  quantity: number;
+  inStock: boolean;
+  lowStock: boolean;
+  valueMinor?: number;
+  /** Per variant LABEL — a projection of the same rows, not a second source. */
+  variants?: Array<{
+    sku: string;
+    quantity: number;
+    costPrice?: number;
+  }>;
+}
+/** The item shape the summary reads: its id and its variants. */
+interface StockableItem extends StockKeySource {
+  readonly variants?: ReadonlyArray<SkuFields & {
+    readonly sku: string;
+    readonly isActive?: boolean;
+  }> | null;
+}
+/**
+ * The item's stock. `rowOf(null)` is the item-level row (filed under the item's own id);
+ * `rowOf(key)` the row filed under one variant's stock key.
+ */
+declare function itemStockOf(item: StockableItem, rowOf: (stockKey: StockKey | null) => StockRow | undefined, options: {
+  readonly defaultReorderPoint: number;
+}): ItemStock;
+//#endregion
+export { ItemStock, StockRow, StockableItem, itemStockOf };

package/dist/item-stock.mjs

@@ -0,0 +1,67 @@
+import { stockKeyFor } from "./item-identity.mjs";
+//#region src/inventory/item-stock.ts
+/**
+* An item's stock in one place (a branch), from the rows its stock source files under stock keys —
+* the ONE summary every reader shows: the server's product reads and an offline till alike.
+*
+*   itemStockOf(product, (key) => rows.get(key ?? productId), { defaultReorderPoint: 10 })
+*
+* Rows are keyed by STOCK KEY (`stockKeyFor`), and a row reached by two lookups is counted once —
+* a sole variant's key IS the product id, so summing lookups instead of rows doubles it.
+*/
+/**
+* The item's stock. `rowOf(null)` is the item-level row (filed under the item's own id);
+* `rowOf(key)` the row filed under one variant's stock key.
+*/
+function itemStockOf(item, rowOf, options) {
+	const itemId = String(item._id);
+	const variants = item.variants ?? [];
+	const keyOf = (variant) => stockKeyFor({
+		_id: itemId,
+		variants
+	}, {
+		kind: "variant",
+		variant
+	});
+	const rows = /* @__PURE__ */ new Map();
+	const itemRow = rowOf(null);
+	if (itemRow) rows.set(itemId, itemRow);
+	for (const variant of variants) {
+		if (variant.isActive === false) continue;
+		const key = keyOf(variant);
+		const row = rowOf(key);
+		if (!row && rows.has(key)) continue;
+		rows.set(key, row);
+	}
+	let quantity = 0;
+	let valueMinor = 0;
+	for (const row of rows.values()) {
+		if (row?.isActive === false) continue;
+		const rowQuantity = row?.quantity ?? 0;
+		quantity += rowQuantity;
+		if (rowQuantity > 0) valueMinor = row?.valueMinor === void 0 || valueMinor === void 0 ? void 0 : valueMinor + row.valueMinor;
+	}
+	const variantStocks = [];
+	for (const variant of variants) {
+		if (variant.isActive === false) continue;
+		const key = keyOf(variant);
+		if (!rows.has(key)) continue;
+		const row = rows.get(key);
+		if (row?.isActive === false) continue;
+		variantStocks.push({
+			sku: variant.sku,
+			quantity: row?.quantity ?? 0,
+			...row?.costPrice !== void 0 ? { costPrice: row.costPrice } : {}
+		});
+	}
+	const reorderPoint = itemRow?.reorderPoint ?? options.defaultReorderPoint;
+	return {
+		quantity,
+		inStock: quantity > 0,
+		lowStock: quantity > 0 && quantity <= reorderPoint,
+		...quantity > 0 && valueMinor !== void 0 ? { valueMinor } : {},
+		...variantStocks.length ? { variants: variantStocks } : {}
+	};
+}
+//#endregion
+export { itemStockOf };

package/dist/legal-form.d.mts

@@ -0,0 +1,12 @@
+//#region src/identity/legal-form.d.ts
+/**
+ * The legal form of a person or entity — what the law treats it as, for the reporting company and its
+ * counterparties alike. A sole proprietorship is an `individual`: the business has no legal personality
+ * of its own. Country packs decide what follows from a form (equity accounts, the year-end close, tax).
+ */
+declare const LEGAL_FORMS: readonly ["individual", "partnership", "company", "cooperative", "nonprofit", "government"];
+type LegalForm = (typeof LEGAL_FORMS)[number];
+declare const LEGAL_FORM_LABELS: Readonly<Record<LegalForm, string>>;
+declare function isLegalForm(value: unknown): value is LegalForm;
+//#endregion
+export { LEGAL_FORMS, LEGAL_FORM_LABELS, LegalForm, isLegalForm };

package/dist/legal-form.mjs

@@ -0,0 +1,27 @@
+//#region src/identity/legal-form.ts
+/**
+* The legal form of a person or entity — what the law treats it as, for the reporting company and its
+* counterparties alike. A sole proprietorship is an `individual`: the business has no legal personality
+* of its own. Country packs decide what follows from a form (equity accounts, the year-end close, tax).
+*/
+const LEGAL_FORMS = [
+	"individual",
+	"partnership",
+	"company",
+	"cooperative",
+	"nonprofit",
+	"government"
+];
+const LEGAL_FORM_LABELS = {
+	individual: "Individual / sole proprietorship",
+	partnership: "Partnership firm",
+	company: "Company",
+	cooperative: "Cooperative society",
+	nonprofit: "Nonprofit / NGO / trust",
+	government: "Government body"
+};
+function isLegalForm(value) {
+	return typeof value === "string" && LEGAL_FORMS.includes(value);
+}
+//#endregion
+export { LEGAL_FORMS, LEGAL_FORM_LABELS, isLegalForm };

package/dist/line-settlement.d.mts

@@ -0,0 +1,70 @@
+import { Result } from "./result.mjs";
+//#region src/inventory/line-settlement.d.ts
+/**
+ * A document line's quantity, split into OUTCOME buckets — the one definition
+ * of "how much of this line is still open".
+ *
+ * Every kernel that moves goods against a document asks this: an order line is
+ * fulfilled / returned / canceled, a transfer line is received / returned /
+ * written off, a purchase line is received / rejected. The buckets are the
+ * kernel's vocabulary; the arithmetic, the over-settlement guard and the state
+ * derivation are this file's, so no two kernels can answer differently.
+ *
+ * Quantities are whole units. A bucket that is absent counts as zero.
+ */
+interface SettlementLine<B extends string> {
+  /** What the line promised to move. */
+  readonly quantity: number;
+  /** What has been settled so far, per outcome. */
+  readonly settled: Readonly<Partial<Record<B, number>>>;
+}
+type SettlementState = "open" | "partial" | "settled";
+/** Sum of every bucket. */
+declare const settledTotal: <B extends string>(line: SettlementLine<B>) => number;
+/**
+ * `quantity − Σ buckets`. NOT clamped at zero: a negative means the line was
+ * over-settled by data written outside {@link planSettlement}, and hiding it
+ * would erase the only signal that happened.
+ */
+declare const outstandingOf: <B extends string>(line: SettlementLine<B>) => number;
+/** `open` — nothing settled; `settled` — nothing outstanding; otherwise `partial`. */
+declare const settlementState: <B extends string>(line: SettlementLine<B>) => SettlementState;
+/** Every line settled ⇒ `settled`; every line untouched ⇒ `open`; else `partial`. */
+declare const documentSettlementState: <B extends string>(lines: ReadonlyArray<SettlementLine<B>>) => SettlementState;
+/** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
+declare const settledEntirelyIn: <B extends string>(lines: ReadonlyArray<SettlementLine<B>>, bucket: B) => boolean;
+type SettlementRefusal = {
+  readonly code: "not_positive_integer";
+  readonly requested: number;
+} | {
+  readonly code: "exceeds_outstanding";
+  readonly requested: number;
+  readonly outstanding: number;
+};
+/**
+ * Settle `quantity` more units into `bucket`, or refuse.
+ *
+ * Refuses a non-positive or fractional quantity and anything above what is
+ * outstanding — an over-settlement is an input error, never silently trimmed.
+ * Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
+ */
+declare const planSettlement: <B extends string>(line: SettlementLine<B>, bucket: B, quantity: number) => Result<SettlementLine<B>, SettlementRefusal>;
+/**
+ * Settle up to `requested` units into `bucket`, taking only what is outstanding.
+ * `applied` is what was actually settled; `0` leaves the line unchanged.
+ */
+declare const clampSettlement: <B extends string>(line: SettlementLine<B>, bucket: B, requested: number) => {
+  readonly line: SettlementLine<B>;
+  readonly applied: number;
+};
+/**
+ * The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
+ * settlement batch, given how many units the whole line had settled before and after it.
+ *
+ * `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+ * batches, and across every outcome bucket, the shares sum to exactly `total` once the line
+ * is fully settled — no remainder to chase, no batch-order dependence.
+ */
+declare const shareOfSettled: (total: number, quantity: number, settledBefore: number, settledAfter: number) => number;
+//#endregion
+export { SettlementLine, SettlementRefusal, SettlementState, clampSettlement, documentSettlementState, outstandingOf, planSettlement, settledEntirelyIn, settledTotal, settlementState, shareOfSettled };

package/dist/line-settlement.mjs

@@ -0,0 +1,79 @@
+import { err, ok } from "./result.mjs";
+//#region src/inventory/line-settlement.ts
+/** Sum of every bucket. */
+const settledTotal = (line) => Object.values(line.settled).reduce((sum, n) => sum + (n ?? 0), 0);
+/**
+* `quantity − Σ buckets`. NOT clamped at zero: a negative means the line was
+* over-settled by data written outside {@link planSettlement}, and hiding it
+* would erase the only signal that happened.
+*/
+const outstandingOf = (line) => line.quantity - settledTotal(line);
+/** `open` — nothing settled; `settled` — nothing outstanding; otherwise `partial`. */
+const settlementState = (line) => {
+	if (outstandingOf(line) <= 0) return "settled";
+	return settledTotal(line) === 0 ? "open" : "partial";
+};
+/** Every line settled ⇒ `settled`; every line untouched ⇒ `open`; else `partial`. */
+const documentSettlementState = (lines) => {
+	const states = lines.map(settlementState);
+	if (states.every((s) => s === "settled")) return "settled";
+	if (states.every((s) => s === "open")) return "open";
+	return "partial";
+};
+/** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
+const settledEntirelyIn = (lines, bucket) => lines.every((l) => (l.settled[bucket] ?? 0) >= l.quantity);
+/**
+* Settle `quantity` more units into `bucket`, or refuse.
+*
+* Refuses a non-positive or fractional quantity and anything above what is
+* outstanding — an over-settlement is an input error, never silently trimmed.
+* Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
+*/
+const planSettlement = (line, bucket, quantity) => {
+	if (!Number.isInteger(quantity) || quantity <= 0) return err({
+		code: "not_positive_integer",
+		requested: quantity
+	});
+	const outstanding = outstandingOf(line);
+	if (quantity > outstanding) return err({
+		code: "exceeds_outstanding",
+		requested: quantity,
+		outstanding
+	});
+	return ok(withBucket(line, bucket, quantity));
+};
+/**
+* Settle up to `requested` units into `bucket`, taking only what is outstanding.
+* `applied` is what was actually settled; `0` leaves the line unchanged.
+*/
+const clampSettlement = (line, bucket, requested) => {
+	const applied = Math.max(0, Math.min(Math.trunc(requested), outstandingOf(line)));
+	return {
+		line: applied > 0 ? withBucket(line, bucket, applied) : line,
+		applied
+	};
+};
+/**
+* The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
+* settlement batch, given how many units the whole line had settled before and after it.
+*
+* `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+* batches, and across every outcome bucket, the shares sum to exactly `total` once the line
+* is fully settled — no remainder to chase, no batch-order dependence.
+*/
+const shareOfSettled = (total, quantity, settledBefore, settledAfter) => {
+	if (!Number.isInteger(total) || total < 0) throw new RangeError(`total must be a non-negative integer, got ${total}`);
+	if (!Number.isInteger(quantity) || quantity <= 0) throw new RangeError(`quantity must be a positive integer, got ${quantity}`);
+	if (!(0 <= settledBefore && settledBefore <= settledAfter && settledAfter <= quantity)) throw new RangeError(`need 0 <= before (${settledBefore}) <= after (${settledAfter}) <= quantity (${quantity})`);
+	const at = (n) => Number(BigInt(total) * BigInt(n) / BigInt(quantity));
+	return at(settledAfter) - at(settledBefore);
+};
+const withBucket = (line, bucket, quantity) => ({
+	quantity: line.quantity,
+	settled: {
+		...line.settled,
+		[bucket]: (line.settled[bucket] ?? 0) + quantity
+	}
+});
+//#endregion
+export { clampSettlement, documentSettlementState, outstandingOf, planSettlement, settledEntirelyIn, settledTotal, settlementState, shareOfSettled };

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);
@@ -74,7 +79,8 @@ var MemoryOutboxStore = class {
 			entry.fenceToken = (entry.fenceToken ?? 0) + 1;
 			claimed.push({
 				event: entry.event,
-				fencingToken: entry.fenceToken
+				fencingToken: entry.fenceToken,
+				attempts: entry.attempts
 			});
 		}
 		return claimed;
@@ -89,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 };