service = new PipelineAllocationService; $this->scenario = Scenario::factory()->create(); } // ────────────────────────────────────────────────────── // Guard clauses // ────────────────────────────────────────────────────── public function test_returns_empty_collection_when_no_buckets(): void { $draws = $this->service->allocateInflow($this->scenario, 100000); $this->assertEmpty($draws); } public function test_returns_empty_collection_when_amount_is_zero(): void { $this->createNeedBucket(50000, priority: 1); $draws = $this->service->allocateInflow($this->scenario, 0); $this->assertEmpty($draws); } public function test_returns_empty_collection_when_amount_is_negative(): void { $this->createNeedBucket(50000, priority: 1); $draws = $this->service->allocateInflow($this->scenario, -10000); $this->assertEmpty($draws); } // ────────────────────────────────────────────────────── // Even mode — base phase // ────────────────────────────────────────────────────── public function test_even_mode_splits_evenly_across_need_buckets(): void { // 3 need buckets, $500 base each, $900 income → $300 each $b1 = $this->createNeedBucket(50000, priority: 1); $b2 = $this->createNeedBucket(50000, priority: 2); $b3 = $this->createNeedBucket(50000, priority: 3); $draws = $this->service->allocateInflow($this->scenario, 90000); $this->assertCount(3, $draws); $this->assertDrawAmount($draws, $b1->id, 30000); $this->assertDrawAmount($draws, $b2->id, 30000); $this->assertDrawAmount($draws, $b3->id, 30000); } public function test_even_mode_redistributes_when_bucket_fills_up(): void { // Bucket A: $200 base, Bucket B: $500 base, Bucket C: $500 base // $900 income → even share = $300 each → A caps at $200, excess $100 redistributed // B and C get $300 + $50 = $350 each $a = $this->createNeedBucket(20000, priority: 1); $b = $this->createNeedBucket(50000, priority: 2); $c = $this->createNeedBucket(50000, priority: 3); $draws = $this->service->allocateInflow($this->scenario, 90000); $this->assertCount(3, $draws); $this->assertDrawAmount($draws, $a->id, 20000); $this->assertDrawAmount($draws, $b->id, 35000); $this->assertDrawAmount($draws, $c->id, 35000); } public function test_even_mode_needs_filled_before_wants(): void { // 2 need buckets ($500 base each), 1 want bucket ($500 base) // $800 income → needs get $400 each (even split), wants get $0 $n1 = $this->createNeedBucket(50000, priority: 1); $n2 = $this->createNeedBucket(50000, priority: 2); $w1 = $this->createWantBucket(50000, priority: 3); $draws = $this->service->allocateInflow($this->scenario, 80000); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $n1->id, 40000); $this->assertDrawAmount($draws, $n2->id, 40000); } public function test_even_mode_wants_filled_after_needs_base(): void { // 1 need ($300 base), 2 wants ($500 base each) // $1000 income → need gets $300 (base), wants split remaining $700 = $350 each $n = $this->createNeedBucket(30000, priority: 1); $w1 = $this->createWantBucket(50000, priority: 2); $w2 = $this->createWantBucket(50000, priority: 3); $draws = $this->service->allocateInflow($this->scenario, 100000); $this->assertCount(3, $draws); $this->assertDrawAmount($draws, $n->id, 30000); $this->assertDrawAmount($draws, $w1->id, 35000); $this->assertDrawAmount($draws, $w2->id, 35000); } public function test_even_mode_remainder_cents_go_to_highest_priority(): void { // 3 need buckets, $500 base each, $100 income → $33/$33/$34 or similar // intdiv(10000, 3) = 3333, remainder = 1 → first bucket gets 3334 $b1 = $this->createNeedBucket(50000, priority: 1); $b2 = $this->createNeedBucket(50000, priority: 2); $b3 = $this->createNeedBucket(50000, priority: 3); $draws = $this->service->allocateInflow($this->scenario, 10000); $this->assertCount(3, $draws); $this->assertDrawAmount($draws, $b1->id, 3334); $this->assertDrawAmount($draws, $b2->id, 3333); $this->assertDrawAmount($draws, $b3->id, 3333); } public function test_even_mode_fewer_cents_than_buckets(): void { // 3 need buckets, 2 cents income → first 2 get 1 cent each, third gets nothing $b1 = $this->createNeedBucket(50000, priority: 1); $b2 = $this->createNeedBucket(50000, priority: 2); $b3 = $this->createNeedBucket(50000, priority: 3); $draws = $this->service->allocateInflow($this->scenario, 2); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $b1->id, 1); $this->assertDrawAmount($draws, $b2->id, 1); } // ────────────────────────────────────────────────────── // Priority mode — base phase // ────────────────────────────────────────────────────── public function test_priority_mode_fills_highest_priority_first(): void { $scenario = Scenario::factory()->priority()->create(); $n1 = $this->createNeedBucket(50000, priority: 1, scenarioId: $scenario->id); $n2 = $this->createNeedBucket(50000, priority: 2, scenarioId: $scenario->id); $w1 = $this->createWantBucket(50000, priority: 3, scenarioId: $scenario->id); // $800 → need1 gets $500, need2 gets $300, want gets $0 $draws = $this->service->allocateInflow($scenario, 80000); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $n1->id, 50000); $this->assertDrawAmount($draws, $n2->id, 30000); } public function test_priority_mode_needs_before_wants(): void { $scenario = Scenario::factory()->priority()->create(); $n1 = $this->createNeedBucket(50000, priority: 1, scenarioId: $scenario->id); $n2 = $this->createNeedBucket(30000, priority: 2, scenarioId: $scenario->id); $w1 = $this->createWantBucket(50000, priority: 3, scenarioId: $scenario->id); // $1000 → need1 $500, need2 $300, want1 gets remaining $200 $draws = $this->service->allocateInflow($scenario, 100000); $this->assertCount(3, $draws); $this->assertDrawAmount($draws, $n1->id, 50000); $this->assertDrawAmount($draws, $n2->id, 30000); $this->assertDrawAmount($draws, $w1->id, 20000); } // ────────────────────────────────────────────────────── // Buffer phases // ────────────────────────────────────────────────────── public function test_base_filled_before_buffer(): void { // Need: $500 base, 0.5x buffer → $750 effective capacity // $2000 income → base phase: $500, buffer phase: $250, overflow: $1250 $n = $this->createNeedBucket(50000, priority: 1, buffer: 0.5); $overflow = $this->createOverflowBucket(priority: 2); $draws = $this->service->allocateInflow($this->scenario, 200000); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $n->id, 75000); // base $500 + buffer $250 $this->assertDrawAmount($draws, $overflow->id, 125000); } public function test_need_buffer_filled_before_want_buffer(): void { // Need: $500 base, 1x buffer → $1000 effective // Want: $500 base, 1x buffer → $1000 effective // $1800 → need base $500, want base $500, need buffer $500, want gets $300 buffer $n = $this->createNeedBucket(50000, priority: 1, buffer: 1.0); $w = $this->createWantBucket(50000, priority: 2, buffer: 1.0); $draws = $this->service->allocateInflow($this->scenario, 180000); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $n->id, 100000); // full: base + buffer $this->assertDrawAmount($draws, $w->id, 80000); // base $500 + $300 buffer } public function test_priority_mode_buffer_fills_by_priority(): void { $scenario = Scenario::factory()->priority()->create(); // Need1: $300 base, 1x buffer → $600 effective // Need2: $300 base, 1x buffer → $600 effective // $1000 income $n1 = $this->createNeedBucket(30000, priority: 1, buffer: 1.0, scenarioId: $scenario->id); $n2 = $this->createNeedBucket(30000, priority: 2, buffer: 1.0, scenarioId: $scenario->id); $draws = $this->service->allocateInflow($scenario, 100000); // Phase 1 (needs base, priority): n1=$300, n2=$300, remaining=$400 // Phase 3 (needs buffer, priority): n1 buffer=$300, n2 gets $100, remaining=$0 $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $n1->id, 60000); // full base + full buffer $this->assertDrawAmount($draws, $n2->id, 40000); // full base + $100 buffer } public function test_no_buffer_when_multiplier_is_zero(): void { // Need: $500 base, 0x buffer → $500 effective // $800 → need gets $500, overflow gets $300 $n = $this->createNeedBucket(50000, priority: 1, buffer: 0); $overflow = $this->createOverflowBucket(priority: 2); $draws = $this->service->allocateInflow($this->scenario, 80000); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $n->id, 50000); $this->assertDrawAmount($draws, $overflow->id, 30000); } public function test_partially_filled_bucket_respects_existing_balance(): void { // Need: $500 base, already has $300 → only $200 space in base phase $n = $this->createNeedBucket(50000, priority: 1, startingAmount: 30000); $overflow = $this->createOverflowBucket(priority: 2); $draws = $this->service->allocateInflow($this->scenario, 80000); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $n->id, 20000); $this->assertDrawAmount($draws, $overflow->id, 60000); } // ────────────────────────────────────────────────────── // Overflow // ────────────────────────────────────────────────────── public function test_overflow_captures_remainder(): void { $n = $this->createNeedBucket(30000, priority: 1); $overflow = $this->createOverflowBucket(priority: 2); $draws = $this->service->allocateInflow($this->scenario, 100000); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $n->id, 30000); $this->assertDrawAmount($draws, $overflow->id, 70000); } public function test_all_buckets_full_everything_to_overflow(): void { $n = $this->createNeedBucket(10000, priority: 1, startingAmount: 10000); // already full $w = $this->createWantBucket(10000, priority: 2, startingAmount: 10000); // already full $overflow = $this->createOverflowBucket(priority: 3); $draws = $this->service->allocateInflow($this->scenario, 50000); $this->assertCount(1, $draws); $this->assertDrawAmount($draws, $overflow->id, 50000); } // ────────────────────────────────────────────────────── // Edge cases // ────────────────────────────────────────────────────── public function test_no_need_buckets_goes_straight_to_wants(): void { $w1 = $this->createWantBucket(50000, priority: 1); $w2 = $this->createWantBucket(50000, priority: 2); $draws = $this->service->allocateInflow($this->scenario, 60000); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $w1->id, 30000); $this->assertDrawAmount($draws, $w2->id, 30000); } public function test_single_need_bucket_gets_all_up_to_capacity(): void { $n = $this->createNeedBucket(50000, priority: 1); $draws = $this->service->allocateInflow($this->scenario, 30000); $this->assertCount(1, $draws); $this->assertDrawAmount($draws, $n->id, 30000); } public function test_allocates_to_single_need_bucket_with_buffer(): void { // $500 base, 1x buffer → $1000 effective, $1000 income → gets all $n = $this->createNeedBucket(50000, priority: 1, buffer: 1.0); $draws = $this->service->allocateInflow($this->scenario, 100000); $this->assertCount(1, $draws); $this->assertDrawAmount($draws, $n->id, 100000); } public function test_skips_buckets_with_zero_allocation_value(): void { $zero = $this->createNeedBucket(0, priority: 1); $normal = $this->createNeedBucket(30000, priority: 2); $draws = $this->service->allocateInflow($this->scenario, 20000); $this->assertCount(1, $draws); $this->assertDrawAmount($draws, $normal->id, 20000); } public function test_non_fixed_limit_buckets_are_skipped_in_phases(): void { // Percentage bucket as need → gets nothing (no meaningful cap in phased distribution) Bucket::factory()->create([ 'scenario_id' => $this->scenario->id, 'type' => BucketTypeEnum::NEED, 'allocation_type' => BucketAllocationTypeEnum::PERCENTAGE, 'allocation_value' => 2500, 'starting_amount' => 0, 'priority' => 1, ]); $overflow = $this->createOverflowBucket(priority: 2); $draws = $this->service->allocateInflow($this->scenario, 50000); $this->assertCount(1, $draws); $this->assertDrawAmount($draws, $overflow->id, 50000); } public function test_surplus_is_lost_when_no_overflow_bucket(): void { // $500 income, only $300 capacity → $200 surplus has nowhere to go $n = $this->createNeedBucket(30000, priority: 1); $draws = $this->service->allocateInflow($this->scenario, 50000); $this->assertCount(1, $draws); $this->assertDrawAmount($draws, $n->id, 30000); // Remaining $200 is silently dropped — no overflow bucket to catch it } public function test_priority_order_respected_regardless_of_creation_order(): void { $scenario = Scenario::factory()->priority()->create(); // Create in reverse priority order $b3 = $this->createNeedBucket(10000, priority: 10, scenarioId: $scenario->id); $b1 = $this->createNeedBucket(20000, priority: 1, scenarioId: $scenario->id); $b2 = $this->createNeedBucket(15000, priority: 5, scenarioId: $scenario->id); $draws = $this->service->allocateInflow($scenario, 25000); $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $b1->id, 20000); $this->assertDrawAmount($draws, $b2->id, 5000); } // ────────────────────────────────────────────────────── // Full pipeline integration // ────────────────────────────────────────────────────── public function test_full_pipeline_even_mode(): void { // Need1: $500 base, 0.5x buffer → $750 effective // Need2: $200 base, no buffer → $200 effective // Want1: $400 base, no buffer → $400 effective // Overflow // $900 income — not enough to fill everything $n1 = $this->createNeedBucket(50000, priority: 1, buffer: 0.5); $n2 = $this->createNeedBucket(20000, priority: 2); $w1 = $this->createWantBucket(40000, priority: 3); $overflow = $this->createOverflowBucket(priority: 4); $draws = $this->service->allocateInflow($this->scenario, 90000); // Phase 1 (needs base, even): n1=$500 (capped), n2=$200 (capped), remaining=$200 // Phase 2 (wants base, even): w1=$200 (partial of $400), remaining=$0 $this->assertCount(3, $draws); $this->assertDrawAmount($draws, $n1->id, 50000); // $500 base $this->assertDrawAmount($draws, $n2->id, 20000); // $200 base $this->assertDrawAmount($draws, $w1->id, 20000); // partial $200 of $400 } public function test_full_pipeline_priority_mode(): void { $scenario = Scenario::factory()->priority()->create(); // Need1: $500 base, 0.5x buffer → $750 effective // Need2: $400 base, no buffer → $400 effective // Want1: $300 base, no buffer → $300 effective // Overflow // $600 income — not enough to fill all need bases $n1 = $this->createNeedBucket(50000, priority: 1, buffer: 0.5, scenarioId: $scenario->id); $n2 = $this->createNeedBucket(40000, priority: 2, scenarioId: $scenario->id); $w1 = $this->createWantBucket(30000, priority: 3, scenarioId: $scenario->id); $overflow = $this->createOverflowBucket(priority: 4, scenarioId: $scenario->id); $draws = $this->service->allocateInflow($scenario, 60000); // Phase 1 (needs base, priority): n1=$500, n2=$100, remaining=$0 // Even mode would split $600/2=$300 each — priority concentrates on n1 first $this->assertCount(2, $draws); $this->assertDrawAmount($draws, $n1->id, 50000); $this->assertDrawAmount($draws, $n2->id, 10000); } public function test_even_and_priority_modes_produce_different_results(): void { // 2 need buckets: $500 and $300 base, $600 income // Even: $300 each → both fit. n1=$300, n2=$300. // Priority: n1 gets $500, n2 gets $100. $n1Even = $this->createNeedBucket(50000, priority: 1); $n2Even = $this->createNeedBucket(30000, priority: 2); $evenDraws = $this->service->allocateInflow($this->scenario, 60000); $this->assertCount(2, $evenDraws); $this->assertDrawAmount($evenDraws, $n1Even->id, 30000); // even: $300 each $this->assertDrawAmount($evenDraws, $n2Even->id, 30000); // Same setup with priority mode $priorityScenario = Scenario::factory()->priority()->create(); $n1Prio = $this->createNeedBucket(50000, priority: 1, scenarioId: $priorityScenario->id); $n2Prio = $this->createNeedBucket(30000, priority: 2, scenarioId: $priorityScenario->id); $prioDraws = $this->service->allocateInflow($priorityScenario, 60000); $this->assertCount(2, $prioDraws); $this->assertDrawAmount($prioDraws, $n1Prio->id, 50000); // priority: fills first $this->assertDrawAmount($prioDraws, $n2Prio->id, 10000); // gets remainder } public function test_full_pipeline_flows_through_all_five_phases(): void { // Need: $200 base, 1x buffer → $400 effective // Want: $100 base, 1x buffer → $200 effective // Overflow // $800 income → enough to fill everything and hit overflow $n = $this->createNeedBucket(20000, priority: 1, buffer: 1.0); $w = $this->createWantBucket(10000, priority: 2, buffer: 1.0); $overflow = $this->createOverflowBucket(priority: 3); $draws = $this->service->allocateInflow($this->scenario, 80000); // Phase 1 (needs base): n=$200, remaining=$600 // Phase 2 (wants base): w=$100, remaining=$500 // Phase 3 (needs buffer): n=$200 buffer, remaining=$300 // Phase 4 (wants buffer): w=$100 buffer, remaining=$200 // Phase 5 (overflow): $200 $this->assertCount(3, $draws); $this->assertDrawAmount($draws, $n->id, 40000); // $200 base + $200 buffer $this->assertDrawAmount($draws, $w->id, 20000); // $100 base + $100 buffer $this->assertDrawAmount($draws, $overflow->id, 20000); // remainder } // ────────────────────────────────────────────────────── // Helpers // ────────────────────────────────────────────────────── private function createNeedBucket( int $allocationValue, int $priority, float $buffer = 0, int $startingAmount = 0, ?int $scenarioId = null, ): Bucket { return Bucket::factory()->need()->fixedLimit($allocationValue)->create([ 'scenario_id' => $scenarioId ?? $this->scenario->id, 'priority' => $priority, 'buffer_multiplier' => $buffer, 'starting_amount' => $startingAmount, ]); } private function createWantBucket( int $allocationValue, int $priority, float $buffer = 0, int $startingAmount = 0, ?int $scenarioId = null, ): Bucket { return Bucket::factory()->want()->fixedLimit($allocationValue)->create([ 'scenario_id' => $scenarioId ?? $this->scenario->id, 'priority' => $priority, 'buffer_multiplier' => $buffer, 'starting_amount' => $startingAmount, ]); } private function createOverflowBucket(int $priority, ?int $scenarioId = null): Bucket { return Bucket::factory()->overflow()->create([ 'scenario_id' => $scenarioId ?? $this->scenario->id, 'priority' => $priority, ]); } private function assertDrawAmount($draws, int $bucketId, int $expectedAmount): void { $draw = $draws->first(fn ($d) => $d->bucket_id === $bucketId); $this->assertNotNull($draw, "No draw found for bucket {$bucketId}"); $this->assertEquals($expectedAmount, $draw->amount, "Draw amount mismatch for bucket {$bucketId}"); } }