@classytic/primitives 0.28.0 → 0.29.0

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

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 };