Module availability_scope 

The two-scope availability read (hand-authored, user-owned; see metaphor.codegen.yaml).

The storefront-facing availability surface: ONE warehouse pivot, TWO read scopes, both computed FRESH per call off the reservation triangle (stock_quants.quantity − reserved_quantity summed over the pivot warehouse’s internal locations). Nothing about a readiness check is ever persisted — no scope columns, no warning rows, no materialized verdicts (the upstream payment-readiness gate that persisted shop_warning writes during a validation probe is the anti-shape; a validation read that mutates rows is refused by construction here — these methods only SELECT).

The two scopes, deliberately separate methods (upstream resolves them through deliberately different resolvers and reserves the checkout arm for a pickup-warehouse override):

• Display — what shop grids and product pages show: fresh availability per item at the pivot warehouse.
• Checkout — what the cart clamp and the payment gate consult: the same fresh availability MINUS the quantities the caller’s own cart already holds, floored at zero. The caller supplies its held quantities; this module never reads (or knows about) carts.

Both scopes are ADVISORY check-then-act reads: nothing is reserved, and enforcement remains where it already lives (the move engine’s reservation and picking edges). Two concurrent carts can both pass — that is the recorded upstream posture, re-expressed deliberately rather than silently “fixed” by a half-reservation here.

Fail-loud posture (the port pattern the composing service fills):

• The warehouse pivot is a REQUIRED Uuid. There is no unset-pivot overload and no all-warehouses arm on this surface — a caller without a pivot must refuse on its own side; it can never ask this read to silently sum every warehouse.
• A pivot warehouse that does not exist or is soft-deleted refuses typed (UnknownWarehouse) rather than projecting an all-sold-out storefront off a zero-row read.
• A GROUPING warehouse node refuses typed as a pivot (GroupPivot) — pointing a shop at a group node is a misconfiguration that would otherwise read as permanently sold out.
• An empty item set refuses typed (EmptyItemSet): a sold-out verdict over zero variants would be vacuously true.
• The sold-out verdict evaluates EVERY item id the caller passes. The caller resolves the variant set (the template’s variants or the single item) and passes all of them; this surface has no first-variant shortcut to get wrong — sold out means NO member of the set has availability.

Tenancy (ADR-0029): the module is tenant-agnostic. Every read rides the ambient org scope the composing service set per request; the composing decorator owns isolation, and a pivot unknown under that scope refuses typed rather than projecting a silently-empty verdict.

Structs

AvailabilityScopeRead

The real, database-backed availability scope read. Implements AvailabilityScopePort so a composition can hold the trait and swap adapters (the refusing default in tests, this service in production).

CheckoutDemand

One checkout-scope demand: the item plus the quantity the CALLER’s own cart already holds for it. The caller sums its own lines per item before passing them here; this module never reads carts.

CheckoutFreeQty

One checkout-scope answer: fresh availability at the pivot warehouse and the free quantity after the caller’s own holdings, floored at zero.

RefusingAvailabilityScopePort

The refusing default: no availability read ever succeeds. Fail-loud — an unwired composition surfaces the typed Unwired refusal on every scope, never a guessed zero (which would render the whole storefront sold out) and never a guessed abundance (which would oversell).

ScopedAvailability

One item’s fresh availability at the pivot warehouse.

SoldOutVerdict

The sold-out verdict over a WHOLE item set (a template’s full variant set, or a single item). sold_out is true only when EVERY member reads availability ≤ 0 — an absent (never-received) item counts as unavailable.

Enums

AvailabilityScopeError

The availability scope read’s typed refusals.

Traits

AvailabilityScopePort

The two-scope availability read a composing service (the storefront, a feed renderer, a pickup flow) consults. Every method is a pure read over the stock estate; nothing is reserved and nothing is persisted.