@classytic/primitives 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -3,6 +3,128 @@
 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.29.0 — 2026-10-08
+
+### Added — `./signed-token`: ES256 compact JWS over WebCrypto
+`signToken` / `verifyToken` for a server and an offline device, no dependency. `typ` is required on both
+sides and a token without `exp` is refused; every failure is a named refusal (`bad_signature`,
+`wrong_type`, `unknown_key`, `expired`, …), never a throw. Signing keys import non-extractable.
+Pinned by `tests/unit/signed-token.test.ts` (the expiry rule is falsified).
+
+### Added — `itemStockOf` (`./item-stock`): one item's stock, the one summary every reader shows
+`itemStockOf(item, rowOf, { defaultReorderPoint })` builds `{ quantity, inStock, lowStock, valueMinor?,
+variants? }` from rows filed under stock keys (`stockKeyFor`). A row reached by both the item-level
+and a variant lookup counts once; production's sole variant keys by the product id. It is pure and
+browser-safe, so the server's catalog bridge and an offline till compute the same answer. Pinned by
+`tests/unit/item-stock.test.ts`; collapsing the row de-duplication fails three of its cases.
+
+### Added — maker-checker on `ApprovalChain` (`./approval`)
+`ApprovalChain.request` (`{ by, at, basis? }`) records who asked and what the approval covers.
+`attachRequest(chain, request)` removes the requester from every step's approvers and throws
+`NO_INDEPENDENT_APPROVER` when a step is left below its quorum. `applyDecision` throws
+`SELF_APPROVAL` when the requester approves (rejecting their own request — a withdrawal — is
+allowed). `applyDecision` and `skipStep` now preserve `request` and `notRequiredReason` instead of
+rebuilding the chain from `{ order, steps, status }`.
+
+### Added — `diffEventSchema` (`./events`)
+Compares two versions of an event payload's JSON Schema and marks each change breaking or not
+for an existing CONSUMER (forward compatibility): a required field removed, a field made optional,
+a widened type or enum break; additions and narrowing do not. Payloads are open for extension, so
+`additionalProperties: false` is disregarded. Nested objects, array items and record values recurse.
+
+### Added — `createEventRouter` (`./events`)
+An index over event subscriptions with `matchEventPattern`'s exact semantics — same values, same
+order, deduped — in amortized O(1) per route: candidates are only the name's separator prefixes,
+and results are memoized per name (bounded) until `add`/`remove`. Pinned by a property test
+against the scan. Transports and graph analyses route through it instead of scanning.
+
+### Added — `readEnv`: strict configuration reads (`./environment`)
+`readEnv(process.env)` → `bool | int | number | oneOf | list`, plus `InvalidEnvError`. Unset or
+blank → the declared default; a value that is SET but unrecognised throws, naming the variable
+and what it accepts. Booleans take `true/false`, `1/0`, `yes/no`, `on/off`; numbers take bounds.
+A hand-rolled `=== 'true'` or `parseInt` widens a typo to the default and says nothing.
+
+### Added — placeholder phone, one definition (`./phone`)
+`PLACEHOLDER_PHONE_PREFIX`, `placeholderPhone(id)`, `isPlaceholderPhone(v)`, `shownPhone(v)`.
+A record whose `phone` is required and unique but unknown stores `pending_<id>`; the writer
+(`@spinekit/order`) and every reader (be-prod party linking, the SDK, commerce-ui, pos-ui,
+the storefront) now share this instead of five hand-written `startsWith('pending_')`.
+
+### Deprecated: `@classytic/primitives/idempotency` — moved to `@classytic/repo-core/idempotency`
+
+The claim contract had no consumers here. It now lives beside `repo-core/lock` with its store
+port, `runIdempotent`, the reference store and the conformance suite, so every persistence kit
+implements it without depending on this package. Removed in the next minor.
+
+### Changed: `canonicalJson` refuses nesting deeper than 100 levels
+
+`MAX_CANONICAL_DEPTH` (MongoDB's document limit). Deeper input throws `CanonicalizeError`
+instead of recursing — a hostile input used to overflow the stack.
+
+### Added: `@classytic/primitives/line-settlement` (incl. `shareOfSettled`)
+
+One definition of "how much of this document line is still open". A line's
+quantity splits into kernel-named outcome buckets (fulfilled / returned /
+received / written off …); `outstandingOf`, `settlementState`,
+`documentSettlementState` and `settledEntirelyIn` derive the rest, and
+`planSettlement` REFUSES a non-integer or over-outstanding quantity instead of
+trimming it (`clampSettlement` exists for surfaces whose contract is "take what
+fits"). Order, flow, purchase and transfer each derived this by hand; transfer
+adopts it first.
+
+### Added: `OutboxClaimedEvent.attempts`, the durable attempt count
+
+`OutboxFailureContext.attempts` was documented as "tracked in-process by the
+relay; resets on restart", and that is exactly where a failure policy is wrong.
+`attempts >= 5 → deadLetter` never fired for a poison event that crashes the
+relay (it came back at 1 on every boot), and across N relays sharing a store it
+meant 5×N deliveries. Stores already increment a per-row counter atomically
+inside the claim; they had no way to report it.
+
+`OutboxClaimedEvent` (the fenced-claim result) gains an optional
+`attempts?: number`, which counts every claim including the one that returned it.
+`MemoryOutboxStore` reports it. Optional and additive: stores that don't count
+leave it absent, and relays fall back to their own count and take the larger of
+the two.
+
+## 0.28.0
+
+### Added: a `pass` monetization kind (paid once, grants a term, never renews)
+
+The union could say "charged once" (`one_time`, a single price, no span) and
+"recurring" (`subscription`, priced spans that renew). It could not say
+"prepaid term": a course access pass, a gym or transit pass, a parking permit,
+a term licence. Hosts selling one reached for `subscription`, the only shape
+that carried priced spans, and then had to explain at every read that it does
+not actually renew. `toRevenueMonetizationType` would also have settled those
+sales as recurring income, forecasting revenue nothing was scheduled to bill.
+
+`PassMonetization { type: 'pass', passes: AccessPass[] }`, where an
+`AccessPass` is a key, a label, a price, an optional "was" price, and a
+`duration` + `durationUnit`. Shaped like `SubscriptionPlan` so a term means
+the same thing everywhere, kept separate because a plan carries `trialDays`
+and a renewal discount that a pass has none of.
+
+Also: `isPassMonetization`, `defaultPassOf` (the cheapest term, ties broken on
+the shorter SPAN so the headline is deterministic), and `approxTermDays` for
+ordering and labels only. `unitPriceOf` returns the cheapest term's price for
+a pass, `compareAtPriceOf` now returns the "was" of that SAME term so a card
+can never strike one term's price through beside another's, and
+`toRevenueMonetizationType('pass')` is `purchase`.
+
+A perpetual sale stays `one_time`: "forever" is the absence of a term, not a
+very long one.
+
+### Added — `CashDestination` on `./money`
+
+`CASH_DESTINATIONS` (`'cash' | 'petty_cash'`), `isCashDestination` and
+`cashDestinationLabel`: WHERE received cash landed, as an intent — never a
+chart-of-accounts code. One vocabulary for a request body, a domain event, a
+client SDK and a settlement dialog, so the accounting tier alone maps it to the
+active chart and a renumber cannot reach any of them. Added because a client
+carried a literal bank code the chart had already renumbered, and every
+settlement it sent was refused.
+
 ## 0.27.0
 
 ### Added — `./csv` subpath: one CSV cell escaper for the whole fleet

package/dist/approval.d.mts

@@ -79,6 +79,18 @@ interface ApprovalChain {
    * {@link isNotRequired} tests the structure instead, which no schema can drop.
    */
   readonly notRequiredReason?: string;
+  /** Who asked, when, and against what — set by {@link attachRequest}. The requester may not approve it. */
+  readonly request?: ApprovalRequest;
+}
+/** The maker of an approval request, and the basis it was approved against. */
+interface ApprovalRequest {
+  readonly by: string;
+  readonly at: Date;
+  /** What the approval covers. A later amount above `basis.amount` is not covered. */
+  readonly basis?: {
+    readonly amount?: number;
+    readonly category?: string;
+  };
 }
 interface CreateChainInput {
   readonly order: ChainOrder;
@@ -101,7 +113,11 @@ type ApprovalErrorCode = 'EMPTY_STEPS' | 'DUPLICATE_STEP_ID' | 'EMPTY_APPROVERS'
  *  `CHAIN_INCOMPLETE`: the chain is not unfinished, it is absent — the
  *  document never carried one, or a schema that never declared the field
  *  stripped it on write. See {@link assertApproved}. */
-'CHAIN_MISSING';
+'CHAIN_MISSING' |
+/** The requester tried to approve their own request (maker-checker). */
+'SELF_APPROVAL' |
+/** Removing the requester left a step with fewer approvers than its quorum. */
+'NO_INDEPENDENT_APPROVER';
 declare class ApprovalError extends Error {
   readonly name = "ApprovalError";
   readonly code: ApprovalErrorCode;
@@ -145,6 +161,14 @@ declare function createChain(input: CreateChainInput): ApprovalChain;
  * @param reason Why approval was not required, for the audit trail.
  */
 declare function notRequiredChain(reason: string): ApprovalChain;
+/**
+ * Stamp the requester onto a chain and remove them from every step's approvers
+ * (maker-checker). A zero-step chain gets the request and nothing else.
+ *
+ * @throws ApprovalError `NO_INDEPENDENT_APPROVER` when a step is left with
+ *   fewer approvers than `requiredApprovals` — nobody else can approve it.
+ */
+declare function attachRequest(chain: ApprovalChain, request: ApprovalRequest): ApprovalChain;
 /**
  * Returns the next step awaiting a decision — or `null` if none.
  *
@@ -242,4 +266,4 @@ declare function isPending(chain: ApprovalChain): boolean;
  */
 declare function decisionCount(chain: ApprovalChain): number;
 //#endregion
-export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, AssertApprovedOptions, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, assertApproved, assertApprovedIfPresent, createChain, decisionCount, isApproved, isNotRequired, isPending, isRejected, nextPendingStep, notRequiredChain, pendingSteps, skipStep };
+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 };

package/dist/approval.mjs

@@ -82,6 +82,28 @@ function notRequiredChain(reason) {
 	};
 }
 /**
+* Stamp the requester onto a chain and remove them from every step's approvers
+* (maker-checker). A zero-step chain gets the request and nothing else.
+*
+* @throws ApprovalError `NO_INDEPENDENT_APPROVER` when a step is left with
+*   fewer approvers than `requiredApprovals` — nobody else can approve it.
+*/
+function attachRequest(chain, request) {
+	const steps = chain.steps.map((step) => {
+		const approvers = step.approvers.filter((a) => a.id !== request.by);
+		if (step.status === "pending" && approvers.length < step.requiredApprovals) throw new ApprovalError("NO_INDEPENDENT_APPROVER", `step ${step.id} needs ${step.requiredApprovals} approver(s) other than the requester ${request.by}; it has ${approvers.length}`);
+		return approvers.length === step.approvers.length ? step : {
+			...step,
+			approvers
+		};
+	});
+	return {
+		...chain,
+		steps,
+		request
+	};
+}
+/**
 * Returns the next step awaiting a decision — or `null` if none.
 *
 * For `sequential` chains: the first `pending` step in order; later steps
@@ -113,6 +135,7 @@ function applyDecision(chain, input) {
 	const step = chain.steps[stepIndex];
 	if (!step) throw new ApprovalError("UNKNOWN_STEP", `no step with id ${input.stepId}`);
 	if (!pendingSteps(chain).some((s) => s.id === input.stepId)) throw new ApprovalError("STEP_NOT_ACTIVE", `step ${input.stepId} is not currently active (status=${step.status})`);
+	if (input.decision === "approved" && chain.request && chain.request.by === input.approverId) throw new ApprovalError("SELF_APPROVAL", `approver ${input.approverId} requested this approval and may not approve it`);
 	if (!step.approvers.some((a) => a.id === input.approverId)) throw new ApprovalError("UNAUTHORIZED_APPROVER", `approver ${input.approverId} is not listed on step ${input.stepId}`);
 	if (step.decisions.some((d) => d.approverId === input.approverId)) throw new ApprovalError("STEP_ALREADY_DECIDED_BY_APPROVER", `approver ${input.approverId} has already decided on step ${input.stepId}`);
 	const decision = {
@@ -127,7 +150,7 @@ function applyDecision(chain, input) {
 	});
 	const updatedSteps = chain.steps.map((s, i) => i === stepIndex ? updatedStep : s);
 	return {
-		order: chain.order,
+		...chain,
 		steps: updatedSteps,
 		status: computeChainStatus(updatedSteps)
 	};
@@ -150,7 +173,7 @@ function skipStep(chain, stepId, reason) {
 	};
 	const updatedSteps = chain.steps.map((s, i) => i === stepIndex ? updatedStep : s);
 	return {
-		order: chain.order,
+		...chain,
 		steps: updatedSteps,
 		status: computeChainStatus(updatedSteps)
 	};
@@ -248,4 +271,4 @@ function computeChainStatus(steps) {
 	return steps.every((s) => s.status === "approved" || s.status === "skipped") ? "approved" : "pending";
 }
 //#endregion
-export { ApprovalError, applyDecision, assertApproved, assertApprovedIfPresent, createChain, decisionCount, isApproved, isNotRequired, isPending, isRejected, nextPendingStep, notRequiredChain, pendingSteps, skipStep };
+export { ApprovalError, applyDecision, assertApproved, assertApprovedIfPresent, attachRequest, createChain, decisionCount, isApproved, isNotRequired, isPending, isRejected, nextPendingStep, notRequiredChain, pendingSteps, skipStep };

package/dist/bank-transaction.d.mts

@@ -1,4 +1,4 @@
-import { n as Money } from "./money-CfAvfNiM.mjs";
+import { n as Money } from "./money-C9iLWiWR.mjs";
 //#region src/money/bank-transaction.d.ts
 /**
  * The other side of a bank transaction. All fields optional — different

package/dist/canonical.d.mts

@@ -27,6 +27,11 @@
 declare class CanonicalizeError extends Error {
   constructor(message: string);
 }
+/**
+ * Deepest nesting canonicalized — MongoDB's own document limit. Deeper input is refused
+ * rather than recursed: it may be hostile (a request body), and recursion would blow the stack.
+ */
+declare const MAX_CANONICAL_DEPTH = 100;
 /**
  * Strict canonical JSON string of any value. Deterministic (sorted keys),
  * `Date`-explicit; throws {@link CanonicalizeError} on unsupported/ambiguous
@@ -38,4 +43,4 @@ declare function sha256Hex(input: string): string;
 /** Convenience: `sha256Hex(canonicalJson(value))` — the integrity digest of a value. */
 declare function canonicalDigest(value: unknown): string;
 //#endregion
-export { CanonicalizeError, canonicalDigest, canonicalJson, sha256Hex };
+export { CanonicalizeError, MAX_CANONICAL_DEPTH, canonicalDigest, canonicalJson, sha256Hex };

package/dist/canonical.mjs

@@ -31,7 +31,12 @@ var CanonicalizeError = class extends Error {
 		this.name = "CanonicalizeError";
 	}
 };
-function canonicalize(value, seen) {
+/**
+* Deepest nesting canonicalized — MongoDB's own document limit. Deeper input is refused
+* rather than recursed: it may be hostile (a request body), and recursion would blow the stack.
+*/
+const MAX_CANONICAL_DEPTH = 100;
+function canonicalize(value, seen, depth = 0) {
 	if (value === null) return "null";
 	const t = typeof value;
 	if (t === "string") return JSON.stringify(value);
@@ -50,10 +55,11 @@ function canonicalize(value, seen) {
 	}
 	if (value instanceof Map || value instanceof Set) throw new CanonicalizeError(`${value.constructor.name} is not supported — use a plain object/array`);
 	const obj = value;
+	if (depth >= 100) throw new CanonicalizeError(`nesting deeper than 100 levels`);
 	if (seen.has(obj)) throw new CanonicalizeError("cyclic reference");
 	seen.add(obj);
 	try {
-		if (Array.isArray(value)) return `[${value.map((v) => canonicalize(v, seen)).join(",")}]`;
+		if (Array.isArray(value)) return `[${value.map((v) => canonicalize(v, seen, depth + 1)).join(",")}]`;
 		/**
 		* Reject CLASS INSTANCES — the silent-collapse hole.
 		*
@@ -72,7 +78,7 @@ function canonicalize(value, seen) {
 		const proto = Object.getPrototypeOf(value);
 		if (proto !== null && proto !== Object.prototype) throw new CanonicalizeError(`class instance '${value.constructor?.name ?? "unknown"}' is not serializable — its own enumerable keys are not its value, so it would digest as {} and silently defeat the checksum. Project it to a plain object first.`);
 		const rec = value;
-		return `{${Object.keys(rec).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(rec[k], seen)}`).join(",")}}`;
+		return `{${Object.keys(rec).sort().map((k) => `${JSON.stringify(k)}:${canonicalize(rec[k], seen, depth + 1)}`).join(",")}}`;
 	} finally {
 		seen.delete(obj);
 	}
@@ -94,4 +100,4 @@ function canonicalDigest(value) {
 	return sha256Hex(canonicalJson(value));
 }
 //#endregion
-export { CanonicalizeError, canonicalDigest, canonicalJson, sha256Hex };
+export { CanonicalizeError, MAX_CANONICAL_DEPTH, canonicalDigest, canonicalJson, sha256Hex };

package/dist/currency.d.mts

@@ -1,2 +1,2 @@
-import { A as convertWithSnapshot, C as CURRENCY_PATTERN, D as FxSnapshot, E as FxRounding, F as minorUnitFactor, I as reverseWithSnapshot, L as toCurrencyCode, M as isCurrencyCode, N as isFxSnapshot, O as InvalidCurrencyCodeError, P as isKnownCurrency, S as CURRENCIES, T as CurrencyMismatchError, j as currencyCode, k as MINOR_UNIT_FACTOR, w as CurrencyCode } from "./money-CfAvfNiM.mjs";
+import { A as FxRounding, B as reverseWithSnapshot, D as CURRENCY_PATTERN, E as CURRENCIES, F as currencyCode, I as isCurrencyCode, L as isFxSnapshot, M as InvalidCurrencyCodeError, N as MINOR_UNIT_FACTOR, O as CurrencyCode, P as convertWithSnapshot, R as isKnownCurrency, V as toCurrencyCode, j as FxSnapshot, k as CurrencyMismatchError, z as minorUnitFactor } from "./money-C9iLWiWR.mjs";
 export { CURRENCIES, CURRENCY_PATTERN, CurrencyCode, CurrencyMismatchError, FxRounding, FxSnapshot, InvalidCurrencyCodeError, MINOR_UNIT_FACTOR, convertWithSnapshot, currencyCode, isCurrencyCode, isFxSnapshot, isKnownCurrency, minorUnitFactor, reverseWithSnapshot, toCurrencyCode };

package/dist/environment.d.mts

@@ -86,5 +86,34 @@ declare function classifyEnv(env: string | undefined | null): EnvClass;
  * published package is not free — it has to be supported, and it invited a needless version bump.
  */
 declare function isProductionEnv(env: string | undefined | null): boolean;
+/** A variable was SET to a value its reader does not accept. Names the variable and what it takes. */
+declare class InvalidEnvError extends Error {
+  readonly code = "INVALID_ENV";
+  readonly variable: string;
+  readonly value: string;
+  readonly accepted: string;
+  constructor(variable: string, value: string, accepted: string);
+}
+/** A typed reader over an env record. Every method: unset or blank → the fallback; set but unrecognised → throws. */
+interface EnvReader {
+  bool(name: string, fallback: boolean): boolean;
+  /** A whole number. A fallback of `undefined` makes the setting optional. */
+  int<F extends number | undefined>(name: string, fallback: F, bounds?: EnvBounds): number | F;
+  /** A finite decimal (a rate, a ratio). */
+  number<F extends number | undefined>(name: string, fallback: F, bounds?: EnvBounds): number | F;
+  oneOf<const T extends string>(name: string, allowed: readonly T[], fallback: T): T;
+  /** Comma-separated, trimmed, empty items dropped. Unset → `[]`. */
+  list(name: string): string[];
+}
+interface EnvBounds {
+  min?: number;
+  max?: number;
+}
+/**
+ * Read configuration strictly: a value that is SET must mean something, or boot fails naming it.
+ * A typo must never read as the default — `FEATURE=ture` silently becoming `false` switches a
+ * feature off with nothing said.
+ */
+declare function readEnv(env: Readonly<Record<string, string | undefined>>): EnvReader;
 //#endregion
-export { EnvClass, classifyEnv, isProductionEnv };
+export { EnvBounds, EnvClass, EnvReader, InvalidEnvError, classifyEnv, isProductionEnv, readEnv };

package/dist/environment.mjs

@@ -49,5 +49,76 @@ function classifyEnv(env) {
 function isProductionEnv(env) {
 	return classifyEnv(env) === "production";
 }
+/** A variable was SET to a value its reader does not accept. Names the variable and what it takes. */
+var InvalidEnvError = class extends Error {
+	code = "INVALID_ENV";
+	variable;
+	value;
+	accepted;
+	constructor(variable, value, accepted) {
+		super(`${variable}=${JSON.stringify(value)} is not valid — expected ${accepted}.`);
+		this.name = "InvalidEnvError";
+		this.variable = variable;
+		this.value = value;
+		this.accepted = accepted;
+	}
+};
+function inBounds(name, v, n, { min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER }, valid, kind) {
+	if (!valid(n) || n < min || n > max) throw new InvalidEnvError(name, v, `${kind} in [${min}, ${max}]`);
+	return n;
+}
+const TRUE = /* @__PURE__ */ new Set([
+	"true",
+	"1",
+	"yes",
+	"on"
+]);
+const FALSE = /* @__PURE__ */ new Set([
+	"false",
+	"0",
+	"no",
+	"off"
+]);
+/**
+* Read configuration strictly: a value that is SET must mean something, or boot fails naming it.
+* A typo must never read as the default — `FEATURE=ture` silently becoming `false` switches a
+* feature off with nothing said.
+*/
+function readEnv(env) {
+	const raw = (name) => {
+		const v = env[name]?.trim();
+		return v ? v : void 0;
+	};
+	return {
+		bool(name, fallback) {
+			const v = raw(name);
+			if (v === void 0) return fallback;
+			const lower = v.toLowerCase();
+			if (TRUE.has(lower)) return true;
+			if (FALSE.has(lower)) return false;
+			throw new InvalidEnvError(name, v, "true | false (also 1 | 0, yes | no, on | off)");
+		},
+		int(name, fallback, bounds = {}) {
+			const v = raw(name);
+			if (v === void 0) return fallback;
+			return inBounds(name, v, /^-?\d+$/.test(v) ? Number(v) : NaN, bounds, Number.isSafeInteger, "an integer");
+		},
+		number(name, fallback, bounds = {}) {
+			const v = raw(name);
+			if (v === void 0) return fallback;
+			return inBounds(name, v, /^-?\d+(\.\d+)?$/.test(v) ? Number(v) : NaN, bounds, Number.isFinite, "a number");
+		},
+		oneOf(name, allowed, fallback) {
+			const v = raw(name);
+			if (v === void 0) return fallback;
+			if (allowed.includes(v)) return v;
+			throw new InvalidEnvError(name, v, allowed.join(" | "));
+		},
+		list(name) {
+			const v = raw(name);
+			return v ? v.split(",").map((s) => s.trim()).filter(Boolean) : [];
+		}
+	};
+}
 //#endregion
-export { classifyEnv, isProductionEnv };
+export { InvalidEnvError, classifyEnv, isProductionEnv, readEnv };

package/dist/events.d.mts

@@ -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

@@ -127,5 +127,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