@classytic/primitives 0.28.0 → 0.30.0

package/dist/approval.d.mts

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

package/dist/approval.mjs

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

package/dist/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/durable-events.d.mts

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

package/dist/durable-events.mjs

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

package/dist/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 };