@classytic/primitives 0.22.0 → 0.24.0

package/dist/approval.mjs

@@ -39,6 +39,49 @@ function createChain(input) {
 	};
 }
 /**
+* The chain for a subject that needs NO approval — zero steps, already
+* resolved. The explicit, greppable answer to "the policy engine ran and
+* decided this document does not require approval."
+*
+* ## Why this is not a fabricated approval
+*
+* {@link computeChainStatus} already folds an empty step list to `'approved'`
+* — "nothing is outstanding" is what approved MEANS to this primitive, and
+* that fold predates this function. What {@link createChain} refuses
+* (`EMPTY_STEPS`) is building a ROUTING chain that routes nowhere, which is a
+* different mistake and stays refused. So this constructor states the same
+* conclusion the fold reaches, under a name a reviewer can search for, rather
+* than letting a caller reach it by handing `createChain` an empty array.
+*
+* ## Why a chain at all, instead of leaving `approvals` absent
+*
+* Because absence is the one input that occurs by accident. A schema that
+* never declared the field strips it, a failed write leaves it unset — and
+* {@link assertApproved} must keep treating that as CHAIN_MISSING. A present,
+* zero-step chain is distinguishable from both a lost chain (absent) and a
+* granted one (has steps and decisions), so every existing gate keeps working
+* unchanged and no caller needs a second predicate beside `isApproved`.
+*
+* ## The hazard, stated plainly
+*
+* This makes {@link isApproved} true without a human deciding anything. It is
+* only correct where a policy engine ASKED and got "no policy applies" — never
+* as a fallback for a lookup that failed, errored, or was not configured. A
+* resolver that cannot reach its policy store must throw; answering "not
+* required" there would auto-approve every document in the deployment, which
+* is precisely the permissive-default failure this codebase designs against.
+*
+* @param reason Why approval was not required, for the audit trail.
+*/
+function notRequiredChain(reason) {
+	return {
+		order: "sequential",
+		steps: [],
+		status: computeChainStatus([]),
+		notRequiredReason: reason
+	};
+}
+/**
 * Returns the next step awaiting a decision — or `null` if none.
 *
 * For `sequential` chains: the first `pending` step in order; later steps
@@ -116,6 +159,22 @@ function isApproved(chain) {
 	return chain.status === "approved";
 }
 /**
+* Was this chain built by {@link notRequiredChain} — i.e. approval did not
+* apply, as opposed to having been granted?
+*
+* Both are `isApproved`, and for GATING that is correct: neither blocks the
+* operation. Use this only where the difference is worth showing — an audit
+* trail or an approvals UI, where rendering "Approved" for a document nobody
+* approved misleads the reader.
+*
+* Tests the STRUCTURE (no steps ⇒ nobody was ever asked), not
+* `notRequiredReason`, which a subject schema that never declared the field
+* silently drops on write.
+*/
+function isNotRequired(chain) {
+	return chain.steps.length === 0;
+}
+/**
 * The canonical finalize-time gate: assert a chain EXISTS and has reached
 * `approved`, else throw. Use it at every commit/post/finalize boundary that
 * must not proceed unapproved (journal-entry post, PO approve, transfer
@@ -189,4 +248,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, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };
+export { ApprovalError, applyDecision, assertApproved, assertApprovedIfPresent, createChain, decisionCount, isApproved, isNotRequired, isPending, isRejected, nextPendingStep, notRequiredChain, pendingSteps, skipStep };

package/dist/calendar-facts.d.mts

@@ -0,0 +1,176 @@
+import { t as CivilDate } from "./timezone-CxUjxmRU.mjs";
+//#region src/scheduling/calendar-facts.d.ts
+/** Inclusive civil-date bounds a dataset is asserted COMPLETE for. */
+interface DateCoverage {
+  readonly from: CivilDate;
+  readonly through: CivilDate;
+}
+/**
+ * A set of dated facts plus the window it is complete for.
+ *
+ * ## The key type documents intent and CANNOT enforce it
+ *
+ * `Record<CivilDate, T>` is a mapped type over a branded string, which TypeScript collapses to a plain
+ * string index signature — so the brand does not survive in key position and any string is accepted at
+ * the type level. The brand is kept because it states what the keys MEAN; every key is validated at
+ * construction instead. Do not assume a value of this type has pre-validated keys unless it came from
+ * {@link defineDateEdition} or a schema that performs the same checks.
+ */
+interface CoveredDateEdition<TEntry extends object> {
+  readonly coverage: DateCoverage;
+  readonly dates: Readonly<Record<CivilDate, TEntry>>;
+}
+/**
+ * Why a lookup could not answer. Each is a DIFFERENT operator remedy, which is why this is not a
+ * boolean:
+ *
+ *   - `missing-edition` — nobody has entered this year. Enter it.
+ *   - `outside-coverage` — the year exists but does not claim to cover this date. Extend the coverage.
+ *   - `unattested` — data exists but no authorized party has vouched for it. Approve it.
+ *
+ * `unattested` is never produced by this module: attestation is a property of how a dataset was STORED
+ * and by whom, which a pure function cannot observe. It lives in the union so a config layer can return
+ * it through the same shape rather than inventing a fourth state.
+ */
+type DateFactUnknownReason = 'missing-edition' | 'outside-coverage' | 'unattested';
+/**
+ * The three-state answer.
+ *
+ * **`not-listed` does not mean "working day".** It means this attested dataset does not list the date.
+ * Converting that into a working-day, a pay rate or a leave deduction is the consuming domain's job,
+ * because the same fact supports different conclusions in each.
+ */
+type DateFactLookup<TEntry> = {
+  readonly kind: 'listed';
+  readonly entry: TEntry;
+} | {
+  readonly kind: 'not-listed';
+} | {
+  readonly kind: 'unknown';
+  readonly reason: DateFactUnknownReason;
+};
+/** Who published a dataset. Required, and required to be non-empty — see {@link defineDateEdition}. */
+interface DateAuthority {
+  /** The publishing body, e.g. a ministry. Never an aggregator API that merely relayed it. */
+  readonly issuer: string;
+  /** The citable instrument — a gazette or circular number. */
+  readonly reference: string;
+  readonly publishedOn?: CivilDate | undefined;
+}
+/** An edition that names its own authority. The unit of completeness for a jurisdiction fact. */
+interface AttributedDateEdition<TEntry extends object> extends CoveredDateEdition<TEntry> {
+  readonly authority: DateAuthority;
+}
+/** One listed date, as an importer supplies it. */
+interface DateEntryInput<TEntry extends object> {
+  readonly date: string;
+  readonly entry: TEntry;
+}
+interface DefineDateEditionInput<TEntry extends object> {
+  /**
+   * The edition key, `YYYY`. Checked AGAINST the coverage rather than derived from it — an edition
+   * filed under the wrong year is a data-entry error that would otherwise make every lookup in that
+   * year report `missing-edition` while the data sat one key away.
+   */
+  readonly year: string;
+  readonly coverage: {
+    readonly from: string;
+    readonly through: string;
+  };
+  readonly authority: DateAuthority;
+  readonly dates: readonly DateEntryInput<TEntry>[];
+  /**
+   * Permit an edition covering less than the whole year.
+   *
+   * OFF by default. An annual public-holiday gazette covers a full year, so partial coverage is
+   * usually a half-finished import — and a half-finished import that presents as authoritative is
+   * precisely the failure this module exists to prevent. Opt in only where a consumer genuinely needs
+   * a partial window.
+   */
+  readonly allowPartialYear?: boolean;
+}
+/** Thrown by {@link defineDateEdition}. Carries every problem, not the first. */
+declare class InvalidDateEditionError extends Error {
+  readonly problems: readonly string[];
+  constructor(year: string, problems: readonly string[]);
+}
+/**
+ * Build a validated edition, or throw naming every problem.
+ *
+ * REPORTS ALL problems rather than the first: an operator fixing a year's holiday list wants the whole
+ * list of bad rows, and returning one at a time turns one correction into twenty round trips.
+ */
+declare function defineDateEdition<TEntry extends object>(input: DefineDateEditionInput<TEntry>): AttributedDateEdition<TEntry>;
+/**
+ * A jurisdiction's (or an employer's) dated facts, keyed by year.
+ *
+ * Year-keyed so an amendment replaces one edition rather than the whole history — and so a lookup for
+ * an unentered year is distinguishable from a date nobody listed.
+ */
+interface DateFactCalendar<TEntry extends object> {
+  /** The zone the civil dates are civil IN. A date has no meaning without it. */
+  readonly timeZone: string;
+  /** Key is `YYYY`. */
+  readonly editions: Readonly<Record<string, AttributedDateEdition<TEntry>>>;
+}
+/** Thrown by {@link defineDateFactCalendar}. */
+declare class InvalidDateFactCalendarError extends Error {
+  readonly problems: readonly string[];
+  constructor(problems: readonly string[]);
+}
+/**
+ * Build a validated calendar. **The timezone is checked here, not trusted.**
+ *
+ * A civil date has no meaning without a zone, and a WRONG zone is worse than a missing one: it shifts
+ * every boundary by the offset while every value still looks like a date. Asia/Dhaka is UTC+6, so a
+ * calendar read in UTC disagrees with the business day for six hours at both ends — the same failure
+ * that once reported August revenue as July for the last six hours of every month.
+ *
+ * Also re-checks each edition's key against its own coverage. `defineDateEdition` already enforces that,
+ * but a calendar can be assembled from editions that were built elsewhere or filed under the wrong key,
+ * and a misfiled edition makes every lookup in its year report `missing-edition` while the data sits one
+ * key away.
+ */
+declare function defineDateFactCalendar<TEntry extends object>(input: {
+  readonly timeZone: string;
+  readonly editions: Readonly<Record<string, AttributedDateEdition<TEntry>>>;
+}): DateFactCalendar<TEntry>;
+/**
+ * Look up one civil date. NEVER falls back to "not listed" for data that is absent rather than empty.
+ *
+ * Order matters: the edition is resolved first, then coverage, then membership. Checking membership
+ * first would answer `not-listed` for a year nobody has entered — which is the whole bug.
+ */
+declare function lookupDateFact<TEntry extends object>(calendar: DateFactCalendar<TEntry>, date: CivilDate): DateFactLookup<TEntry>;
+/**
+ * Look up the civil date an INSTANT falls on, resolved in the CALENDAR'S zone.
+ *
+ * Prefer this over converting yourself. `lookupDateFact` takes a `CivilDate`, and producing one from an
+ * instant requires a zone — if the caller picks its own (the server's, or UTC) it will disagree with the
+ * calendar near midnight and be wrong by a whole day at the boundary. The calendar already knows the
+ * only correct zone, so the conversion belongs here rather than at every call site.
+ */
+declare function lookupDateFactAt<TEntry extends object>(calendar: DateFactCalendar<TEntry>, instant: Date): DateFactLookup<TEntry>;
+/** A public holiday, as published. `label` is the occasion's name, for display and audit. */
+interface PublicHolidayEntry {
+  readonly label: string;
+}
+/** A jurisdiction's public-holiday calendar. The company-scoped, statutory one. */
+type PublicHolidayCalendar = DateFactCalendar<PublicHolidayEntry>;
+/**
+ * An employer closure, which unlike a public holiday can also declare a date OPEN.
+ *
+ * The `open` arm exists because a branch override must be able to CONTRADICT a company-wide closure —
+ * the branch works that day. Modelled as a discriminated union rather than a boolean so a merge
+ * replaces the whole value per date; recursively merging `{state:'closed',label}` onto
+ * `{state:'open',reason}` would leave both fields and satisfy neither arm.
+ */
+type EmployerClosureEntry = {
+  readonly state: 'closed';
+  readonly label: string;
+} | {
+  readonly state: 'open';
+  readonly reason: string;
+};
+//#endregion
+export { AttributedDateEdition, CoveredDateEdition, DateAuthority, DateCoverage, DateEntryInput, DateFactCalendar, DateFactLookup, DateFactUnknownReason, DefineDateEditionInput, EmployerClosureEntry, InvalidDateEditionError, InvalidDateFactCalendarError, PublicHolidayCalendar, PublicHolidayEntry, defineDateEdition, defineDateFactCalendar, lookupDateFact, lookupDateFactAt };

package/dist/calendar-facts.mjs

@@ -0,0 +1,187 @@
+import { civilDateOf, civilDaysBetween, isCivilDate, isValidTimeZone } from "./timezone.mjs";
+//#region src/scheduling/calendar-facts.ts
+/**
+* CALENDAR FACTS — attested sets of civil dates, and a lookup that can say "I do not know".
+*
+* A calendar fact is "this date is listed in a dataset somebody vouches for". It is deliberately NOT
+* "this is a working day": that conclusion also depends on weekly schedules, shifts, substitutions and
+* whichever law is asking. Consumers convert facts into their own verdicts — a tax pack into
+* `holiday | working-day | unknown`, payroll into a premium rate, leave into whether balance is
+* consumed. See {@link DateFactLookup}.
+*
+* ## Why this is a sibling of `sla-policy`, not a field on it
+*
+* `WorkingHours` in `./sla-policy` is an SLA SCHEDULE — weekdays plus start/end minutes, with an
+* optional list of skipped dates. Gazette authority and completeness are not schedule properties, and
+* bolting them on would couple statutory tax evidence to support hours while leaving the meaning of the
+* shared field ambiguous per consumer. So these are separate types over the same `CivilDate`.
+*
+* ## The property everything else rests on: COVERAGE
+*
+* A bare `string[]` of holidays cannot express *unknown*. A date absent from the list is
+* indistinguishable from a date nobody has entered yet, so a 2029 deadline checked against a 2026 list
+* reads as a working day — a confident wrong answer, from data that was simply not there.
+*
+* An {@link CoveredDateEdition} therefore carries the bounds it is asserted COMPLETE for. Inside them,
+* absent means not-listed. Outside them, absent means `unknown`. A dataset cannot prove its own
+* completeness, so someone has to declare it — the same reasoning as a tax pack's gazette-coverage
+* claim, and the reason a missing edition can never silently become an empty-but-complete one.
+*
+* ## Input is a LIST, storage is date-KEYED — and that is not incidental
+*
+* The constructors take an array (what an importer or a spreadsheet produces) and return a record keyed
+* by date. Two reasons:
+*
+*   1. **duplicates are caught at construction.** A list can carry the same date twice with different
+*      labels; a record cannot, and building one silently would drop whichever came first.
+*   2. **records overlay safely, arrays do not.** A config layer that merges a branch override onto a
+*      company default REPLACES arrays wholesale — so a branch list would erase the company list with
+*      no error at all. Keyed entries merge per date.
+*/
+/** Thrown by {@link defineDateEdition}. Carries every problem, not the first. */
+var InvalidDateEditionError = class extends Error {
+	problems;
+	constructor(year, problems) {
+		super(`[primitives] Cannot define a date edition for "${year}" — ${problems.length} problem(s):\n` + problems.map((p) => `  - ${p}`).join("\n"));
+		this.name = "InvalidDateEditionError";
+		this.problems = problems;
+	}
+};
+const YEAR_PATTERN = /^\d{4}$/;
+/**
+* Build a validated edition, or throw naming every problem.
+*
+* REPORTS ALL problems rather than the first: an operator fixing a year's holiday list wants the whole
+* list of bad rows, and returning one at a time turns one correction into twenty round trips.
+*/
+function defineDateEdition(input) {
+	const problems = [];
+	const { year, coverage, authority, dates, allowPartialYear = false } = input;
+	if (!YEAR_PATTERN.test(year)) problems.push(`year must be YYYY; got "${year}"`);
+	if (!authority || !authority.issuer?.trim()) problems.push("authority.issuer is required and must be non-empty — an unattributed dataset cannot support a statutory claim");
+	if (!authority || !authority.reference?.trim()) problems.push("authority.reference is required and must be non-empty — cite the instrument, not the tool that relayed it");
+	if (authority?.publishedOn !== void 0 && !isCivilDate(authority.publishedOn)) problems.push(`authority.publishedOn must be a civil date (YYYY-MM-DD); got "${String(authority.publishedOn)}"`);
+	const from = coverage?.from;
+	const through = coverage?.through;
+	if (!isCivilDate(from)) problems.push(`coverage.from must be a civil date (YYYY-MM-DD); got "${String(from)}"`);
+	if (!isCivilDate(through)) problems.push(`coverage.through must be a civil date (YYYY-MM-DD); got "${String(through)}"`);
+	if (isCivilDate(from) && isCivilDate(through)) {
+		if (civilDaysBetween(from, through) < 0) problems.push(`coverage.from (${from}) is after coverage.through (${through})`);
+		if (YEAR_PATTERN.test(year)) {
+			if (from.slice(0, 4) !== year || through.slice(0, 4) !== year) problems.push(`edition key "${year}" disagrees with its coverage (${from} … ${through}) — an edition spans exactly one year`);
+			else if (!allowPartialYear && (from !== `${year}-01-01` || through !== `${year}-12-31`)) problems.push(`coverage (${from} … ${through}) is narrower than the full year "${year}". An annual gazette covers the whole year, so this is usually an unfinished import; pass allowPartialYear if it is deliberate`);
+		}
+	}
+	const built = {};
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, row] of dates.entries()) {
+		if (!isCivilDate(row?.date)) {
+			problems.push(`dates[${index}].date must be a civil date (YYYY-MM-DD); got "${String(row?.date)}"`);
+			continue;
+		}
+		if (seen.has(row.date)) {
+			/**
+			* A duplicate is REFUSED, never last-write-wins. Two rows for one date disagree about something,
+			* and quietly keeping one drops a fact an operator entered on purpose.
+			*/
+			problems.push(`dates[${index}] repeats ${row.date} — a date may be listed once per edition`);
+			continue;
+		}
+		if (isCivilDate(from) && isCivilDate(through)) {
+			if (civilDaysBetween(from, row.date) < 0 || civilDaysBetween(row.date, through) < 0) {
+				problems.push(`dates[${index}] (${row.date}) falls outside the declared coverage ${from} … ${through}`);
+				continue;
+			}
+		}
+		if (row.entry === null || typeof row.entry !== "object") {
+			problems.push(`dates[${index}].entry must be an object; got ${String(row.entry)}`);
+			continue;
+		}
+		seen.add(row.date);
+		built[row.date] = row.entry;
+	}
+	if (problems.length > 0) throw new InvalidDateEditionError(year, problems);
+	return {
+		coverage: {
+			from,
+			through
+		},
+		authority,
+		dates: built
+	};
+}
+/** Thrown by {@link defineDateFactCalendar}. */
+var InvalidDateFactCalendarError = class extends Error {
+	problems;
+	constructor(problems) {
+		super(`[primitives] Cannot define a date-fact calendar — ${problems.length} problem(s):\n` + problems.map((p) => `  - ${p}`).join("\n"));
+		this.name = "InvalidDateFactCalendarError";
+		this.problems = problems;
+	}
+};
+/**
+* Build a validated calendar. **The timezone is checked here, not trusted.**
+*
+* A civil date has no meaning without a zone, and a WRONG zone is worse than a missing one: it shifts
+* every boundary by the offset while every value still looks like a date. Asia/Dhaka is UTC+6, so a
+* calendar read in UTC disagrees with the business day for six hours at both ends — the same failure
+* that once reported August revenue as July for the last six hours of every month.
+*
+* Also re-checks each edition's key against its own coverage. `defineDateEdition` already enforces that,
+* but a calendar can be assembled from editions that were built elsewhere or filed under the wrong key,
+* and a misfiled edition makes every lookup in its year report `missing-edition` while the data sits one
+* key away.
+*/
+function defineDateFactCalendar(input) {
+	const problems = [];
+	if (typeof input.timeZone !== "string" || input.timeZone.length === 0) problems.push("timeZone is required — a civil date has no meaning without the zone it is civil in");
+	else if (!isValidTimeZone(input.timeZone)) problems.push(`timeZone "${input.timeZone}" is not a recognised IANA zone. A wrong zone shifts every boundary by its offset while every value still looks like a valid date`);
+	for (const [key, edition] of Object.entries(input.editions)) {
+		if (!YEAR_PATTERN.test(key)) {
+			problems.push(`edition key "${key}" must be YYYY`);
+			continue;
+		}
+		if (edition.coverage.from.slice(0, 4) !== key || edition.coverage.through.slice(0, 4) !== key) problems.push(`edition "${key}" is filed under a year its coverage (${edition.coverage.from} … ${edition.coverage.through}) does not match — every lookup in ${key} would report missing-edition`);
+	}
+	if (problems.length > 0) throw new InvalidDateFactCalendarError(problems);
+	return {
+		timeZone: input.timeZone,
+		editions: input.editions
+	};
+}
+/**
+* Look up one civil date. NEVER falls back to "not listed" for data that is absent rather than empty.
+*
+* Order matters: the edition is resolved first, then coverage, then membership. Checking membership
+* first would answer `not-listed` for a year nobody has entered — which is the whole bug.
+*/
+function lookupDateFact(calendar, date) {
+	const edition = calendar.editions[date.slice(0, 4)];
+	if (edition === void 0) return {
+		kind: "unknown",
+		reason: "missing-edition"
+	};
+	const { from, through } = edition.coverage;
+	if (civilDaysBetween(from, date) < 0 || civilDaysBetween(date, through) < 0) return {
+		kind: "unknown",
+		reason: "outside-coverage"
+	};
+	const entry = edition.dates[date];
+	return entry === void 0 ? { kind: "not-listed" } : {
+		kind: "listed",
+		entry
+	};
+}
+/**
+* Look up the civil date an INSTANT falls on, resolved in the CALENDAR'S zone.
+*
+* Prefer this over converting yourself. `lookupDateFact` takes a `CivilDate`, and producing one from an
+* instant requires a zone — if the caller picks its own (the server's, or UTC) it will disagree with the
+* calendar near midnight and be wrong by a whole day at the boundary. The calendar already knows the
+* only correct zone, so the conversion belongs here rather than at every call site.
+*/
+function lookupDateFactAt(calendar, instant) {
+	return lookupDateFact(calendar, civilDateOf(instant, calendar.timeZone));
+}
+//#endregion
+export { InvalidDateEditionError, InvalidDateFactCalendarError, defineDateEdition, defineDateFactCalendar, lookupDateFact, lookupDateFactAt };

package/dist/fault-attribution.d.mts

@@ -0,0 +1,98 @@
+//#region src/composition/fault-attribution.d.ts
+/**
+ * Fault attribution value object + pure helpers.
+ *
+ * Answers ONE question every domain eventually asks: **when something goes
+ * wrong, who bears the cost?** A returned item's shipping, a redelivery after a
+ * failed drop, a re-issued card, an SLA credit, a scrapped inbound transfer —
+ * all the same shape: a reason code implies a responsible party, and whoever is
+ * responsible pays.
+ *
+ * The primitive is *pure data + pure helpers* — no persistence, no events, and
+ * deliberately NO vocabulary of its own. Each domain owns its reason codes and
+ * supplies a `FaultPolicy` mapping them to parties; the primitive owns the
+ * attribution RULES, which are what actually drift between implementations.
+ *
+ * Consumers: `@classytic/order` (RMA return-shipping liability),
+ * `@classytic/flow` (damaged inbound), `@classytic/carrier` (failed delivery
+ * attempts), and any SLA credit built on `primitives/sla-policy`.
+ *
+ * ## Why this exists as a primitive
+ *
+ * `@classytic/order` documented "`merchantPaysReturnShipping` defaults from the
+ * line-level reasons" and then shipped `input.merchantPaysReturnShipping ??
+ * false`. The lookup never ran, so a `damaged_in_transit` return — squarely the
+ * merchant's fault — billed the CUSTOMER for return shipping. Nothing threw;
+ * the field held a plausible boolean.
+ *
+ * A boolean is the wrong type for this. `false` cannot distinguish "the
+ * customer is responsible" from "nobody has decided yet", so the unset case
+ * silently becomes a verdict against whoever `false` happens to mean. Modelling
+ * the PARTY, with `unknown` as a real member, makes that impossible to express
+ * by accident.
+ *
+ * @example
+ * import { attributeFault, bearsCost } from '@classytic/primitives/fault-attribution';
+ *
+ * const RETURN_FAULT = {
+ *   defective: 'merchant',
+ *   damaged_in_transit: 'merchant',
+ *   changed_mind: 'customer',
+ * } as const;
+ *
+ * attributeFault(RETURN_FAULT, ['damaged_in_transit']);            // 'merchant'
+ * attributeFault(RETURN_FAULT, ['changed_mind'], 'merchant');      // 'merchant' — explicit wins
+ * attributeFault(RETURN_FAULT, ['act_of_god']);                    // 'unknown' — NOT 'customer'
+ * bearsCost(attributeFault(RETURN_FAULT, ['defective']), 'merchant'); // true
+ */
+/**
+ * Who is responsible for the cost.
+ *
+ * `unknown` is a first-class member, not a gap. An unrecognised reason is an
+ * unanswered question, and answering it by default is how a system quietly
+ * bills the wrong party — the same asymmetry that makes a payment timeout
+ * `unknown` rather than `declined`.
+ *
+ * `shared` exists because real disputes settle that way (split shipping,
+ * goodwill on a customer-fault return). It is a DECISION, so it is only ever
+ * reachable through an explicit override — never inferred from a reason.
+ */
+type FaultParty = 'merchant' | 'customer' | 'carrier' | 'shared' | 'unknown';
+/** Reason code → responsible party. The domain owns the keys. */
+type FaultPolicy<TReason extends string = string> = Readonly<Partial<Record<TReason, FaultParty>>>;
+/**
+ * Attribute fault across one or more reasons.
+ *
+ * Rules, in order:
+ *
+ * 1. **An explicit decision always wins.** A human or an upstream policy that
+ *    said "the merchant covers this" outranks any reason lookup — a general
+ *    default must never override a specific instruction.
+ * 2. **Merchant fault is sticky.** If ANY reason is the merchant's fault, the
+ *    whole claim is: a customer returning three items, one of them defective,
+ *    is not asked to part-pay the shipping. This is the single rule most likely
+ *    to be re-implemented differently per call site, which is why it lives here.
+ * 3. **Carrier before customer.** A carrier-fault reason is not the customer's
+ *    problem even though the merchant may recover it separately.
+ * 4. **Otherwise the reasons must AGREE.** Mixed or unmapped reasons yield
+ *    `unknown` rather than a guess.
+ * 5. **No reasons at all is `unknown`**, never a party.
+ */
+declare function attributeFault<TReason extends string>(policy: FaultPolicy<TReason>, reasons: readonly TReason[], explicit?: FaultParty | undefined): FaultParty;
+/**
+ * Does `party` bear the cost?
+ *
+ * `shared` bears it for every named party — a split is not an escape from
+ * paying. `unknown` bears nothing: an undecided claim must not auto-charge
+ * anyone, which is the whole reason `unknown` is modelled.
+ */
+declare function bearsCost(attributed: FaultParty, party: Exclude<FaultParty, 'unknown'>): boolean;
+/**
+ * True when attribution is still open and a human (or a later signal) must
+ * decide. Use it to route a claim to review instead of letting it settle at a
+ * default — an `unknown` that silently behaves like `customer` is the defect
+ * this primitive exists to prevent.
+ */
+declare function needsFaultReview(attributed: FaultParty): boolean;
+//#endregion
+export { FaultParty, FaultPolicy, attributeFault, bearsCost, needsFaultReview };

package/dist/fault-attribution.mjs

@@ -0,0 +1,51 @@
+//#region src/composition/fault-attribution.ts
+/**
+* Attribute fault across one or more reasons.
+*
+* Rules, in order:
+*
+* 1. **An explicit decision always wins.** A human or an upstream policy that
+*    said "the merchant covers this" outranks any reason lookup — a general
+*    default must never override a specific instruction.
+* 2. **Merchant fault is sticky.** If ANY reason is the merchant's fault, the
+*    whole claim is: a customer returning three items, one of them defective,
+*    is not asked to part-pay the shipping. This is the single rule most likely
+*    to be re-implemented differently per call site, which is why it lives here.
+* 3. **Carrier before customer.** A carrier-fault reason is not the customer's
+*    problem even though the merchant may recover it separately.
+* 4. **Otherwise the reasons must AGREE.** Mixed or unmapped reasons yield
+*    `unknown` rather than a guess.
+* 5. **No reasons at all is `unknown`**, never a party.
+*/
+function attributeFault(policy, reasons, explicit) {
+	if (explicit !== void 0) return explicit;
+	if (reasons.length === 0) return "unknown";
+	const parties = reasons.map((r) => policy[r] ?? "unknown");
+	if (parties.includes("merchant")) return "merchant";
+	if (parties.includes("carrier")) return "carrier";
+	const first = parties[0];
+	return parties.every((p) => p === first) ? first : "unknown";
+}
+/**
+* Does `party` bear the cost?
+*
+* `shared` bears it for every named party — a split is not an escape from
+* paying. `unknown` bears nothing: an undecided claim must not auto-charge
+* anyone, which is the whole reason `unknown` is modelled.
+*/
+function bearsCost(attributed, party) {
+	if (attributed === "unknown") return false;
+	if (attributed === "shared") return true;
+	return attributed === party;
+}
+/**
+* True when attribution is still open and a human (or a later signal) must
+* decide. Use it to route a claim to review instead of letting it settle at a
+* default — an `unknown` that silently behaves like `customer` is the defect
+* this primitive exists to prevent.
+*/
+function needsFaultReview(attributed) {
+	return attributed === "unknown";
+}
+//#endregion
+export { attributeFault, bearsCost, needsFaultReview };

package/dist/memory-outbox.d.mts

@@ -1,5 +1,5 @@
 import { DeadLetteredEvent, DomainEvent } from "./events.mjs";
-import { OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxErrorInfo, OutboxFailOptions, OutboxStatus, OutboxStore, OutboxWriteOptions } from "./outbox.mjs";
+import { OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxClaimedEvent, OutboxErrorInfo, OutboxFailOptions, OutboxStatus, OutboxStore, OutboxWriteOptions } from "./outbox.mjs";
 //#region src/events/memory-outbox.d.ts
 interface MemoryEntry {
   event: DomainEvent;
@@ -7,6 +7,8 @@ interface MemoryEntry {
   attempts: number;
   visibleAt: number;
   leaseOwner: string | null;
+  /** Fencing token — one per claim epoch of this event. */
+  fenceToken?: number;
   leaseExpiresAt: number;
   deliveredAt: number | null;
   firstFailedAt: number | null;
@@ -44,6 +46,7 @@ declare class MemoryOutboxStore implements OutboxStore {
   save(event: DomainEvent, options?: OutboxWriteOptions): Promise<void>;
   getPending(limit: number): Promise<DomainEvent[]>;
   claimPending(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
+  claimPendingFenced(options?: OutboxClaimOptions): Promise<OutboxClaimedEvent[]>;
   acknowledge(eventId: string, options?: OutboxAcknowledgeOptions): Promise<void>;
   fail(eventId: string, error: OutboxErrorInfo, options?: OutboxFailOptions): Promise<void>;
   getDeadLettered(limit: number): Promise<DeadLetteredEvent[]>;

package/dist/memory-outbox.mjs

@@ -53,6 +53,9 @@ var MemoryOutboxStore = class {
 		return this.entries.filter((e) => e.status === "pending" && e.visibleAt <= now && (e.leaseOwner === null || e.leaseExpiresAt <= now)).slice(0, limit).map((e) => e.event);
 	}
 	async claimPending(options) {
+		return (await this.claimPendingFenced(options)).map((c) => c.event);
+	}
+	async claimPendingFenced(options) {
 		const now = Date.now();
 		const limit = options?.limit ?? 100;
 		const leaseMs = options?.leaseMs ?? DEFAULT_LEASE_MS;
@@ -68,7 +71,11 @@ var MemoryOutboxStore = class {
 			entry.leaseOwner = consumerId;
 			entry.leaseExpiresAt = now + leaseMs;
 			entry.attempts++;
-			claimed.push(entry.event);
+			entry.fenceToken = (entry.fenceToken ?? 0) + 1;
+			claimed.push({
+				event: entry.event,
+				fencingToken: entry.fenceToken
+			});
 		}
 		return claimed;
 	}
@@ -77,6 +84,7 @@ var MemoryOutboxStore = class {
 		if (!entry) return;
 		if (entry.status === "delivered") return;
 		if (options?.consumerId && entry.leaseOwner && entry.leaseOwner !== options.consumerId) throw new OutboxOwnershipError(eventId, options.consumerId, entry.leaseOwner);
+		if (options?.fencingToken !== void 0 && options.fencingToken !== entry.fenceToken) throw new OutboxOwnershipError(eventId, `token ${options.fencingToken}`, `token ${entry.fenceToken}`);
 		entry.status = "delivered";
 		entry.deliveredAt = Date.now();
 		entry.leaseOwner = null;