@classytic/primitives 0.21.0 → 0.23.0

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,12 +1,14 @@
 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;
-  status: "pending" | "delivered" | "dead_letter";
+  status: 'pending' | 'delivered' | 'dead_letter';
   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

@@ -1,13 +1,5 @@
 import { InvalidOutboxEventError, OutboxOwnershipError } from "./outbox.mjs";
 //#region src/events/memory-outbox.ts
-/**
-* In-memory outbox store — reference implementation for dev / testing.
-*
-* Supports the full `OutboxStore` capability set (claim/lease, fail/retry,
-* dedupe, visibleAt). Production deployments should pass a `repository` to
-* `EventOutbox` instead of using this; the memory store exists for unit
-* tests and single-process dev where durable persistence is noise.
-*/
 const DEFAULT_LEASE_MS = 3e4;
 var MemoryOutboxStore = class {
 	entries = [];
@@ -61,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;
@@ -76,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;
 	}
@@ -85,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;

package/dist/outbox.d.mts

@@ -35,15 +35,35 @@ interface OutboxClaimOptions {
   /** Only claim events of these types (optional filter). */
   readonly types?: readonly string[];
 }
+/**
+ * A claim result carrying the FENCING TOKEN — returned by
+ * {@link OutboxStore.claimPendingFenced}. The token is minted by the STORE
+ * per claim epoch of that event: a re-claim after lease expiry mints a
+ * STRICTLY GREATER token, so a stale ex-holder presenting its old token to
+ * `acknowledge`/`fail` is rejected — the overlap window ownership checks
+ * narrow but cannot close (holder ids recur; epochs do not).
+ */
+interface OutboxClaimedEvent {
+  readonly event: DomainEvent;
+  readonly fencingToken: number;
+}
 /** Options for {@link OutboxStore.acknowledge}. */
 interface OutboxAcknowledgeOptions {
   /** Worker identifier — stores may enforce "only owner can ack". */
   readonly consumerId?: string;
+  /**
+   * Fencing token from {@link OutboxStore.claimPendingFenced}. Stores that
+   * fence MUST throw {@link OutboxOwnershipError} when it is not the event's
+   * CURRENT claim token.
+   */
+  readonly fencingToken?: number;
 }
 /** Options for {@link OutboxStore.fail}. */
 interface OutboxFailOptions {
   /** Worker identifier — stores may enforce "only owner can fail". */
   readonly consumerId?: string;
+  /** Fencing token — same contract as {@link OutboxAcknowledgeOptions.fencingToken}. */
+  readonly fencingToken?: number;
   /** Schedule retry for a later time (implements backoff). */
   readonly retryAt?: Date;
   /** Move the event to dead-letter state (no further retries). */
@@ -213,6 +233,13 @@ interface OutboxStore {
    * prefers this over `getPending`.
    */
   claimPending?(options?: OutboxClaimOptions): Promise<DomainEvent[]>;
+  /**
+   * FENCED claim — same atomic semantics as `claimPending`, returning each
+   * event with a store-minted fencing token (see {@link OutboxClaimedEvent}).
+   * Additive and feature-detected, mirroring `LockAdapter.tryAcquireFenced`:
+   * a store that cannot mint monotonic per-event tokens omits this method.
+   */
+  claimPendingFenced?(options?: OutboxClaimOptions): Promise<OutboxClaimedEvent[]>;
   /**
    * Mark event as successfully relayed.
    *
@@ -291,4 +318,4 @@ interface OutboxStore {
   oldestPendingAgeMs?(): Promise<number | null>;
 }
 //#endregion
-export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStatus, OutboxStore, OutboxWriteOptions };
+export { InvalidOutboxEventError, OUTBOX_STATUSES, OutboxAcknowledgeOptions, OutboxClaimOptions, OutboxClaimedEvent, OutboxErrorInfo, OutboxFailOptions, OutboxFailureContext, OutboxFailureDecision, OutboxFailurePolicy, OutboxOwnershipError, OutboxStatus, OutboxStore, OutboxWriteOptions };

package/dist/period.d.mts

@@ -160,6 +160,30 @@ declare function resolvePeriod(period: Period, timezone?: string): DateRange;
  * For the `$lte` call sites that predate half-open ranges. Derived from the
  * resolved end rather than `start + 24h - 1`, so it stays DST-exact.
  */
+/**
+ * Shift a MONTH or QUARTER period by `n` of its own units (negative = back).
+ *
+ * The arithmetic a caller would otherwise write inline, and the reason this is
+ * here rather than in each of them: "two filing months ago" is a `Period`
+ * question, and the shapes reachable without it are both wrong in the same way.
+ *
+ *   `new Date(Date.UTC(y, m - 1 - n, 1))` — a UTC instant used to answer a
+ *   BUSINESS-calendar question. Six hours off in Asia/Dhaka at both ends; the
+ *   five silent defects in this module's header are all that shape.
+ *
+ *   hand-rolled integer math (`y * 12 + (m - 1) - n`) — correct, but it is a
+ *   third copy of a rule the `Period` type already owns, and the year rollover
+ *   is exactly where a copy goes wrong.
+ *
+ * NO Date is constructed and no zone is consulted: shifting a month is pure
+ * calendar arithmetic on `(year, month)`. The `timezone` rides along unchanged,
+ * so the shifted period still resolves against the calendar it was defined in —
+ * `resolvePeriod` / {@link resolveMonth} remain the only places instants appear.
+ *
+ * A YEAR period shifts by years; a `custom` (ad-hoc start/end) period has no
+ * unit to shift and throws rather than guessing one.
+ */
+declare function shiftPeriod(period: Period, n: number): Period;
 declare function inclusiveEnd(range: DateRange): Date;
 /**
  * The period an INSTANT falls in, on the local calendar.
@@ -185,4 +209,4 @@ declare function parsePeriod(label: string, timezone?: string): Period;
  */
 declare function formatPeriod(period: Period): string;
 //#endregion
-export { DateRange, DateRangeError, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear };
+export { DateRange, DateRangeError, Period, PeriodError, PeriodErrorCode, PeriodGranularity, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/period.mjs

@@ -261,6 +261,55 @@ function resolvePeriod(period, timezone) {
 * For the `$lte` call sites that predate half-open ranges. Derived from the
 * resolved end rather than `start + 24h - 1`, so it stays DST-exact.
 */
+/**
+* Shift a MONTH or QUARTER period by `n` of its own units (negative = back).
+*
+* The arithmetic a caller would otherwise write inline, and the reason this is
+* here rather than in each of them: "two filing months ago" is a `Period`
+* question, and the shapes reachable without it are both wrong in the same way.
+*
+*   `new Date(Date.UTC(y, m - 1 - n, 1))` — a UTC instant used to answer a
+*   BUSINESS-calendar question. Six hours off in Asia/Dhaka at both ends; the
+*   five silent defects in this module's header are all that shape.
+*
+*   hand-rolled integer math (`y * 12 + (m - 1) - n`) — correct, but it is a
+*   third copy of a rule the `Period` type already owns, and the year rollover
+*   is exactly where a copy goes wrong.
+*
+* NO Date is constructed and no zone is consulted: shifting a month is pure
+* calendar arithmetic on `(year, month)`. The `timezone` rides along unchanged,
+* so the shifted period still resolves against the calendar it was defined in —
+* `resolvePeriod` / {@link resolveMonth} remain the only places instants appear.
+*
+* A YEAR period shifts by years; a `custom` (ad-hoc start/end) period has no
+* unit to shift and throws rather than guessing one.
+*/
+function shiftPeriod(period, n) {
+	if (!Number.isInteger(n)) throw new PeriodError("INVALID_FIELD", `shiftPeriod expects an integer offset, received ${String(n)}.`);
+	const granularity = granularityOf(period);
+	const zone = period.timezone !== void 0 ? { timezone: period.timezone } : {};
+	if (granularity === "month") {
+		const zeroBased = period.year * 12 + (period.month - 1) + n;
+		return {
+			year: Math.floor(zeroBased / 12),
+			month: zeroBased % 12 + 1,
+			...zone
+		};
+	}
+	if (granularity === "quarter") {
+		const zeroBased = period.year * 4 + (period.quarter - 1) + n;
+		return {
+			year: Math.floor(zeroBased / 4),
+			quarter: zeroBased % 4 + 1,
+			...zone
+		};
+	}
+	if (granularity === "year") return {
+		year: period.year + n,
+		...zone
+	};
+	throw new PeriodError("AMBIGUOUS_PERIOD", "shiftPeriod has no unit to shift for an ad-hoc start/end period — shift the instants, or use a calendar period.");
+}
 function inclusiveEnd(range) {
 	assertUsableRange(range, "range");
 	return /* @__PURE__ */ new Date(range.end.getTime() - 1);
@@ -339,4 +388,4 @@ function formatPeriod(period) {
 	throw new PeriodError("INVALID_LABEL", "An ad-hoc Period (start + end) has no canonical label.");
 }
 //#endregion
-export { DateRangeError, PeriodError, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear };
+export { DateRangeError, PeriodError, dayStart, formatPeriod, granularityOf, inclusiveEnd, isDateRange, isWithin, parsePeriod, periodOf, periodTimeZone, rangeDurationMs, rangesOverlap, resolveDateSpan, resolveDay, resolveMonth, resolvePeriod, resolveQuarter, resolveYear, shiftPeriod };

package/dist/unit-cost-rate.d.mts

@@ -46,9 +46,26 @@ declare function unitCostRateFromTotal<C extends string = string>(totalMinor: nu
  * {@link QTY_SCALE} precision.
  */
 declare function extendedAmount<C extends string = string>(rate: UnitCostRate<C>, quantity: number, mode?: RoundingMode): MinorUnits<C>;
+/**
+ * Incremental weighted-average of two scaled rates — the moving-average (WAC)
+ * receipt step:
+ *
+ *   newRate = (onHandQty × onHandRate + inQty × inRate) / (onHandQty + inQty)
+ *
+ * Both rates must share the same scale (ecosystem-wide {@link RATE_SCALE});
+ * the result is a scaled integer on that same scale. Bigint-exact with the
+ * quantity honoured to {@link QTY_SCALE} precision; rounds once, at the end.
+ *
+ * Degenerate-stock semantics (the moving-average standard): a zero or
+ * NEGATIVE on-hand contributes NOTHING to the average — the incoming rate
+ * RESETS the cost. Averaging against a negative quantity would let a
+ * catch-up receipt swing the rate arbitrarily far from any price ever paid.
+ * Outflows never call this function: an issue leaves the average unchanged.
+ */
+declare function weightedAverageScaledRate(onHandQuantity: number, onHandScaledRate: number, inQuantity: number, inScaledRate: number, mode?: RoundingMode): number;
 /** The rate as a plain (fractional) minor-units-per-unit number — for display only. */
 declare function rateMinorPerUnit(rate: UnitCostRate): number;
 /** Structural guard. */
 declare function isUnitCostRate(value: unknown): value is UnitCostRate;
 //#endregion
-export { RATE_SCALE, RoundingMode, UnitCostRate, UnitCostRateError, UnitCostRateErrorCode, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal };
+export { RATE_SCALE, RoundingMode, UnitCostRate, UnitCostRateError, UnitCostRateErrorCode, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal, weightedAverageScaledRate };

package/dist/unit-cost-rate.mjs

@@ -85,6 +85,35 @@ function extendedAmount(rate, quantity, mode = DEFAULT_ROUNDING) {
 	if (!Number.isSafeInteger(minor)) throw new UnitCostRateError("UNSAFE_INTEGER", `extended amount ${minor} exceeds safe integer range`);
 	return MinorUnits(minor, rate.currency);
 }
+/**
+* Incremental weighted-average of two scaled rates — the moving-average (WAC)
+* receipt step:
+*
+*   newRate = (onHandQty × onHandRate + inQty × inRate) / (onHandQty + inQty)
+*
+* Both rates must share the same scale (ecosystem-wide {@link RATE_SCALE});
+* the result is a scaled integer on that same scale. Bigint-exact with the
+* quantity honoured to {@link QTY_SCALE} precision; rounds once, at the end.
+*
+* Degenerate-stock semantics (the moving-average standard): a zero or
+* NEGATIVE on-hand contributes NOTHING to the average — the incoming rate
+* RESETS the cost. Averaging against a negative quantity would let a
+* catch-up receipt swing the rate arbitrarily far from any price ever paid.
+* Outflows never call this function: an issue leaves the average unchanged.
+*/
+function weightedAverageScaledRate(onHandQuantity, onHandScaledRate, inQuantity, inScaledRate, mode = DEFAULT_ROUNDING) {
+	if (!Number.isFinite(inQuantity) || inQuantity <= 0) throw new UnitCostRateError("NON_POSITIVE_QUANTITY", `incoming quantity must be > 0, got ${inQuantity}`);
+	assertSafe(inScaledRate);
+	const oldQty = Number.isFinite(onHandQuantity) ? Math.max(onHandQuantity, 0) : 0;
+	if (oldQty === 0) return inScaledRate;
+	assertSafe(onHandScaledRate);
+	const oldQ = scaleQuantity(oldQty);
+	const inQ = scaleQuantity(inQuantity);
+	const numerator = oldQ * BigInt(onHandScaledRate) + inQ * BigInt(inScaledRate);
+	const scaled = Number(roundedDiv(numerator, oldQ + inQ, mode));
+	assertSafe(scaled);
+	return scaled;
+}
 /** The rate as a plain (fractional) minor-units-per-unit number — for display only. */
 function rateMinorPerUnit(rate) {
 	return rate.scaledAmount / rate.scale;
@@ -113,4 +142,4 @@ function roundedDiv(numerator, denominator, mode) {
 	return neg ? -result : result;
 }
 //#endregion
-export { RATE_SCALE, UnitCostRateError, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal };
+export { RATE_SCALE, UnitCostRateError, extendedAmount, isUnitCostRate, rateMinorPerUnit, unitCostRate, unitCostRateFromTotal, weightedAverageScaledRate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -45,6 +45,10 @@
       "types": "./dist/calendar.d.mts",
       "default": "./dist/calendar.mjs"
     },
+    "./calendar-facts": {
+      "types": "./dist/calendar-facts.d.mts",
+      "default": "./dist/calendar-facts.mjs"
+    },
     "./timezone": {
       "types": "./dist/timezone.d.mts",
       "default": "./dist/timezone.mjs"
@@ -53,6 +57,10 @@
       "types": "./dist/reference.d.mts",
       "default": "./dist/reference.mjs"
     },
+    "./fault-attribution": {
+      "types": "./dist/fault-attribution.d.mts",
+      "default": "./dist/fault-attribution.mjs"
+    },
     "./context": {
       "types": "./dist/context.d.mts",
       "default": "./dist/context.mjs"