@classytic/primitives 0.31.1 → 0.33.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.33.0 — 2026-10-14
+
+### Changed — `inventory/line-settlement` settles decimal quantities on the 6-dp grid
+- `planSettlement`, `clampSettlement`, `settledTotal`, `outstandingOf`, `settledEntirelyIn` and `shareOfSettled` add, subtract and compare
+  on the grid (`addQuantity` / `subtractQuantity`), so 0.1 + 0.2 settles exactly 0.3 and a weighed line can be received in parts.
+  Whole-unit inputs behave as before.
+- A non-positive or off-grid request is refused with code `not_positive_quantity` (was `not_positive_integer`; no in-repo consumer
+  branches on the old code).
+
+## 0.32.0 — 2026-10-12
+
+### Added — `./quantity`: the step and running-sum helpers every package was copying
+
+Seven packages (order, cart, catalog, invoice, bd-tax, commerce-ui, pos-ui) each carried their own copy of the quantity grid; the pieces the grid did not yet offer are now here, so a consumer imports instead of copying.
+- `isQuantityStep(step)` — a guard for a usable step (a positive number on the grid, at least one grid unit). True exactly when `quantityStepToGrid` accepts it, pinned by a property test. For untrusted input (a stored `quantityStep`, a request body), where a throw is the wrong answer.
+- `isOnStepStrict(quantity, step)` — is the quantity ON the grid and a whole multiple of a valid step? STRICT and total: junk, an off-grid quantity or an invalid step is `false`, never a throw and never a snap. `isOnStep` is unchanged (it snaps first and throws on a bad step; its docs now say so and point here).
+- `addQuantity(a, b)` / `subtractQuantity(a, b)` — arithmetic on the grid, so a running sum never drifts (`1.2 + 1.15` is `2.35`). Zero is `0`, never `-0`. A non-finite operand throws `QuantityError`, as everywhere in the grid.
+
 ## 0.31.1 — 2026-10-11
 
 ### Fixed — `convertWithSnapshot` is exact (`./currency`)

package/dist/line-settlement.d.mts

@@ -10,7 +10,8 @@ import { Result } from "./result.mjs";
  * kernel's vocabulary; the arithmetic, the over-settlement guard and the state
  * derivation are this file's, so no two kernels can answer differently.
  *
- * Quantities are whole units. A bucket that is absent counts as zero.
+ * Quantities are decimals on the 6-dp grid (`./quantity`): whole units for a countable item, 2.35 for a weighed one.
+ * Every sum and comparison is exact on the grid. A bucket that is absent counts as zero.
  */
 interface SettlementLine<B extends string> {
   /** What the line promised to move. */
@@ -34,7 +35,7 @@ declare const documentSettlementState: <B extends string>(lines: ReadonlyArray<S
 /** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
 declare const settledEntirelyIn: <B extends string>(lines: ReadonlyArray<SettlementLine<B>>, bucket: B) => boolean;
 type SettlementRefusal = {
-  readonly code: "not_positive_integer";
+  readonly code: "not_positive_quantity";
   readonly requested: number;
 } | {
   readonly code: "exceeds_outstanding";
@@ -44,7 +45,7 @@ type SettlementRefusal = {
 /**
  * Settle `quantity` more units into `bucket`, or refuse.
  *
- * Refuses a non-positive or fractional quantity and anything above what is
+ * Refuses a non-positive quantity, one off the 6-dp grid, and anything above what is
  * outstanding — an over-settlement is an input error, never silently trimmed.
  * Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
  */
@@ -61,7 +62,7 @@ declare const clampSettlement: <B extends string>(line: SettlementLine<B>, bucke
  * The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
  * settlement batch, given how many units the whole line had settled before and after it.
  *
- * `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+ * `floor(total·after/q) − floor(total·before/q)` (units on the 6-dp grid) TELESCOPES: however a line is split into
  * batches, and across every outcome bucket, the shares sum to exactly `total` once the line
  * is fully settled — no remainder to chase, no batch-order dependence.
  */

package/dist/line-settlement.mjs

@@ -1,13 +1,14 @@
+import { QUANTITY_SCALE, addQuantity, compareQuantity, isOnQuantityGrid, quantityToGrid, snapQuantity, subtractQuantity } from "./quantity.mjs";
 import { err, ok } from "./result.mjs";
 //#region src/inventory/line-settlement.ts
 /** Sum of every bucket. */
-const settledTotal = (line) => Object.values(line.settled).reduce((sum, n) => sum + (n ?? 0), 0);
+const settledTotal = (line) => Object.values(line.settled).reduce((sum, n) => addQuantity(sum, n ?? 0), 0);
 /**
 * `quantity − Σ buckets`. NOT clamped at zero: a negative means the line was
 * over-settled by data written outside {@link planSettlement}, and hiding it
 * would erase the only signal that happened.
 */
-const outstandingOf = (line) => line.quantity - settledTotal(line);
+const outstandingOf = (line) => subtractQuantity(line.quantity, settledTotal(line));
 /** `open` — nothing settled; `settled` — nothing outstanding; otherwise `partial`. */
 const settlementState = (line) => {
 	if (outstandingOf(line) <= 0) return "settled";
@@ -21,21 +22,21 @@ const documentSettlementState = (lines) => {
 	return "partial";
 };
 /** `true` when every line is settled entirely through `bucket` (e.g. all received, nothing lost). */
-const settledEntirelyIn = (lines, bucket) => lines.every((l) => (l.settled[bucket] ?? 0) >= l.quantity);
+const settledEntirelyIn = (lines, bucket) => lines.every((l) => compareQuantity(l.settled[bucket] ?? 0, l.quantity) >= 0);
 /**
 * Settle `quantity` more units into `bucket`, or refuse.
 *
-* Refuses a non-positive or fractional quantity and anything above what is
+* Refuses a non-positive quantity, one off the 6-dp grid, and anything above what is
 * outstanding — an over-settlement is an input error, never silently trimmed.
 * Use {@link clampSettlement} only where the surface's CONTRACT is "take what fits".
 */
 const planSettlement = (line, bucket, quantity) => {
-	if (!Number.isInteger(quantity) || quantity <= 0) return err({
-		code: "not_positive_integer",
+	if (!(quantity > 0) || !isOnQuantityGrid(quantity)) return err({
+		code: "not_positive_quantity",
 		requested: quantity
 	});
 	const outstanding = outstandingOf(line);
-	if (quantity > outstanding) return err({
+	if (compareQuantity(quantity, outstanding) > 0) return err({
 		code: "exceeds_outstanding",
 		requested: quantity,
 		outstanding
@@ -47,7 +48,10 @@ const planSettlement = (line, bucket, quantity) => {
 * `applied` is what was actually settled; `0` leaves the line unchanged.
 */
 const clampSettlement = (line, bucket, requested) => {
-	const applied = Math.max(0, Math.min(Math.trunc(requested), outstandingOf(line)));
+	const wanted = requested > 0 ? isOnQuantityGrid(requested) ? requested : Math.floor(requested * QUANTITY_SCALE) / QUANTITY_SCALE : 0;
+	const fits = snapQuantity(wanted);
+	const outstanding = outstandingOf(line);
+	const applied = compareQuantity(fits, outstanding) <= 0 ? fits : Math.max(0, outstanding);
 	return {
 		line: applied > 0 ? withBucket(line, bucket, applied) : line,
 		applied
@@ -57,22 +61,23 @@ const clampSettlement = (line, bucket, requested) => {
 * The share of a line-level amount (a value or a cost, integer MINOR units) owed by one
 * settlement batch, given how many units the whole line had settled before and after it.
 *
-* `floor(total·after/q) − floor(total·before/q)` TELESCOPES: however a line is split into
+* `floor(total·after/q) − floor(total·before/q)` (units on the 6-dp grid) TELESCOPES: however a line is split into
 * batches, and across every outcome bucket, the shares sum to exactly `total` once the line
 * is fully settled — no remainder to chase, no batch-order dependence.
 */
 const shareOfSettled = (total, quantity, settledBefore, settledAfter) => {
 	if (!Number.isInteger(total) || total < 0) throw new RangeError(`total must be a non-negative integer, got ${total}`);
-	if (!Number.isInteger(quantity) || quantity <= 0) throw new RangeError(`quantity must be a positive integer, got ${quantity}`);
-	if (!(0 <= settledBefore && settledBefore <= settledAfter && settledAfter <= quantity)) throw new RangeError(`need 0 <= before (${settledBefore}) <= after (${settledAfter}) <= quantity (${quantity})`);
-	const at = (n) => Number(BigInt(total) * BigInt(n) / BigInt(quantity));
+	if (!(quantity > 0) || !isOnQuantityGrid(quantity)) throw new RangeError(`quantity must be positive with at most 6 decimals, got ${quantity}`);
+	if (!(0 <= settledBefore && compareQuantity(settledBefore, settledAfter) <= 0 && compareQuantity(settledAfter, quantity) <= 0)) throw new RangeError(`need 0 <= before (${settledBefore}) <= after (${settledAfter}) <= quantity (${quantity})`);
+	const q = quantityToGrid(quantity);
+	const at = (n) => Number(BigInt(total) * quantityToGrid(n) / q);
 	return at(settledAfter) - at(settledBefore);
 };
 const withBucket = (line, bucket, quantity) => ({
 	quantity: line.quantity,
 	settled: {
 		...line.settled,
-		[bucket]: (line.settled[bucket] ?? 0) + quantity
+		[bucket]: addQuantity(line.settled[bucket] ?? 0, quantity)
 	}
 });
 //#endregion

package/dist/quantity.d.mts

@@ -28,11 +28,32 @@ declare function snapQuantity(quantity: number, step?: number, mode?: RoundingMo
  * boundary, where a 7th decimal is a caller error rather than float drift.
  */
 declare function isOnQuantityGrid(value: number): boolean;
-/** Is `quantity` a whole multiple of `step`, within half a grid unit? */
+/**
+ * Is `quantity` a whole multiple of `step`, within half a grid unit? Snaps `quantity` first and THROWS
+ * ({@link QuantityError}) on a non-finite quantity or an invalid step. Use {@link isOnStepStrict} where a
+ * malformed input must answer `false` instead.
+ */
 declare function isOnStep(quantity: number, step: number): boolean;
+/**
+ * Is `step` a usable quantity step: a positive number on the grid, at least one grid unit? True exactly
+ * when {@link quantityStepToGrid} accepts it. A guard for untrusted input (a stored `quantityStep`, a
+ * request body) where a throw is the wrong answer.
+ */
+declare function isQuantityStep(step: unknown): step is number;
+/**
+ * Is `quantity` ON the grid and a whole multiple of a valid `step`? STRICT and total: an off-grid or
+ * non-finite quantity, or an invalid step, is `false` — never a throw and never a snap (`2.3500004`
+ * is off the 0.001 step here, on it for {@link isOnStep}). The check for an input boundary, such as a
+ * line quantity against the line's step.
+ */
+declare function isOnStepStrict(quantity: number, step: number): boolean;
+/** `a + b` on the grid, so a running sum never drifts (`1.2 + 1.15` is 2.35, not 2.3499…). */
+declare function addQuantity(a: number, b: number): number;
+/** `a − b` on the grid, so a running balance never drifts. */
+declare function subtractQuantity(a: number, b: number): number;
 /** Compare two quantities on the grid: equal when they snap to the same grid unit. */
 declare function compareQuantity(a: number, b: number): -1 | 0 | 1;
 /** `compareQuantity(a, b) === 0`. */
 declare function quantitiesEqual(a: number, b: number): boolean;
 //#endregion
-export { QUANTITY_SCALE, QuantityError, QuantityErrorCode, type RoundingMode, compareQuantity, isOnQuantityGrid, isOnStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity };
+export { QUANTITY_SCALE, QuantityError, QuantityErrorCode, type RoundingMode, addQuantity, compareQuantity, isOnQuantityGrid, isOnStep, isOnStepStrict, isQuantityStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity, subtractQuantity };

package/dist/quantity.mjs

@@ -70,10 +70,39 @@ function isOnQuantityGrid(value) {
 	const grid = Math.round(scaled);
 	return Number.isSafeInteger(grid) && Math.abs(grid - scaled) <= 1e-9 * Math.max(1, Math.abs(scaled));
 }
-/** Is `quantity` a whole multiple of `step`, within half a grid unit? */
+/**
+* Is `quantity` a whole multiple of `step`, within half a grid unit? Snaps `quantity` first and THROWS
+* ({@link QuantityError}) on a non-finite quantity or an invalid step. Use {@link isOnStepStrict} where a
+* malformed input must answer `false` instead.
+*/
 function isOnStep(quantity, step) {
 	return quantityToGrid(quantity) % quantityStepToGrid(step) === 0n;
 }
+/**
+* Is `step` a usable quantity step: a positive number on the grid, at least one grid unit? True exactly
+* when {@link quantityStepToGrid} accepts it. A guard for untrusted input (a stored `quantityStep`, a
+* request body) where a throw is the wrong answer.
+*/
+function isQuantityStep(step) {
+	return typeof step === "number" && Number.isFinite(step) && step > 0 && isOnQuantityGrid(step) && quantityToGrid(step) > 0n;
+}
+/**
+* Is `quantity` ON the grid and a whole multiple of a valid `step`? STRICT and total: an off-grid or
+* non-finite quantity, or an invalid step, is `false` — never a throw and never a snap (`2.3500004`
+* is off the 0.001 step here, on it for {@link isOnStep}). The check for an input boundary, such as a
+* line quantity against the line's step.
+*/
+function isOnStepStrict(quantity, step) {
+	return isOnQuantityGrid(quantity) && isQuantityStep(step) && isOnStep(quantity, step);
+}
+/** `a + b` on the grid, so a running sum never drifts (`1.2 + 1.15` is 2.35, not 2.3499…). */
+function addQuantity(a, b) {
+	return gridToNumber(quantityToGrid(a) + quantityToGrid(b));
+}
+/** `a − b` on the grid, so a running balance never drifts. */
+function subtractQuantity(a, b) {
+	return gridToNumber(quantityToGrid(a) - quantityToGrid(b));
+}
 /** Compare two quantities on the grid: equal when they snap to the same grid unit. */
 function compareQuantity(a, b) {
 	const ga = quantityToGrid(a);
@@ -85,4 +114,4 @@ function quantitiesEqual(a, b) {
 	return compareQuantity(a, b) === 0;
 }
 //#endregion
-export { QUANTITY_SCALE, QuantityError, compareQuantity, isOnQuantityGrid, isOnStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity };
+export { QUANTITY_SCALE, QuantityError, addQuantity, compareQuantity, isOnQuantityGrid, isOnStep, isOnStepStrict, isQuantityStep, quantitiesEqual, quantityStepToGrid, quantityToGrid, snapQuantity, subtractQuantity };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.31.1",
+  "version": "0.33.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",