@happyvertical/smrt-commerce 0.55.19 → 0.55.21

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-commerce",
-  "packageVersion": "0.55.19",
+  "packageVersion": "0.55.21",
   "objects": {
     "@happyvertical/smrt-commerce:ContractCollection": {
       "name": "contractcollection",

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-commerce",
-  "packageVersion": "0.55.19",
+  "packageVersion": "0.55.21",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "e4cd1fba44f50fd32926918e426e8fd716e9bb2f655fdc64ad55a9878eb0760a",
-    "packageJson": "4ff5ed22f61fb32cf21459ae0bb4f2142470c1ff6de5afc8a3e5e1f048b37641",
+    "manifest": "6b8d0f3474cfea4182a47e5975d0fcdc3ed3dbcf11ea11f0f1f47c721606c74e",
+    "packageJson": "bf0fd5ea43b2c013affb10bccfa80c885f9128a62cf0862e0d1c03a3a37ac331",
     "agents": "5a4901577a0f007cf44f04658c4394e1b1fe292f24701d0ff00ccf66095b4217",
     "moduleDoc:agents/invoice-quantity.md": "bc3b617d4fb8cc87511763b281283107557ba64795e64522193ef967a3715d32",
     "moduleDoc:agents/payment-allocations.md": "46c0b921f0e40060cd1caec2dcefb01ed6612e31e4bf220a1a0b61e4e2a58212",
@@ -16,7 +16,7 @@
     "moduleDoc:agents/commercial-ui.md": "308729a481c82903d06837e7052c04509a92cf17d17345f71dce88d8d42d0431",
     "moduleDoc:agents/quote-ui.md": "514568e4e7815c47113627ac044a1f31a6933377b3f6c70f5d54b2508d94200c",
     "moduleDoc:agents/purchasing-ui.md": "c7d633c5ba45078c51f4066f68d90112cd748ac089ac34d209f9bf025739589f",
-    "moduleDoc:agents/cost-billing.md": "def9486f25bbe6d7259d50dc6e18e2bd29f60f995d8fcf201a9e8c2ceaa83823"
+    "moduleDoc:agents/cost-billing.md": "e60e6b7285962464e9bbc35ce259f7e99a81f6c9c39ae5855cdd0a34093d8d47"
   },
   "exports": [
     ".",
@@ -19868,7 +19868,7 @@
     {
       "path": "agents/cost-billing.md",
       "module": "cost-billing",
-      "content": "# Exact cost billing\n\n`@happyvertical/smrt-commerce/cost-billing` is an independent, transport-neutral\nentry point without model, server or Svelte dependencies. It does not persist,\npost, authorize, select a currency/jurisdiction, or implement credit-note lifecycle.\nExisting Invoice calculations and editor defaults are unchanged. In particular,\n`calculateInvoiceMinorLine` retains negative ties toward positive infinity; the\nnew opt-in helpers use symmetric half-away-from-zero ties. Positive-only invoice\neditor validation remains distinct from these generic signed calculations.\n\nCall `resolveCostMarkup(overrides)` with caller-approved precedence, most specific\nfirst. Each item has `source`, optional `policy` and `version`, and optional\n`percent`. The first defined percent wins, including `\"0\"`. At least one is\nrequired; even shadowed inputs are validated. The result contains the percent,\nselected index, and detached ordered provenance. Persist accepted snapshots in\nthe owning application; these helpers never reprice them automatically.\n\nCall `calculateCostBilling({ basisMinor, mode, markup })` with that result. Money\nis signed safe-integer minor units in a single caller-selected currency. The\nbasis is explicitly chosen by the caller (for example excluding recoverable tax).\n`reimbursement-plus-fee` returns principal once plus rounded fee; `fee-only`\nreturns only the fee; `nonbillable` and `fixed-contract` return zero charge.\nThe result includes `principalMinor`, `feeMinor`, `totalMinor`, and provenance.\nPercent strings use plain nonnegative decimal notation, range 0–100000 percent,\nat most six fractional places, without whitespace, exponent or leading zeroes.\nThe finite range and scale bound input parsing and arithmetic resource use; they\nare API limits, not tax or industry policy. Arithmetic uses BigInt intermediates and half-away-from-zero rounding. Invalid\ninputs, unknown modes, inconsistent provenance and unsafe outputs throw.\n\n`calculateCostBillingTax({ lines, rules, roundingScope })` accepts line\n`id`, signed `amountMinor`, and `category`; rules explicitly map every used\ncategory to `{ id, percent }` components. An empty component array explicitly\nmeans exempt. Components are additive, never compounded. Shared component IDs\nmust use equal rates across categories; distinct rate regimes need distinct IDs.\nThe caller owns taxable basis and jurisdiction mapping. Duplicate category,\ncomponent-within-category or line IDs fail closed. `line` scope rounds each\nline/component pair; `invoice` scope aggregates exact amounts per component and\nrounds once. Two 10-unit lines at 5 percent yield tax 2 versus 1 respectively.\nReturns `taxMinor` and component totals, deliberately without allocating rounded\ninvoice tax back to lines. Signed reversals use symmetric rounding, but mixed\npositive/negative lines may differ between rounding scopes.\n"
+      "content": "# Exact cost billing\n\n`@happyvertical/smrt-commerce/cost-billing` is an independent, transport-neutral\nentry point without model, server or Svelte dependencies. It does not persist,\npost, authorize, select a currency/jurisdiction, or implement credit-note lifecycle.\nExisting Invoice calculations and editor defaults are unchanged. In particular,\n`calculateInvoiceMinorLine` retains negative ties toward positive infinity; the\nnew opt-in helpers use symmetric half-away-from-zero ties. Positive-only invoice\neditor validation remains distinct from these generic signed calculations.\n\nCall `resolveCostMarkup(overrides)` with caller-approved precedence, most specific\nfirst. Each item has `source`, optional `policy` and `version`, and optional\n`percent`. The first defined percent wins, including `\"0\"`. At least one is\nrequired; even shadowed inputs are validated. The result contains the percent,\nselected index, and detached ordered provenance. Persist accepted snapshots in\nthe owning application; these helpers never reprice them automatically.\n\nCall `calculateCostBilling({ basisMinor, mode, markup })` with that result. Money\nis signed safe-integer minor units in a single caller-selected currency. The\nbasis is explicitly chosen by the caller (for example excluding recoverable tax).\n`reimbursement-plus-fee` returns principal once plus rounded fee; `fee-only`\nreturns only the fee; `nonbillable` and `fixed-contract` return zero charge.\nThe result includes `principalMinor`, `feeMinor`, `totalMinor`, and provenance.\nPercent strings use plain nonnegative decimal notation, range 0–100000 percent,\nat most six fractional places, without whitespace, exponent or leading zeroes.\nThe finite range and scale bound input parsing and arithmetic resource use; they\nare API limits, not tax or industry policy. Arithmetic uses BigInt intermediates and half-away-from-zero rounding. Invalid\ninputs, unknown modes, inconsistent provenance and unsafe outputs throw.\n\n`calculateCostBillingTax({ lines, rules, roundingScope })` accepts line\n`id`, signed `amountMinor`, and `category`; rules explicitly map every used\ncategory to `{ id, percent }` components. An empty component array explicitly\nmeans exempt. Components are additive, never compounded. Shared component IDs\nmust use equal rates across categories; distinct rate regimes need distinct IDs.\nThe caller owns taxable basis and jurisdiction mapping. Duplicate category,\ncomponent-within-category or line IDs fail closed. `line` scope rounds each\nline/component pair; `invoice` scope aggregates exact amounts per component and\nrounds once. Two 10-unit lines at 5 percent yield tax 2 versus 1 respectively.\nReturns `taxMinor` and component totals, deliberately without allocating rounded\ninvoice tax back to lines. Signed reversals use symmetric rounding, but mixed\npositive/negative lines may differ between rounding scopes.\n\n## Ordered compound tax with explicit allocation\n\n`calculateOrderedCostBillingTax` is a separate opt-in calculator on the same\nentry point. The additive calculator above, existing model/editor rounding and\nhistorical snapshots are unchanged. This helper neither infers regional rules\nnor persists policy. Applications must explicitly select approved tenant/regional\nsettings, preserve their accepted policy and result snapshots, and decide when a\nnew calculation is appropriate.\n\nSupply `lines` (`id`, signed safe-integer `amountMinor`, `category`), `categories`\n(`category`, `componentIds`) and ordered `components` (`id`, exact `percent`,\n`priorComponentIds`). Every component must explicitly supply `priorComponentIds`:\n`[]` means net-only; otherwise each ID must name a distinct earlier component.\nThe component basis on each eligible line is its net plus that line's allocated\ntax for exactly those prior components. A prior tax not applicable to that line\ncontributes zero. Category membership order does not control execution; the\nglobal component array does. A category's empty `componentIds` means exempt.\n\nChoose `roundingScope: 'line'` to round each eligible line/component pair\nhalf-away-from-zero. Invoice allocation options are forbidden in this mode,\nincluding an explicitly present `invoiceAllocation: undefined` property.\nChoose `roundingScope: 'invoice'` with the mandatory explicit\n`invoiceAllocation: 'signed-largest-remainder'` to round each component once\nover its eligible lines and distribute that rounded amount as follows:\n\n1. Calculate each eligible line's exact rational tax from its compound basis.\n2. Truncate each exact tax toward zero, retaining its signed fractional remainder.\n3. Round the exact component aggregate half-away-from-zero. Subtract the sum of\n   truncated line taxes to obtain the signed residual.\n4. For positive residual, assign one extra minor unit to each of the lines with\n   the largest signed remainders; for negative residual, subtract one unit from\n   each line with the smallest (most negative) remainders. Stop when conserved.\n   Ties use ascending JavaScript UTF-16 code-unit line ID order, never locale\n   collation or input order. A zero residual leaves every truncated tax unchanged.\n\nThis allocation is a caller-selected arithmetic convention, not a jurisdiction\ndefault or independent per-line rounding. It supports mixed signs and exact full\nreversal: keeping the same IDs/policy and negating all amounts negates every\nreturned basis and allocation. An individual line's allocation can change when\nother lines change; independently recalculating a subset or a partial reversal\ndoes not preserve the original invoice allocation. Consumers needing historical\npartial adjustments must use their accepted snapshot and explicit adjustment\npolicy. Mixed exact taxes `+0.8` and `-0.8` have zero aggregate and allocate\n`0, 0` under this convention.\n\nFor example, lines `a` and `b`, each net 10, both receive `first` at 5 percent.\nThe invoice tax is 1, allocated `a: 1, b: 0`. If only `a` receives `second` at\n100 percent with `priorComponentIds: ['first']`, its basis is 11 and its tax 11;\nthe total tax is 12. If only `b` receives `second`, its basis and tax are 10.\nNegating both original amounts allocates `first` as `a: -1, b: 0`; the second\ntax on `a` has basis and tax -11, total tax -12. At line scope the positive\nexample instead yields first tax 2 and total tax 13.\n\nThe result is `{ taxMinor, components }`. Components follow the supplied global\norder and each returns `{ id, taxMinor, lines }`, where eligible lines are\n`{ id, basisMinor, taxMinor }` in ascending code-unit ID order. Each component's\nline allocations sum exactly to its total. Components with no eligible lines\nreturn zero and `lines: []`; well-formed unused categories and components remain\nvalid for reusable policy. Exempt lines appear in no component allocation.\nRepeated calculations and input line/category/membership permutations produce\nidentical output. All arithmetic intermediates use BigInt; every returned basis,\nallocation, component tax and final tax must fit a safe integer, even when a\nlarger value would later cancel or a component has a zero rate.\n\nAll configuration is validated, including unused entries. Missing category\nmapping, unknown IDs, duplicate line/category/component/membership/prior IDs,\nforward/self references, missing arrays, malformed rates and unknown modes fail\nclosed. Rates use the same bounded decimal-string contract as the additive API.\nThe input is never mutated and the result holds no aliases to input objects.\n"
     }
   ],
   "recipes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-commerce",
-  "version": "0.55.19",
+  "version": "0.55.21",
   "smrtJsdoc": "strict",
   "description": "Commerce models for the SMRT framework - contracts, fulfillments, payments",
   "type": "module",
@@ -61,13 +61,13 @@
   "dependencies": {
     "@happyvertical/accounting": "^0.103.5",
     "@happyvertical/payments": "^0.103.5",
-    "@happyvertical/smrt-core": "0.55.19",
-    "@happyvertical/smrt-jobs": "0.55.19",
-    "@happyvertical/smrt-ledgers": "0.55.19",
-    "@happyvertical/smrt-subscriptions": "0.55.19",
-    "@happyvertical/smrt-tenancy": "0.55.19",
-    "@happyvertical/smrt-types": "0.55.19",
-    "@happyvertical/smrt-ui": "0.55.19"
+    "@happyvertical/smrt-core": "0.55.21",
+    "@happyvertical/smrt-jobs": "0.55.21",
+    "@happyvertical/smrt-ledgers": "0.55.21",
+    "@happyvertical/smrt-subscriptions": "0.55.21",
+    "@happyvertical/smrt-tenancy": "0.55.21",
+    "@happyvertical/smrt-types": "0.55.21",
+    "@happyvertical/smrt-ui": "0.55.21"
   },
   "peerDependencies": {
     "svelte": "^5.57.0"
@@ -78,7 +78,7 @@
     }
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.55.19",
+    "@happyvertical/smrt-vitest": "0.55.21",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@testing-library/jest-dom": "^7.0.1",