@classytic/primitives 0.22.0 → 0.24.0

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/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.22.0",
+  "version": "0.24.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"