@classytic/primitives 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.32.0",
+  "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",