A policy is a list of slots. Each slot names an equipment type, optionally a minimum condition score, optionally a preferred brand, and whether newer equipment is preferred:

1 laptop with condition >= 0.8, prefer Apple; 2 monitors

The service must pick one distinct available item per slot such that every hard constraint holds and the soft preferences are satisfied as well as possible across the whole set -- or, if no such set exists, fail with a reason an operator can act on.

Three things make this harder than it looks.

• Hard constraints are structural, not expensive. A pairing that violates type or minimum condition must be impossible, not merely penalised. Penalties fail the moment soft preferences accumulate past them.
• Items compete across slots. Two monitor slots share one monitor pool. Deciding one slot in isolation can consume the only item another slot could have used.
• Distinctness is implicit. "2 monitors" means two different physical monitors.

Allocation builds a bipartite flow graph:

source --(1)--> slot_i --(1, cost = -score)--> item_j --(1)--> sink

• One node per policy slot, one per available item of a requested type.
• An edge from a slot to an item exists only if the item meets the slot's hard constraints (meetsHardConstraints in AllocationMatcher.kt). Ineligible pairs are absent from the graph, which is what makes hard constraints structural.
• Every edge has capacity 1. The unit capacity on item -> sink is what enforces distinctness: an item can carry flow to at most one slot.
• The slot-to-item edge cost is the negated preference score, so minimising cost maximises preference.

A successive-shortest-augmenting-path min-cost max-flow solver then pushes one unit of flow per slot. Max-flow settles feasibility (can every slot be filled?), min-cost settles optimality (of all complete assignments, which scores highest?). One pass settles both. The shortest-path step is SPFA (queue-based Bellman-Ford): costs are negative and residual edges flip sign, so plain Dijkstra would need potentials.

Consider the case the brief calls out -- two monitor slots and three available monitors:

Policy: slot A = monitor, minimum condition 0.85. slot B = monitor, prefer LG.

Greedy fills slot B first, because that is the slot with a preference to satisfy. The only LG is M1, so B takes M1. Slot A now needs a monitor at 0.85 or better, and only M2 (0.80) and M3 (0.70) remain. The request fails, even though a valid allocation exists: M1 to slot A (0.90 clears its minimum) and M2 to slot B (no LG available, but the slot has no hard constraint). Two items allocated, zero constraints violated.

Greedy fails whichever order it uses, because the problem is structural: a greedy choice for one slot can consume the only item another slot could have used, and greedy has no way to undo that choice. Min-cost max-flow does not have this problem: augmenting paths can push flow back along residual edges, so an early assignment is revisited automatically when a later slot needs that item more. The solver either returns the globally highest-scoring complete assignment or proves none exists. AllocationScoringTest pins this exact instance and the M1-to-A, M2-to-B assignment; AllocationShortfallsTest pins that the diagnosis stays silent on it.

Soft preferences are combined into one edge score, but as strict tiers, not a blend. The documented order is brand > recency > condition > id, and the implementation guarantees it: each tier is a multiplicative unit chosen so that

unit(tier) > maximum combined contribution of every tier below it

So a brand match (10^16) beats any recency advantage (at most 10^15), one day of recency (10^10) beats any condition advantage (at most 10^9), and one hundredth of condition (10^7) beats any id advantage (at most 10^7 - 1). No accumulation of lower-priority signals can outvote a higher-priority one. AllocationMatcher.tierInvariantsHold() states the rule and AllocationScoringTest asserts it, alongside one test per tier boundary that sets the higher tier against the maximum swing of everything below it.

The units are also bounded from above. SPFA sums edge costs along a residual path that can cross every slot the API allows (50), so 50 x the maximum edge score must stay inside Long. It does, with a margin of about 16x, and a test pins that too.

Two consequences:

• Recency is sharp. An item purchased one day later beats one in far better condition, as long as both clear the slot's hard minimum. That is the literal meaning of "prefer newer equipment". If months or model year fit the business better, change the ageDays line in AllocationMatcher.score().
• The tie-break covers ids below ten million. Beyond that every item ties at zero and order falls back to candidate order, which the repository already fixes as ascending id.

When the solver cannot fill every slot, the request is stored as FAILED with a failureReason the UI shows verbatim. The reason is exact.

The hard constraints are only type and minimum condition, so within a type every slot's candidate set is a threshold set -- all items at or above the slot's minimum -- and threshold sets are nested: a tighter slot's candidates are a subset of a looser slot's. For nested sets, Hall's marriage condition collapses to one check per distinct threshold:

the number of slots demanding at least that minimum must not exceed the number of items meeting it

Types never share candidates, so the checks are independent across types. AllocationShortfalls walks each type's thresholds from tightest to loosest, accumulating demand while supply widens, and reports every threshold where demand exceeds supply. The solver stays the authority on feasibility; the diagnosis only explains. A randomised test confirms they agree on every instance: the diagnosis finds a shortfall if and only if the matcher returns no assignment.

The earlier implementation counted compatible items per type at the loosest minimum and so missed competition between slots of the same type. Two monitor slots, one needing 0.90 and one needing anything, against stock at 0.50 and 0.60: two monitors, two wanted, "no shortage" -- yet the 0.90 slot has nothing. The new diagnosis says so:

No valid equipment set is available (monitor: 1 slot needs condition >= 0.90, 0 available).

And for the competing-slots case with two slots at 0.85 against stock at 0.90, 0.80, 0.70:

No valid equipment set is available (monitor: 2 slots need condition >= 0.85, 1 available).

failure_reason is TEXT (migration V3), so even a 50-slot policy failing on every threshold is explained in full rather than truncated to fit a column.

Both the matcher and the diagnosis decide eligibility through one predicate, PolicySlotRequest.accepts(item). That is what keeps them in agreement: a new hard constraint added there reaches both, and a randomised test asserts they still agree. The service normalises each slot once (normalised() trims the brand) and hands the same values to the matcher, the diagnosis and the persisted policy, and @Digits(1, 2) on minimumCondition keeps requests at the column's NUMERIC(3,2) scale -- so the threshold the matcher enforces is the one Postgres stores and the failure reason reports.

For S slots, E eligible equipment items, V = S + E + 2 graph vertices, and A <= S x E compatibility edges, the implementation's conservative worst-case bound is O(S x V x A) time and O(V + A) space. The SPFA pass is usually far faster than that bound; see the measured numbers below. The failure diagnosis is O(S log S + S x E) and runs only on the failure path.

The price is more code than a sorted greedy pass. For very large inventories it could be improved with Johnson potentials plus Dijkstra instead of SPFA, more aggressive pre-filtering before graph construction, or an external optimisation solver. The current approach is deterministic, easy to test, and appropriate for an operations inventory where requests contain relatively few slots.

Measured with ./gradlew :backend:benchmark (AllocationMatcherBenchmark): a seeded catalogue of 5 000 equipment items, 50 warmup and 300 measured iterations per scenario, OpenJDK 21.0.9 in the gradle:9.2-jdk21 container on a 12-core machine. Candidate counts differ per scenario because only items of a requested type are eligible.

What the numbers say:

• Realistic policies finish in under 2 ms at p99. The brief's one-laptop-plus-two-monitors policy runs at 0.47 ms p50 against 2 514 candidates.
• Cost scales with slot count, not catalogue size. Each slot needs one augmenting path, so 50 slots cost roughly 50x the 1-slot case though both scan the same catalogue. Graph construction is linear in candidates.
• Failure is the fastest path. An unsatisfiable policy returns in 0.07 ms: the first augmentation finds no path and the solver exits at once.
• Matching is not the bottleneck. Even the pathological 50-slot request stays under 42 ms at p99 (the 80 ms max is a single outlier, consistent with a GC pause). AllocationService.create holds a pessimistic row lock for the whole window, so lock contention will dominate under concurrency long before the algorithm does. If 50-slot policies become common, replace SPFA with Johnson potentials plus Dijkstra.

The benchmark is a wall-clock harness, not JMH. It characterises the curve and catches regressions; microsecond precision would need JMH with blackholes and forked JVMs.

Creation runs in one transaction and pessimistically locks all available equipment rows of the requested types before matching. The chosen items become RESERVED atomically, preventing concurrent requests from receiving the same item. Confirm changes them to ASSIGNED; cancel returns them to AVAILABLE; returning a confirmed device releases that device alone. Allocation-item rows remain as history after each transition.