@vibedout/commerce 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vibedout
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,411 @@
-# Temporary Holding Version
+# @vibedout/commerce
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contracts a store is built from on Cloudflare Workers, as types and pure functions. A **line source** prices what a buyer asks for, on
+the server, and may hold places of its own (a booking slot). A **stock port** holds, sells and returns units. A **payments port** starts a
+payment and may cancel one. Tax, shipping rates and discounts are optional ports. Around them: checks for what the browser sends and for
+what a source answers, a cart priced across several sources, totals in minor units that refuse a mixed currency, a discount split over the
+lines to the centavo, the payment request an order becomes, and test helpers (a harness for your line source, an in-memory stock and
+in-memory slots, a fake payments port, and the suites a stock, a holding source and a payments provider pass).
+
+- **The server sets the price.** The browser says *which thing and how many* (a `LineAsk`); the line source says what it costs (a
+  `ResolvedLine`). `validateAsks` drops everything else the browser sends, and no option is read as a price, except an amount the buyer
+  chooses inside bounds the server sets (a donation; below).
+- **Whole numbers.** Every amount is a safe integer of minor units (centavos) with an uppercase ISO 4217 currency. No float crosses an API
+  here, and two currencies are never added. The money type and the overflow-safe sum are `@vibedout/money`'s, bundled by the build.
+- **A feature does not import another feature.** Each feature that sells, holds stock or takes money *provides* one of these ports and
+  registers it; the one that needs it looks it up by name. This package is only the types and the pure functions; where a provider is
+  registered and found is the registry in the project (`src/worker/lib/ports.ts` of the pattern pack: `linePort(key)`, `stockPort()`,
+  `paymentsPort()`, `taxPort()`, `shippingRatesPort()`, `discountPort()`).
+- **Workers-first, no runtime dependencies.** ESM only, with types. Every module is its own subpath.
+
+| Import | What |
+|---|---|
+| `@vibedout/commerce` | everything below except the test helpers |
+| `@vibedout/commerce/types` | the port interfaces and the data they carry (`LineSource`, `HoldingLineSource`, `ResolvedLine`, `CartAsk`, `CartLine`, `StockPort`, `PaymentsPort`, `CancelPaymentResult`, `TaxPort`, `ShippingRatesPort`, `DiscountPort`, `PortProviders`), `MAX_HOLD_MS` |
+| `@vibedout/commerce/lines` | `validateAsks`, `validateCartAsks`, `resolveLines`, `resolveCart`, `checkResolvedLine`, `checkResolvedLines`, `partitionLines`, `blockedReason`, `holdLinesFrom`, `holdsCapacity` |
+| `@vibedout/commerce/totals` | `computeTotals`, `assertTotals` |
+| `@vibedout/commerce/money` | `isMinorUnits`, `isCurrencyCode`, `lineTotalMinor`, `sumMinor`, `subtractMinor`, `basisPointsOf`, `taxIncludedIn`, `allocateMinor`, `MAX_RATE_BP`, `ROUNDINGS` |
+| `@vibedout/commerce/payments` | `checkStartPayment`, `paymentRequestFrom` |
+| `@vibedout/commerce/ports` | `PORT_METHODS`, `PORT_NAMES`, `checkPortProvider` |
+| `@vibedout/commerce/discounts` | `spreadDiscount`, `lineDiscountsFrom`, `checkLineDiscounts` |
+| `@vibedout/commerce/snapshot` | `SNAPSHOT_KEYS`, `snapshotText` |
+| `@vibedout/commerce/errors` | `CommerceError`, `CommerceProblem`, `PROBLEM_CODES` |
+| `@vibedout/commerce/testing` | `runLineSourceConformance`, `checkLineSource`, `runStockConformance`, `createMemoryStock`, `runLineHoldConformance`, `createMemorySlots`, `runPaymentsConformance`, `createFakePayments`, `runTaxConformance`, `createFlatTax`, `runDiscountConformance`, `createFlatDiscount`, `testContext` |
+
+## Provide a line source
+
+A feature that sells something (a catalog, a booking service, a menu, a payment link) answers one question: *what does this cost, and can it
+be bought?*
+
+```ts
+import type { LineSource, ResolvedLine } from "@vibedout/commerce";
+
+export const variantLines: LineSource = {
+  async resolve(ctx, asks) {
+    const rows = await loadVariants(ctx.db, asks.map((ask) => ask.ref)); // one query for the whole batch
+    return asks.map((ask): ResolvedLine => {
+      const row = rows.get(ask.ref);
+      if (!row) {
+        // A ref that does not exist is an answer, not an exception.
+        return { ref: ask.ref, title: ask.ref, quantity: ask.quantity, unitAmountMinor: 0, currency: "MXN", availability: "not_found", taxIncluded: true, fulfilment: "none", snapshot: {} };
+      }
+      return {
+        ref: ask.ref,
+        title: row.title,
+        quantity: ask.quantity, // echoed, never changed
+        unitAmountMinor: row.priceMinor, // the server's price; ask.options never sets it
+        currency: row.currency,
+        availability: row.published ? "available" : "not_orderable",
+        maxQuantity: 10,
+        taxCode: "01010101",
+        taxIncluded: true,
+        fulfilment: "ship",
+        stock: { subjectType: "catalog.variant", subjectId: row.id }, // inventory holds it
+        snapshot: { sku: row.sku, name: row.title }, // frozen into the order line
+      };
+    });
+  },
+};
+```
+
+The rules of a source, which `checkLineSource` and `runLineSourceConformance` test:
+
+- **One line per ask, in the order asked**, for a ref that does not exist too (`availability: "not_found"`, price 0). Two asks for one ref
+  are two lines. The `ref` and `quantity` are echoed.
+- `availability` is `available`, `sold_out` (a real item with none left: keep its title and price), `not_orderable` (not for sale) or
+  `not_found`. `maxQuantity` is the most one order may take, at least 1.
+- A price is a whole number of minor units, zero or more. It comes from your data, never from `ask.options` (the one exception is a source
+  whose buyer chooses the amount inside bounds the server sets, below), and the same ask gives the same line.
+- `snapshot` is a plain object that survives JSON unchanged, at most 2 KiB. It is copied into every order line.
+- A source reads its own tables and never edits the asks it was given.
+- A stock subject (`stock`) is `{ subjectType, subjectId }` with a dotted lowercase type (`catalog.variant`); inventory knows an item by it.
+
+**A buyer who chooses the amount** (a donation, a tip) is the one case where the price comes from the ask: the amount travels in an option as
+a string of digits, the source refuses anything that is not a whole number inside its bounds (`12.5`, `1e3`, a padded or signed number, `0x10`,
+digits of another script) and answers `maxQuantity: 1`, so a quantity cannot multiply the amount past the bound. The line is `available` at
+exactly that amount, or `not_orderable`. Say so to the harness with `buyerPrice` (below).
+
+## Read a buyer's asks, resolve them, total them
+
+```ts
+import { computeTotals, partitionLines, resolveLines, validateAsks } from "@vibedout/commerce";
+
+const asks = validateAsks(body.lines); // { ok, asks } | { ok: false, problems }: only ref, quantity and options survive
+if (!asks.ok) return c.json({ problems: asks.problems }, 422);
+
+const resolved = await resolveLines(source, ctx, asks.asks); // the answer is checked: a wrong source stops here, not in the total
+if (!resolved.ok) throw new Error(`line source: ${resolved.problems[0]?.message}`);
+
+const { chargeable, blocked } = partitionLines(resolved.lines); // blocked: sold_out, not_orderable, not_found, over_max_quantity
+const totals = computeTotals({ lines: chargeable, discounts: discount.applied, shipping: chosenRate, tax });
+if (!totals.ok) return c.json({ problems: totals.problems }, 422);
+totals.totals.totalMinor; // subtotal - discounts + shipping + added tax
+```
+
+- `validateAsks` allows 1 to 50 lines, quantities 1 to 99 and refs of 1 to 120 printable characters (no control, zero-width or
+  direction-changing characters, nothing padded), and refuses the same ref with the same options twice. Pass limits as the second argument
+  (a ref is at most 1024 characters whatever the limit says).
+- `resolveLines` hands the source frozen copies of the asks (a source that sorts them in place throws instead of corrupting your order) and
+  does not catch a source that throws: that is a fault, not a problem with the answer.
+- `computeTotals` refuses (it returns `problems`, it does not throw) an empty order, a line that cannot be bought, two currencies, **a
+  shipping rate, a tax or a discount in a currency other than the lines'** (each states its own: `shipping: rate` passes a `ShippingRate` as it
+  is), an amount that is not whole minor units or too large for a number, discounts larger than the subtotal, and a tax breakdown that does not add
+  up to its headline. `tax.includedMinor` is the tax already inside the prices (for the invoice); it is not added again. `assertTotals` throws a
+  `CommerceError` carrying the same problems. Each priced line keeps its `fulfilment`, `stock` subject and `snapshot` for the order.
+- Every problem is `{ code, path, message }`: `code` is for your route to map, `message` is English for a log.
+
+## A cart of several sources
+
+A cart holds things several features sell (a tag from the catalog, a session from booking). Each line names its source; `resolveCart` asks
+each source once, for its own lines, and gives the lines back in the cart's order, each with its `source`:
+
+```ts
+import { computeTotals, type LineSource, partitionLines, resolveCart, validateCartAsks } from "@vibedout/commerce";
+
+const findSource = (key: string) => {
+  const found = linePort<LineSource>(key); // the project's registry
+  return found.ok ? found.port : undefined;
+};
+const read = validateCartAsks(cartLines, { find: findSource }); // only source, ref, quantity and options survive; a source nobody registered is refused
+if (!read.ok) return c.json({ problems: read.problems }, 422);
+const cart = await resolveCart(findSource, ctx, read.asks);
+if (!cart.ok) throw new Error(`line source: ${cart.problems[0]?.message}`); // a source answered wrong: the path is the cart's line
+const { chargeable, blocked } = partitionLines(cart.lines); // a line whose source is gone is blocked as not_found
+const totals = computeTotals({ lines: chargeable });
+```
+
+- Each source gets only its asks (without the `source` key), as frozen copies, and its answer is checked as `resolveLines` checks it. The
+  sources are asked at the same time; one that throws is not caught.
+- A line whose source is not there (a feature that was removed, a key nobody registered) comes back `not_found` at a price of 0 in no
+  currency (`XXX`), as a ref no source has: the cart shows it as no longer sold and totals the rest.
+- A source that answers wrong makes the whole answer `{ ok: false, problems }`, listed source by source: a problem with one line points at the
+  cart's line (`lines[3].unitAmountMinor`), one with a source's whole answer at `lines`, and each message starts with the source's key.
+- It does not check the asks: check them where they come in, with `validateCartAsks` (below). A line not sold here shows its ref as its title.
+- `validateCartAsks(input, { find?, ...limits })` reads a cart's lines before any price is asked and any place is held. It gives back exactly
+  `source`, `ref`, `quantity` and `options`, in the order sent, and refuses a `source` that is not a key (`invalid_source`: dotted lowercase words,
+  at most 80 characters), with `find` a key nobody registered (`unknown_source`), the same source, ref and options twice (`duplicate_ref`: the same
+  ref under two sources, or with other options, is two lines) and whatever `validateAsks` refuses for a ref, a quantity or the options, at the
+  same paths (`asks[2].quantity`), with the same limits.
+
+## The stock port
+
+Provided by the `inventory` feature, at most one per project.
+
+```ts
+import { holdLinesFrom, type StockPort } from "@vibedout/commerce";
+
+const stock: StockPort = { availability, hold, commit, release };
+
+const held = await stock.hold(ctx, {
+  holdId: order.id, // the same id again is the same hold
+  lines: holdLinesFrom(totals.totals.lines), // the lines that name a stock subject: hold with this, not with the `ref`
+  expiresAt: ctx.now + 30 * 60_000, // the units come back by themselves at this time
+});
+if (!held.ok) {
+  held.code; // "insufficient_stock" (with `short`: what was asked and what there is), "hold_conflict", "hold_closed" or "invalid_request"
+}
+await stock.commit(ctx, order.id); // the payment succeeded; a late payment still commits and says `late: true` (and `oversold: true` below zero)
+await stock.release(ctx, order.id); // the payment failed or was cancelled; releasing a committed hold is `invalid_state`
+await stock.fulfil?.(ctx, order.id); // optional (0.1.1): the sold units left the shelf; `on hand` and `committed` both go down, once
+await stock.uncommit?.(ctx, order.id); // optional (0.2.1): the sale was undone before they left (a full refund); the units can be bought again
+```
+
+A hold is every line or none, and the last unit goes to exactly one of two buyers. The same `holdId` with the same lines is the same hold: it
+holds nothing twice, and a later `expiresAt` extends it (the date of an OXXO voucher is known only after the payment starts) but never
+shortens it. A `holdId` whose hold is over (released, expired or committed) answers `hold_closed` with its `status`: a new attempt takes a new
+id. A hold lasts at most 14 days (`MAX_HOLD_MS`), so a time in the wrong unit is refused and not kept for years. A subject inventory does not
+know is untracked, always available: that is why a hold is made from the lines' `stock`, never from a `ref`. The clock is `ctx.now`, never the
+database's. **`runStockConformance` is the suite a provider must pass**: run it against your implementation and the in-memory one passes the
+same tests.
+
+`fulfil` is optional (0.1.1), so a provider written for 0.1.0 is still one; `OPTIONAL_PORT_METHODS` lists it, and `checkPortProvider` checks
+that it is a function when it is there. It is for a committed hold whose units have left (shipped, handed over, delivered): the units stop
+counting both as sold and as on hand, so what can be bought does not move. It moves a hold once (a second call answers `changed: false`), the
+hold stays `committed` and carries `fulfilledAt`, and a hold that is not committed is `invalid_state` with its status. A caller checks that
+the method is there (`stock.fulfil?.(...)`); a provider that tracks no units on hand leaves it out and runs the suite with
+`{ skipFulfil: true }`.
+
+`uncommit` is optional (0.2.1) and is the other way out of `committed`: the sale was undone before the units left the shelf (an order was
+refunded in full and never fulfilled). A committed hold gives its units back to what can be bought, `on hand` does not move, and the hold ends
+as `released`. Once per hold: a second call, and a hold that is already released or expired, answer `changed: false`. A hold that is still `held`
+(never paid; that is `release`) or was fulfilled (its units left) is `invalid_state` with its status and nothing moves. The hold's id stays
+closed to a new hold, and a payment that still arrived for it would commit it again as a late one, so a caller uncommits an order that
+cannot be paid any more. A provider that does not count units leaves it out and runs the suite with `{ skipUncommit: true }`.
+
+## A source with places of its own
+
+A thing whose capacity inventory does not count (a booking slot and its seats, a class and its places) is held by its own line source:
+`hold`, `commit` and `release` on `LineSource`, optional and always the three together. They follow the stock port's rules, by the ask
+instead of a stock subject: every ask or none, the same `holdId` is the same hold (a later `expiresAt` extends it, never shortens it), the
+last place goes to one buyer, the clock is `ctx.now`, the places come back by themselves at `expiresAt`, a payment after that still commits
+and says `late` (and `oversold` when the place went to someone else), and a committed hold cannot be released. While a hold lasts, `resolve`
+counts its places as taken. A ref the source does not have is never held (`insufficient_stock`, 0 available).
+
+```ts
+import { holdsCapacity, type LineSource } from "@vibedout/commerce";
+
+if (holdsCapacity(source)) {
+  const held = await source.hold(ctx, { holdId: order.id, lines: asks, expiresAt: ctx.now + 30 * 60_000 }); // beside the stock port's hold
+  if (!held.ok) held.code; // "insufficient_stock" (with `short`: the ref, what was asked and what is left), "hold_conflict", "hold_closed" or "invalid_request"
+}
+// on the payment's success: source.commit(ctx, order.id); on its failure for good, a cancel or an expiry: source.release(ctx, order.id)
+```
+
+A checkout holds such a source's asks with the order's id, beside the stock port's hold of the lines that name a stock subject, and commits or
+releases both. `runLineHoldConformance` is the suite such a source passes, and `createMemorySlots` the in-memory one that passes it.
+
+## The payments port
+
+Provided by the `payments` feature, at most one per project.
+
+```ts
+import { computeTotals, paymentRequestFrom } from "@vibedout/commerce";
+
+const request = paymentRequestFrom(totals.totals, {
+  reference: order.id, // set by the server; the provider's idempotency key derives from it
+  successUrl: `${origin}/orders/${order.id}`,
+  cancelUrl: `${origin}/cart`,
+  payer: { email },
+  expiresAt: ctx.now + 30 * 60_000,
+});
+const started = await paymentsPort.start(ctx, request);
+if (started.ok) redirect(started.redirectUrl);
+else started.code; // "invalid_request", "not_configured" or "provider_error" (with `retryable`)
+```
+
+`paymentRequestFrom` turns totals into lines plus `shipping`, `tax` and `discount` adjustments that add up to the total to the centavo. A
+payments port runs `checkStartPayment(input)` first and answers `invalid_request` when it returns problems; a total of zero is
+`free_order`: the order is paid with no provider. The discounts come off the items only: together they may not be more than the lines, even
+when the shipping and the tax would pay for them (a provider shows a discount on the item lines, and no line goes below zero).
+
+`cancel` is optional (0.2.0): the order behind a reference will not be paid (staff cancelled it, or its time ran out), so the provider's page
+stops taking money and a voucher stops being payable.
+
+```ts
+const cancelled = await paymentsPort.cancel?.(ctx, order.id);
+if (cancelled && !cancelled.ok) cancelled.code; // "unknown_payment", "already_paid" (refund it instead), "not_cancellable", "not_configured", "provider_error"
+```
+
+It stops a payment once (a second call answers `changed: false`), and starting the reference again is refused. A payment already on its way
+(a payer who pressed "pay" at the same moment, a voucher being paid at the counter) can still arrive as `payment.succeeded`: handle it as
+the late payment it is. Without `cancel` the page stays payable until its `expiresAt`. `runPaymentsConformance` is the suite a payments
+provider passes (`{ skipCancel: true }` for one without `cancel`).
+
+## Tax, shipping rates and discounts
+
+Optional ports (`TaxPort.compute`, `ShippingRatesPort.quote`, `DiscountPort.apply`), at most one each. Without them an order adds no tax,
+no shipping and no discount: a line with `taxIncluded: false` and no tax provider is charged no tax, so a shop installs a tax feature or
+prices with tax included. A shipping rate is chosen by `id`: the server quotes again before it charges, so the amount is never the browser's.
+Every amount a provider returns states its currency (`TaxResult.currency`, `AppliedDiscount.currency`, `ShippingRate.currency`), and
+`computeTotals` refuses one that is not the order's. Rates in a tax breakdown are basis points (16% is `1600`). A discount that covers several
+lines is worked out either on the subtotal or line by line, and the two differ by a centavo (three lines of 1.05 at 10% are 0.33 one by one and 0.32 together):
+the provider chooses, and one that works line by line, rounding each line half-up (`pricing` does), says which lines it came off in `AppliedDiscount.lines`
+(below), so a caller that spreads an order's discount itself (`allocateMinor`) uses those amounts when they are there.
+
+**What a discount did to each line (0.2.2).** A tax is worked on what each line costs after its discount, and an invoice states a discount per
+line, but the discount port answers amounts for the order. A discount may say which lines it came off (`AppliedDiscount.lines`, the position in
+`DiscountInput.lines` and the amount, adding up to the discount's amount); `lineDiscountsFrom(lines, applied)` adds them up per line, or answers
+`undefined` when a discount does not say (or says something `checkLineDiscounts` refuses), and then `spreadDiscount(lines, discountMinor)` spreads the
+total in proportion to the line totals. The result goes to the tax port as `TaxInput.lineDiscountsMinor`; a tax provider that does not read it spreads
+`discountMinor` itself. This matters when the lines are taxed at different rates and a discount applies to one of them.
+
+```ts
+import { lineDiscountsFrom, spreadDiscount } from "@vibedout/commerce";
+
+const perLine = lineDiscountsFrom(lines, applied) ?? spreadDiscount(lines, discountMinor); // [400, 50]
+await tax.compute(ctx, { currency, lines, discountMinor, lineDiscountsMinor: perLine, shippingMinor, destination });
+```
+
+**What a source writes for the features that price and tax its lines (0.2.2).** The snapshot is free-form, but three keys are read by other
+features: `sku` (a discount rule names a SKU), `productId` (a rule covers every variant of a product) and `taxClass` (`standard`, `zero`, `exempt`:
+a tax provider maps it to a rate; not the SAT product key, which is `ResolvedLine.taxCode`). A source that sells goods writes them; a reader uses
+`snapshotText(line, "sku")`, which answers nothing for a missing or malformed value, and falls back to its default.
+
+A title is checked by `isDisplayText(value, max)` (0.2.2): one to `max` characters, no space at either end, no control character, line break or invisible override.
+`checkResolvedLine` and `computeTotals` refuse a line or a discount whose title fails it, so a feature that lets a person type such a title validates with it
+when it is typed, and the cart never refuses what an admin accepted.
+
+A provider that applies a rate does it in whole numbers, with the helpers and not `amount * 0.16`:
+
+```ts
+import { basisPointsOf, subtractMinor, taxIncludedIn } from "@vibedout/commerce";
+
+basisPointsOf(10_000, 1600);   // 1600: 16% of 100.00
+basisPointsOf(10_050, 100);    // 101: 1% of 100.50 is 1.005, half up (`(1.005).toFixed(2)` says "1.00")
+taxIncludedIn(11_600, 1600);   // 1600: the IVA already inside a shelf price of 116.00
+subtractMinor(11_600, 1600);   // 10_000: the net price
+basisPointsOf(5, 5000, "down"); // 2: `half-up` is the default; `down` and `up` are for a rule that says so
+```
+
+The product is computed with BigInt, so the largest amount a number holds is exact; a rate is a whole number of basis points from 0 to 100000
+(`MAX_RATE_BP`: a discount is at most 10000, a tax can be more, as IEPS on tobacco at 160%), and a result a number cannot hold is refused.
+
+An invoice that states each line's discount (a CFDI does) splits the order's discount over the lines with `allocateMinor`, the line totals
+as the weights:
+
+```ts
+import { allocateMinor } from "@vibedout/commerce";
+
+allocateMinor(1000, [3000, 1000]); // [750, 250]: 10.00 off a 30.00 and a 10.00 line
+allocateMinor(100, [1, 1, 1]);     // [34, 33, 33]: the centavo left goes to the largest fraction, the earlier line on a tie
+```
+
+The shares add up to the total exactly; no share is more than its line when the discount is not more than the lines, and a line of 0 gets 0.
+`@vibedout/payments` spreads a discount over a provider's page by the same rule, so the invoice and the page agree line by line.
+
+## Providers in a project
+
+`PortProviders` maps each port name to its interface, so a feature types its export with it:
+
+```ts
+import type { PortProviders } from "@vibedout/commerce";
+
+export const inventoryStock: PortProviders["stock"] = { availability, hold, commit, release };
+```
+
+`checkPortProvider("stock", inventoryStock)` lists the methods an export lacks (for a provider assembled by a factory, or written in plain
+JavaScript), an optional one that is not a function, and the rest of a set it has only part of (`hold` without `commit` and `release`);
+`PORT_METHODS` and `OPTIONAL_PORT_METHODS` are those lists as data. In a project that lists this package, the generated `registerPorts` call
+checks each provider against its port with `satisfies PortProviders["stock"]`, so a mistyped provider fails `pnpm typecheck`.
+
+## Testing
+
+```ts
+import { describe, expect, it } from "vitest";
+import { runLineSourceConformance } from "@vibedout/commerce/testing";
+import { variantLines } from "./line-source";
+
+runLineSourceConformance(
+  variantLines,
+  {
+    ctx, // a PortContext with the project's env.DB when the source reads D1; the default has a database that throws
+    known: [{ ref: "var_1", unitAmountMinor: 4900, currency: "MXN" }],
+    unavailable: [{ ref: "var_9", availability: "not_orderable" }],
+  },
+  { describe, it, expect },
+);
+```
+
+A source whose buyer chooses the amount inside bounds the server sets (a donation, a tip) says so with `buyerPrice: { ref, option, min, max }`.
+The harness then checks that the bounds hold and that only a whole number of minor units inside them is priced (`12.5`, `1e3`, a padded or
+signed number and one outside the bounds are refused), that the line is one unit (`maxQuantity: 1`), and still refuses a price in every other
+option name it tries. It tries `price`, `amount`, `unitAmountMinor`, `unit_price`, `total`, `currency` and `discount`; a source that reads
+another option name for something else (`pledge`) lists it in `extraPriceOptions`, so the harness tries it as a price too.
+
+One test for each thing a checkout relies on: no asks, no lines; a valid, available line at the right price; lines in the order asked
+whatever else is in the batch; a ref that does not exist and hostile refs (`__proto__`, `constructor`, `' OR 1=1 --`) answered `not_found`
+with no exception; sold out items reported as such; a price sent in `options` ignored; read-only asks accepted; the same ask giving the same
+line; two asks for one ref staying two lines. `checkLineSource(source, fixtures)` returns the findings without a test runner.
+
+| Helper | What |
+|---|---|
+| `runStockConformance(make, tools, options?)` | the suite a stock provider passes; `make(seed)` returns a provider holding that seed (`{ "type:id": { tracking: "count", onHand: 3 } }`); `{ skipFulfil: true }` and `{ skipUncommit: true }` leave out the cases of the optional `fulfil` and `uncommit` |
+| `createMemoryStock(seed)` | a stock in memory with the same semantics, `fulfil` and `uncommit` included, for testing a checkout; `counts()` shows what it holds |
+| `runLineHoldConformance(make, tools, options?)` | the suite a line source that holds its own places passes; `make(places)` returns one with those places (`{ slot_a: 3 }`) |
+| `createMemorySlots(places, { unitAmountMinor? })` | a line source with places of its own, in memory (its holds are the in-memory stock's), for testing a checkout |
+| `runPaymentsConformance(make, tools, options?)` | the suite a payments provider passes: it checks what it charges (the total, a discount over the items, a free order), one payment per reference, and `cancel`; `{ skipCancel: true }` leaves the cancel cases out, `referencePrefix` keeps references apart in a shared database |
+| `createFakePayments()` | a payments port that runs `checkStartPayment`, is idempotent by `reference`, records what it started and cancels once; `failNext(...)` makes the next call fail, `markPaid(reference)` stands in for the provider's event |
+| `runTaxConformance(make, tools, options?)` | the suite a tax provider passes, whatever the country: the answer is in the order's currency and whole minor units, a breakdown adds up so the totals take it, a price that includes the tax adds nothing on top, a discount never raises the tax, a free line carries none, the same input gives the same answer and is left as it was; the rates are the provider's own golden files |
+| `createFlatTax({ rateBp?, code? })` | one rate for everything, worked per line on what is paid (the discount of each line when `lineDiscountsMinor` is given), shipping taxed on top |
+| `runDiscountConformance(make, tools, { scenarios, plain? })` | the suite a discount provider passes: you give it the orders its rules apply to; amounts are whole, titled, in the order's currency and at most the subtotal, the lines a discount names are real and add up, every typed code is answered once with a reason from the list, the same input gives the same answer |
+| `createFlatDiscount({ percentBp?, fromQuantity?, title? })` | a percent off every line of at least a quantity, with the lines named; it knows no code |
+| `testContext(overrides)` | a `PortContext` with a fixed clock (`TEST_NOW`) and a `db` whose every method throws |
+
+## Problem codes
+
+`PROBLEM_CODES` lists them. By where they come from:
+
+| From | Codes |
+|---|---|
+| the buyer's asks | `invalid_asks`, `invalid_ref`, `invalid_quantity`, `invalid_options`, `duplicate_ref` |
+| a source's answer | `invalid_lines`, `line_count_mismatch`, `line_ref_mismatch`, `line_quantity_mismatch`, `invalid_line`, `invalid_title`, `invalid_price`, `invalid_currency`, `invalid_availability`, `invalid_max_quantity`, `invalid_fulfilment`, `invalid_stock_subject`, `invalid_snapshot` |
+| a line that cannot be bought now | `sold_out`, `not_orderable`, `not_found`, `over_max_quantity` |
+| totals | `empty_order`, `currency_mismatch`, `out_of_range`, `invalid_adjustment`, `discount_exceeds_subtotal`, `tax_breakdown_mismatch` |
+| a payment request | `invalid_payment`, `payment_not_reconciled`, `free_order` |
+| a port provider | `invalid_port` |
+
+## Changelog
+
+- 0.2.3: `validateCartAsks`, the check a cart's `complete` runs on its lines before any price is asked and any place is held (`{ source, ref,
+  quantity, options? }` per line: the source is a key, with `find` a registered one, the same source, ref and options twice are refused, the rest
+  as `validateAsks`), with the problem codes `invalid_source` and `unknown_source`. Additive: `validateAsks` and everything else are as they were.
+- 0.2.2: what a discount did to each line (`AppliedDiscount.lines`, `TaxInput.lineDiscountsMinor`, `lineDiscountsFrom`, `spreadDiscount`,
+  `checkLineDiscounts`), the snapshot keys other features read (`SNAPSHOT_KEYS`, `snapshotText`), and the suites for the two optional ports that had
+  none (`runTaxConformance`, `runDiscountConformance`, with `createFlatTax` and `createFlatDiscount`), and `isDisplayText`, the check a title passes. Additive: a provider and a caller written for 0.2.1
+  work unchanged, and a tax provider that ignores `lineDiscountsMinor` is still one.
+- 0.2.1: the stock port's optional `uncommit` (the sale was undone before the units left the shelf: a committed, unfulfilled hold gives its units back
+  and ends as `released`, once), with eight conformance cases (`skipUncommit` leaves them out), `OPTIONAL_PORT_METHODS` and the in-memory stock's own
+  `uncommit`. Additive: a provider and a caller written for 0.2.0 work unchanged, but a feature whose stock provider has `uncommit` needs this
+  version's types to compile.
+- 0.2.0: a line source may hold its own places (`hold`, `commit`, `release`, optional and together; `HoldingLineSource`, `holdsCapacity`,
+  `runLineHoldConformance`, `createMemorySlots`, the harness's `holds` check); `resolveCart` prices a cart across sources; the payments port's
+  optional `cancel` (`CancelPaymentResult`, the fake's `cancel` and `markPaid`) and `runPaymentsConformance`; `allocateMinor` splits an amount
+  over lines; `checkStartPayment` refuses discounts larger than the items even when the shipping and the tax would cover them (before, only
+  larger than the whole charge; the message starts with the words the payments feature's own check uses); `Hold`, `HoldResult`,
+  `SettleResult`, `BlockedLine` and `partitionLines` take the line type as a parameter (the default is what it was). Additive for a provider or
+  a caller written for 0.1.x, with two exceptions: a payment request whose discounts pass its items is now refused, and a line source that has
+  some of `hold`, `commit` and `release` but not all three is now reported by `checkPortProvider` and the harness.
+- 0.1.1: the stock port's optional `fulfil` (a committed hold's units leave the shelf: on hand and committed both go down, once), with
+  `Hold.fulfilledAt`, `OPTIONAL_PORT_METHODS`, five conformance cases (`skipFulfil` leaves them out) and the in-memory stock's own `fulfil`.
+  Additive: a provider and a caller written for 0.1.0 work unchanged.
+- 0.1.0: first release.

package/dist/discounts.d.mts

@@ -0,0 +1,33 @@
+import { n as CommerceProblem } from "./errors-DGzIIflf.mjs";
+import { U as ResolvedLine, r as AppliedDiscount } from "./types-BzlVbRp1.mjs";
+//#region src/discounts.d.ts
+/** What a discount needs of a line: its price and quantity. A `ResolvedLine`, a `PricedLine` and a cart line all fit. */
+type DiscountableLine = Pick<ResolvedLine, "unitAmountMinor" | "quantity">;
+/**
+ * `discountMinor` spread over the lines in proportion to their totals, in whole minor units that add up to it exactly (`allocateMinor`): what a
+ * tax provider does when the discounts do not say which lines they came off. No line gives more than its total. Throws {@link CommerceError}
+ * (`discount_exceeds_subtotal`) when the discount is more than the lines cost together.
+ *
+ * ```ts
+ * spreadDiscount([{ unitAmountMinor: 3000, quantity: 1 }, { unitAmountMinor: 1000, quantity: 1 }], 1000); // [750, 250]
+ * ```
+ */
+declare function spreadDiscount(lines: readonly DiscountableLine[], discountMinor: number): number[];
+/**
+ * The problems with the attributions of `discounts` over `lines`: every discount that takes something off says which lines it came off, each
+ * `index` is a line, the amounts are whole and add up to the discount's `amountMinor`, and no line is discounted by more than it costs. A
+ * discount of 0 needs nothing. An empty list means {@link lineDiscountsFrom} can answer.
+ */
+declare function checkLineDiscounts(lines: readonly DiscountableLine[], discounts: readonly AppliedDiscount[], path?: string): CommerceProblem[];
+/**
+ * What the discounts took off each line, in the order of `lines`, or `undefined` when they do not say (a discount of the whole order, or
+ * attributions that {@link checkLineDiscounts} refuses): then spread the total with {@link spreadDiscount}. Pass the result as
+ * `TaxInput.lineDiscountsMinor`.
+ *
+ * ```ts
+ * const perLine = lineDiscountsFrom(lines, applied) ?? spreadDiscount(lines, discountMinor);
+ * ```
+ */
+declare function lineDiscountsFrom(lines: readonly DiscountableLine[], discounts: readonly AppliedDiscount[]): number[] | undefined;
+//#endregion
+export { DiscountableLine, checkLineDiscounts, lineDiscountsFrom, spreadDiscount };

package/dist/discounts.mjs

@@ -0,0 +1,97 @@
+import { CommerceError, problem } from "./errors.mjs";
+import { i as isRecord } from "./internal-p2FS_A4L.mjs";
+import { o as isMinorUnits, r as allocateMinor, s as lineTotalMinor } from "./money-aFFtGd0E.mjs";
+//#region src/discounts.ts
+/**
+* What a discount did to each line (0.2.2). A discount port answers amounts for the order; a tax is worked on what each line costs after its
+* discount, and an invoice (a CFDI) states a discount per line. These are the two ways to know that amount: the discount says which lines it
+* came off ({@link AppliedDiscount.lines}), or it is spread over the lines in proportion to their totals.
+*/
+/**
+* `discountMinor` spread over the lines in proportion to their totals, in whole minor units that add up to it exactly (`allocateMinor`): what a
+* tax provider does when the discounts do not say which lines they came off. No line gives more than its total. Throws {@link CommerceError}
+* (`discount_exceeds_subtotal`) when the discount is more than the lines cost together.
+*
+* ```ts
+* spreadDiscount([{ unitAmountMinor: 3000, quantity: 1 }, { unitAmountMinor: 1000, quantity: 1 }], 1000); // [750, 250]
+* ```
+*/
+function spreadDiscount(lines, discountMinor) {
+	const totals = lines.map((line) => lineTotalMinor(line.unitAmountMinor, line.quantity));
+	if (!isMinorUnits(discountMinor)) throw new CommerceError("out_of_range", "a discount is a whole number of minor units, zero or more", "discountMinor");
+	if (discountMinor === 0) return totals.map(() => 0);
+	if (totals.length === 0) throw new CommerceError("discount_exceeds_subtotal", "there are no lines to take a discount from", "lines");
+	const sum = totals.reduce((total, amount) => total + amount, 0);
+	if (discountMinor > sum) throw new CommerceError("discount_exceeds_subtotal", `a discount of ${discountMinor} is more than the lines cost (${sum})`, "discountMinor");
+	return allocateMinor(discountMinor, totals);
+}
+/**
+* The problems with the attributions of `discounts` over `lines`: every discount that takes something off says which lines it came off, each
+* `index` is a line, the amounts are whole and add up to the discount's `amountMinor`, and no line is discounted by more than it costs. A
+* discount of 0 needs nothing. An empty list means {@link lineDiscountsFrom} can answer.
+*/
+function checkLineDiscounts(lines, discounts, path = "discounts") {
+	const out = [];
+	const taken = lines.map(() => 0);
+	for (const [at, discount] of discounts.entries()) {
+		const where = `${path}[${at}]`;
+		if (!isRecord(discount) || !isMinorUnits(discount.amountMinor)) {
+			out.push(problem("invalid_adjustment", where, "a discount has a whole amount of minor units, zero or more"));
+			continue;
+		}
+		if (discount.amountMinor === 0) continue;
+		if (!Array.isArray(discount.lines)) {
+			out.push(problem("invalid_adjustment", `${where}.lines`, "a discount that takes something off says which lines it came off"));
+			continue;
+		}
+		let sum = 0;
+		const seen = /* @__PURE__ */ new Set();
+		const parts = discount.lines;
+		for (const [position, part] of parts.entries()) {
+			const partPath = `${where}.lines[${position}]`;
+			const index = isRecord(part) ? part.index : void 0;
+			const amountMinor = isRecord(part) ? part.amountMinor : void 0;
+			if (typeof index !== "number" || !Number.isSafeInteger(index) || index < 0 || index >= lines.length) {
+				out.push(problem("invalid_adjustment", partPath, "index is the position of a line"));
+				continue;
+			}
+			if (!isMinorUnits(amountMinor)) {
+				out.push(problem("invalid_adjustment", partPath, "amountMinor is a whole number of minor units, zero or more"));
+				continue;
+			}
+			if (seen.has(index)) {
+				out.push(problem("invalid_adjustment", partPath, "a line appears once in a discount"));
+				continue;
+			}
+			seen.add(index);
+			sum += amountMinor;
+			taken[index] = taken[index] + amountMinor;
+		}
+		if (sum !== discount.amountMinor) out.push(problem("invalid_adjustment", `${where}.lines`, `the lines add up to ${sum}, the discount is ${discount.amountMinor}`));
+	}
+	for (const [index, line] of lines.entries()) if (isMinorUnits(line.unitAmountMinor) && Number.isSafeInteger(line.quantity) && line.quantity >= 1) {
+		const total = lineTotalMinor(line.unitAmountMinor, line.quantity);
+		if (taken[index] > total) out.push(problem("discount_exceeds_subtotal", `${path}.lines[${index}]`, `line ${index} is discounted by ${taken[index]}, it costs ${total}`));
+	}
+	return out;
+}
+/**
+* What the discounts took off each line, in the order of `lines`, or `undefined` when they do not say (a discount of the whole order, or
+* attributions that {@link checkLineDiscounts} refuses): then spread the total with {@link spreadDiscount}. Pass the result as
+* `TaxInput.lineDiscountsMinor`.
+*
+* ```ts
+* const perLine = lineDiscountsFrom(lines, applied) ?? spreadDiscount(lines, discountMinor);
+* ```
+*/
+function lineDiscountsFrom(lines, discounts) {
+	if (checkLineDiscounts(lines, discounts).length > 0) return void 0;
+	const taken = lines.map(() => 0);
+	for (const discount of discounts) {
+		if (discount.amountMinor === 0) continue;
+		for (const part of discount.lines ?? []) taken[part.index] = taken[part.index] + part.amountMinor;
+	}
+	return taken;
+}
+//#endregion
+export { checkLineDiscounts, lineDiscountsFrom, spreadDiscount };

package/dist/errors-DGzIIflf.d.mts

@@ -0,0 +1,24 @@
+//#region src/errors.d.ts
+/**
+ * What can be wrong, as data. A check of untrusted input (a buyer's asks, the lines a source returns, a payment request) returns a list of
+ * {@link CommerceProblem} and never throws; a route maps `code` to its own error. Only the low-level helpers of `./money` throw, with a
+ * {@link CommerceError} that carries the same codes.
+ */
+declare const PROBLEM_CODES: readonly ["invalid_asks", "invalid_ref", "invalid_quantity", "invalid_options", "duplicate_ref", "invalid_source", "unknown_source", "invalid_lines", "line_count_mismatch", "line_ref_mismatch", "line_quantity_mismatch", "invalid_line", "invalid_title", "invalid_price", "invalid_currency", "invalid_availability", "invalid_max_quantity", "invalid_fulfilment", "invalid_stock_subject", "invalid_snapshot", "sold_out", "not_orderable", "not_found", "over_max_quantity", "empty_order", "currency_mismatch", "out_of_range", "invalid_adjustment", "discount_exceeds_subtotal", "tax_breakdown_mismatch", "invalid_payment", "payment_not_reconciled", "free_order", "invalid_port"];
+type ProblemCode = (typeof PROBLEM_CODES)[number];
+interface CommerceProblem {
+  code: ProblemCode;
+  /** Where, in the shape of the input: `asks[1].quantity`, `lines[0].unitAmountMinor`, `total`. */
+  path: string;
+  /** For a log or a developer, in English. A person-facing text is the caller's, chosen by `code`. */
+  message: string;
+}
+/** Thrown by the low-level money helpers and by `assertTotals`. `code` is the first problem's; `problems` has at least one entry. */
+declare class CommerceError extends Error {
+  readonly code: ProblemCode;
+  readonly problems: readonly CommerceProblem[];
+  constructor(code: ProblemCode, message: string, path?: string, problems?: readonly CommerceProblem[]);
+}
+declare const problem: (code: ProblemCode, path: string, message: string) => CommerceProblem;
+//#endregion
+export { problem as a, ProblemCode as i, CommerceProblem as n, PROBLEM_CODES as r, CommerceError as t };

package/dist/errors.d.mts

@@ -0,0 +1,2 @@
+import { a as problem, i as ProblemCode, n as CommerceProblem, r as PROBLEM_CODES, t as CommerceError } from "./errors-DGzIIflf.mjs";
+export { CommerceError, CommerceProblem, PROBLEM_CODES, ProblemCode, problem };