Pin the pricing arithmetic a second implementation cannot currently derive

[Ethan-Arrowood]

Read SPEC.md as someone writing the Fastify + Postgres + Redis implementation from it alone. Six things in the pricing path can't be derived, and one isn't underspecified but self-contradictory. AGENTS.md says a requirement that couldn't be satisfied on that stack is mis-specified, so these are defects rather than polish.

The contradiction

The POST /cart/:id/quote section states that all discounts draw on one budget, the line's remaining amount — then two paragraphs later states that cart-wide and per-line discounts draw on separate budgets. Both are in the normative part of that section.

The implementation has one budget: drawDown serves exclusive, threshold, BOGO and stackable alike, and the cart-level accumulator survives only in a stale header comment. Removed the stale half of each.

The six gaps

	Gap	What a second implementation does differently
1	Tier multipliers were nowhere in the spec. QUOTE-004 said tier is "applied to pricing" without saying by how much. The values lived in resources/lib/pricing.js, duplicated in packages/seed/src/vocabulary.ts with nothing checking they match	Cannot derive them. Every unit price of every line differs — the whole comparison is invalid before pricing logic runs
2	BOGO magnitude. Step 4 said which unit, never how much. The implementation discounted the full unit price and ignored the promotion's own amountBasisPoints	Applies the promotion's percentage instead. Agrees today only because every bogo row carries 10000 basis points; diverges silently the moment one doesn't
3	thresholdMinor gates every kind, not just the threshold kind. The implementation does this; the spec mentioned it only under threshold	Applies a stackable carrying a threshold regardless of subtotal
4	The cap is a running bound, not a final truncation	Truncating at the end leaves appliedPromotionIds citing promotions whose discount was scaled away — which QUOTE-012 forbids — and makes per-line figures stop summing to the cart total
5	A shortfall doesn't reduce the priced quantity	Prices only what's in stock, making the total a function of inventory the background writer is continuously changing — totals drift under load for reasons unrelated to architecture
6	Shipping band boundaries — inclusivity, overlap precedence, and a silent 0 when nothing matches	Picks different boundary semantics

On (6) I specified the data contract rather than a fallback: a new Rate table invariants subsection under Data model now states that bands are contiguous, non-overlapping, inclusive at both ends and cover every weight — which the dataset already satisfies. Exactly one band matches, so no fallback is reachable, and an implementation finding zero or several has loaded a bad dataset and should fail loudly.

One implementation change

pricing.js now reads the BOGO magnitude from the promotion instead of assuming the full unit price. Provably behaviour-identical on this corpus: every bogo row carries amountBasisPoints: 10000 and amountMinor: 0, and applying 10000 basis points to an integer returns it unchanged — floor((u × 10000 + 5000) / 10000) = floor(u + 0.5) = u. It makes the code agree with the spec permanently rather than coincidentally.

What this does not do

No requirement ids added or withdrawn. These clarify existing MUSTs rather than impose new ones, so the coverage gate is unchanged — npm run check passes, 32 ids both sides, every MUST covered.

Two of these were things I'd initially read as wrong behaviour rather than unstated behaviour. On inspection both current choices are right and the spec was simply silent: pricing the full requested quantity keeps totals independent of the background writer, and continuous cap enforcement is what keeps attribution honest. The amendments state the reasoning so the next reader doesn't re-litigate them.

Why now

This is the prerequisite for the correctness suite. Generating expected values against the spec as it stood would have meant reading them out of pricing.js — encoding this implementation's answers to all six questions as ground truth, so the table would ratify the implementation rather than check it, and the second stack would "fail correctness" for picking a different defensible reading of an unstated rule.

Left open deliberately, recorded in docs/plan.md: whether the tier multipliers should move from spec text into rate rows discriminated by kind: 'tier', which would make them dataset-pinned and delete the unchecked duplicate constant. That costs a regeneration; the ambiguity is closed either way.

🤖 Generated with Claude Code