@jetta/blocks-allocator 0.2.1-1 → 0.2.1-2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jetta/blocks-allocator",
-    "version": "0.2.1-1",
+    "version": "0.2.1-2",
     "description": "Blocks wall allocation library",
     "main": "src/index.js",
     "exports": {

package/src/Allocation_Optimization/item_consumption_heuristic/Item_Chooser.js

@@ -1,24 +1,11 @@
 const No_Available_Items_Exception = require('./exceptions/No_Available_Items_Exception')
-const No_Slots_For_Items_Exception = require('./exceptions/No_Slots_For_Items_Exception')
 const Cargo_Profile = require('../../models/Cargo_Profile')
-const No_Suitable_Item_Exception = require('../block_builder/exceptions/No_Suitable_Item_Exception')
-const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
-const Allocated_Item = require('../../models/Allocated_Item')
-const { distribute_items_by_weight_range } = require('./Weight_Slot_Distribution')
-const {
-    resolve_choose_item_heuristic_context,
-    format_slot_label_for_exception
-} = require('./Choose_Item_Heuristic_Context')
-const {
-    calculate_total_stack_slots,
-    sort_stacking_slots_by_proximity
-} = require('./Stack_Slot_Calculator')
-const { order_items_by_capacity_bias } = require('./Capacity_Bias_Item_Order')
-const candidate_item_fits_axle_load = require('./axle_load/candidate_item_fits_axle_load')
+const { select_slot_item, select_preferred_or_heuristic } = require('./select_slot_item')
 
 /**
  * Chooses an item from available items by distributing them into stacking slots by weight
  * and returning the item in the slot closest to the block slot position.
+ * When the axle gate is on, legal SKUs in that band are ranked by hottest-axle ratio.
  * @param {object} data - Input bag.
  * @param {object} [data.slot] - Slot with get_y() and get_height() (production).
  * @param {object} [data.block_slot] - Legacy alias for slot (tests).
@@ -41,127 +28,8 @@ module.exports = function choose_item(data)
     {
         throw new No_Available_Items_Exception()
     }
-    const is_to_prefer_same_id = data.block.get_slot_list().length > 0 && previous_chosen_item_id !== undefined && Cargo_Profile.prefer_block_with_same_item()
-    return is_to_prefer_same_id ? prefer_same_id(data) : choose_item_with_heuristic(data)
-}
-
-function prefer_same_id(data)
-{
-    const { container, item_list, previous_chosen_item_id, item_position } = data
-    const allocation_item = item_list.find(item => item.get_id() === previous_chosen_item_id)
-    if (allocation_item)
-    {
-        const accepted_item = try_accept_candidate(data, container, allocation_item, item_position)
-        if (accepted_item)
-        {
-            return accepted_item
-        }
-    }
-
-    return choose_item_with_heuristic(data)
-}
-
-/**
- * Heuristic path: weight bands, proximity-ordered bands, stacking validation per candidate.
- * @param {object} data - Input bag (see choose_item).
- * @returns {object} Chosen item.
- */
-function choose_item_with_heuristic(data)
-{
-    const { slot, container, item_position } = resolve_choose_item_heuristic_context(data)
-    const { item_list, qty_of_slots } = data
-    const total_slots = calculate_total_stack_slots(container.get_height(), slot)
-    const stacking_slots = distribute_items_by_weight_range(item_list, total_slots)
-    const ordered_bands = sort_stacking_slots_by_proximity(
-        stacking_slots,
-        slot.get_y(),
-        slot.get_height()
-    )
-
-    for (const band of ordered_bands)
-    {
-        const candidate_items = band.items
-        while (candidate_items.length > 0)
-        {
-            const allocation_item = get_item(candidate_items, qty_of_slots, container)
-            const accepted_item = try_accept_candidate(data, container, allocation_item, item_position)
-            if (accepted_item)
-            {
-                return accepted_item
-            }
-
-            remove_item_from_candidate_list(candidate_items, allocation_item)
-        }
-    }
-
-    const slot_label = format_slot_label_for_exception(slot)
-    throw new No_Suitable_Item_Exception(ALLOCATOR_MESSAGE.NO_SUITABLE_ITEM, [slot_label])
-}
-
-/**
- * @param {object} data
- * @param {object} container
- * @param {object} allocation_item
- * @param {object} item_position
- * @returns {object|undefined}
- */
-function try_accept_candidate(data, container, allocation_item, item_position)
-{
-    const allocated_item = new Allocated_Item(
-        allocation_item,
-        item_position.x,
-        item_position.y,
-        item_position.z
-    )
-    if (!candidate_item_fits_axle_load(data, allocated_item))
-    {
-        return undefined
-    }
-    if (should_defer_loose_on_block_stacking_validation(data.block))
-    {
-        return allocated_item
-    }
-    if (!container.is_a_valid_stacking(allocated_item))
-    {
-        return undefined
-    }
-    return allocated_item
-}
-
-function should_defer_loose_on_block_stacking_validation(block)
-{
-    return Cargo_Profile.stack_loose_on_tie_ratio_blocks()
-        && block?.get_slot_list?.().length === 1
-}
-
-function remove_item_from_candidate_list(candidate_item_list, allocation_item)
-{
-    const index = candidate_item_list.indexOf(allocation_item)
-    if (index > -1)
-    {
-        candidate_item_list.splice(index, 1)
-    }
-}
-
-function get_item(item_list, qty_of_slots, container)
-{
-    if (qty_of_slots === undefined)
-    {
-        throw new No_Slots_For_Items_Exception()
-    }
-
-    if (item_list.length === 0)
-    {
-        throw new No_Available_Items_Exception()
-    }
-
-    const ordered_item_list = order_items_by_capacity_bias(item_list, container)
-    const preferable_item_list = ordered_item_list.filter(item => item.get_amount() >= qty_of_slots)
-
-    if (preferable_item_list.length > 0)
-    {
-        return preferable_item_list[0]
-    }
-
-    return ordered_item_list[0]
+    const is_to_prefer_same_id = data.block.get_slot_list().length > 0
+        && previous_chosen_item_id !== undefined
+        && Cargo_Profile.prefer_block_with_same_item()
+    return is_to_prefer_same_id ? select_preferred_or_heuristic(data) : select_slot_item(data)
 }

package/src/Allocation_Optimization/item_consumption_heuristic/axle_load/axle_load_exceeds_limit.js

@@ -1,5 +1,21 @@
 const { gt } = require('@jetta/number-compare')
 
+/**
+ * Hottest axle load as a fraction of the folga-adjusted cap. Above 1 is over limit.
+ * @param {object} env - Calculator output env with containers[].pesoEixos.
+ * @param {number} folga_percent - Slack percent (10 means 110% of pesoMaxFinal).
+ * @returns {number}
+ */
+function max_axle_load_ratio(env, folga_percent)
+{
+    let hottest_ratio = 0
+    for (const axle of collect_peso_eixos_rows(env))
+    {
+        hottest_ratio = Math.max(hottest_ratio, axle_row_ratio(axle, folga_percent))
+    }
+    return hottest_ratio
+}
+
 /**
  * Whether any container axle row exceeds the folga-adjusted final max.
  * @param {object} env - Calculator output env with containers[].pesoEixos.
@@ -8,15 +24,7 @@ const { gt } = require('@jetta/number-compare')
  */
 function axle_load_exceeds_limit(env, folga_percent)
 {
-    const axle_rows = collect_peso_eixos_rows(env)
-    for (const axle of axle_rows)
-    {
-        if (axle_row_exceeds_limit(axle, folga_percent))
-        {
-            return true
-        }
-    }
-    return false
+    return gt(max_axle_load_ratio(env, folga_percent), 1)
 }
 
 /**
@@ -25,12 +33,10 @@ function axle_load_exceeds_limit(env, folga_percent)
  */
 function collect_peso_eixos_rows(env)
 {
-    const containers = env.containers ?? []
     const rows = []
-    for (const container of containers)
+    for (const container of env.containers ?? [])
     {
-        const axle_list = container.pesoEixos ?? []
-        rows.push(...axle_list)
+        rows.push(...(container.pesoEixos ?? []))
     }
     return rows
 }
@@ -38,14 +44,19 @@ function collect_peso_eixos_rows(env)
 /**
  * @param {object} axle
  * @param {number} folga_percent
- * @returns {boolean}
+ * @returns {number}
  */
-function axle_row_exceeds_limit(axle, folga_percent)
+function axle_row_ratio(axle, folga_percent)
 {
     const loaded_kilograms = Number(axle.pesoCarregadoFinal ?? 0)
     const max_kilograms = Number(axle.pesoMaxFinal ?? 0)
     const limit_kilograms = max_kilograms * (1 + folga_percent / 100)
-    return gt(loaded_kilograms, limit_kilograms)
+    if (limit_kilograms === 0)
+    {
+        return loaded_kilograms > 0 ? Number.POSITIVE_INFINITY : 0
+    }
+    return loaded_kilograms / limit_kilograms
 }
 
 module.exports = axle_load_exceeds_limit
+module.exports.max_axle_load_ratio = max_axle_load_ratio

package/src/Allocation_Optimization/item_consumption_heuristic/axle_load/candidate_item_axle_score.js

@@ -0,0 +1,42 @@
+const { gt } = require('@jetta/number-compare')
+const Cargo_Profile = require('../../../models/Cargo_Profile')
+const { score_layout_axle_load } = require('./evaluate_layout_axle_load')
+const layout_fits_axle_load = require('./layout_fits_axle_load')
+
+/**
+ * Axle score for one candidate. fits is false when the cap is exceeded or physics fails.
+ * When the gate is off, ratio is 0 and fits is true.
+ * @param {object} data
+ * @param {object} allocated_item
+ * @returns {{ fits: boolean, ratio: number|undefined }}
+ */
+function candidate_item_axle_score(data, allocated_item)
+{
+    if (!Cargo_Profile.enable_axle_load_slot_gate() || !layout_fits_axle_load.transport_has_axles(data.transport))
+    {
+        return { fits: true, ratio: 0 }
+    }
+    const ratio = score_layout_axle_load(layout_probe(data, allocated_item))
+    if (ratio === undefined)
+    {
+        return { fits: false, ratio: undefined }
+    }
+    return { fits: gt(ratio, 1) === false, ratio }
+}
+
+/**
+ * @param {object} data
+ * @param {object} allocated_item
+ * @returns {object}
+ */
+function layout_probe(data, allocated_item)
+{
+    const pending_axle_items = data.pending_axle_items ?? []
+    return {
+        transport: data.transport,
+        container: data.container,
+        extra_items: pending_axle_items.concat(allocated_item)
+    }
+}
+
+module.exports = candidate_item_axle_score

package/src/Allocation_Optimization/item_consumption_heuristic/axle_load/evaluate_layout_axle_load.js

@@ -1,43 +1,63 @@
 const { calculate_weight_on_axles_physics } = require('@jetta/axle-load-calculator')
+const { gt } = require('@jetta/number-compare')
 const { Logger } = require('@jetta/logger')
 const Cargo_Profile = require('../../../models/Cargo_Profile')
 const clone_env_with_layout_items = require('./clone_env_with_layout_items')
 const axle_load_exceeds_limit = require('./axle_load_exceeds_limit')
+const { max_axle_load_ratio } = axle_load_exceeds_limit
 
 const logger = new Logger('Axle Load Slot Gate')
 
 /**
- * Runs axle physics for the current layout plus extra items on the active container.
+ * Hottest axle ratio for the layout, or undefined when physics cannot run.
  * @param {object} data
  * @param {object} data.transport
  * @param {object} data.container
  * @param {object[]} data.extra_items
- * @returns {boolean} True when no axle exceeds the folga-adjusted cap.
+ * @returns {number|undefined}
  */
-function evaluate_layout_axle_load(data)
+function score_layout_axle_load(data)
 {
     const env = clone_env_with_layout_items(data.transport, data.container, data.extra_items)
     try
     {
-        return layout_is_within_axle_limit(env)
+        return ratio_from_physics(env)
     }
     catch (error)
     {
         logger.warn(`axle calculator rejected layout: ${error.message}`)
+        return undefined
+    }
+}
+
+/**
+ * Runs axle physics for the current layout plus extra items on the active container.
+ * @param {object} data
+ * @param {object} data.transport
+ * @param {object} data.container
+ * @param {object[]} data.extra_items
+ * @returns {boolean} True when no axle exceeds the folga-adjusted cap.
+ */
+function evaluate_layout_axle_load(data)
+{
+    const ratio = score_layout_axle_load(data)
+    if (ratio === undefined)
+    {
         return false
     }
+    return gt(ratio, 1) === false
 }
 
 /**
  * @param {object} env
- * @returns {boolean}
+ * @returns {number}
  */
-function layout_is_within_axle_limit(env)
+function ratio_from_physics(env)
 {
     const output = calculate_weight_on_axles_physics({ envs: [env] })
-    const calculated_env = output.envs[0]
     const folga_percent = Cargo_Profile.axle_weight_gap_percent()
-    return axle_load_exceeds_limit(calculated_env, folga_percent) === false
+    return max_axle_load_ratio(output.envs[0], folga_percent)
 }
 
 module.exports = evaluate_layout_axle_load
+module.exports.score_layout_axle_load = score_layout_axle_load

package/src/Allocation_Optimization/item_consumption_heuristic/axle_load/layout_fits_axle_load.js

@@ -15,7 +15,7 @@ function layout_fits_axle_load(data)
     {
         return true
     }
-    if (!env_has_axles(data.transport))
+    if (!transport_has_axles(data.transport))
     {
         return true
     }
@@ -26,10 +26,11 @@ function layout_fits_axle_load(data)
  * @param {object|undefined} transport
  * @returns {boolean}
  */
-function env_has_axles(transport)
+function transport_has_axles(transport)
 {
     const env = transport?.get_axle_env_template?.()
     return Array.isArray(env?.eixos) && env.eixos.length > 0
 }
 
 module.exports = layout_fits_axle_load
+module.exports.transport_has_axles = transport_has_axles

package/src/Allocation_Optimization/item_consumption_heuristic/select_axle_balanced_slot_item.js

@@ -0,0 +1,143 @@
+const { lt } = require('@jetta/number-compare')
+const { get_item, remove_item_from_candidate_list } = require('./slot_candidate_order')
+const { score_without_commit, commit_scored_candidate } = require('./slot_candidate_acceptance')
+
+/**
+ * Legal SKU across every weight band with the lowest hottest-axle ratio.
+ * Ties keep band order, then candidate order inside the band.
+ * @param {object} data
+ * @param {object} context
+ * @returns {object|undefined}
+ */
+function commit_lowest_ratio_across_bands(data, context)
+{
+    const ranked = rank_every_band(data, context)
+    for (const selected of ranked)
+    {
+        const committed = commit_scored_candidate(data, context.container, selected)
+        if (committed)
+        {
+            return committed
+        }
+    }
+    return undefined
+}
+
+/**
+ * Best legal SKU across every band. Does not commit stacking.
+ * @param {object} data
+ * @param {object} context
+ * @returns {{ allocated_item: object, ratio: number, allocation_item: object }|undefined}
+ */
+function lowest_ratio_across_bands(data, context)
+{
+    const ranked = rank_every_band(data, context)
+    return ranked[0]
+}
+
+/**
+ * Preferred SKU scored without a stacking commit.
+ * @param {object} data
+ * @param {object} context
+ * @returns {{ allocated_item: object, ratio: number, allocation_item: object }|undefined}
+ */
+function score_preferred(data, context)
+{
+    const allocation_item = data.item_list.find(item => item.get_id() === data.previous_chosen_item_id)
+    if (!allocation_item)
+    {
+        return undefined
+    }
+    return score_without_commit(data, context, allocation_item)
+}
+
+/**
+ * @param {{ ratio: number }|undefined} preferred
+ * @param {{ ratio: number }|undefined} best
+ * @returns {boolean}
+ */
+function preferred_wins(preferred, best)
+{
+    if (!preferred)
+    {
+        return false
+    }
+    if (!best)
+    {
+        return true
+    }
+    return lt(best.ratio, preferred.ratio) === false
+}
+
+/**
+ * @param {object} data
+ * @param {object} context
+ * @returns {object[]}
+ */
+function rank_every_band(data, context)
+{
+    const scored = []
+    for (const band of context.ordered_bands)
+    {
+        scored.push(...rank_band(data, context, band.items.slice()))
+    }
+    return rank_by_ratio(scored)
+}
+
+/**
+ * @param {object} data
+ * @param {object} context
+ * @param {object[]} pending
+ * @returns {object[]}
+ */
+function rank_band(data, context, pending)
+{
+    const scored = []
+    while (pending.length > 0)
+    {
+        const allocation_item = get_item(pending, data.qty_of_slots, context.container)
+        const candidate = score_without_commit(data, context, allocation_item)
+        if (candidate)
+        {
+            scored.push(candidate)
+        }
+        remove_item_from_candidate_list(pending, allocation_item)
+    }
+    return rank_by_ratio(scored)
+}
+
+/**
+ * @param {{ ratio: number }[]} scored
+ * @returns {{ ratio: number }[]}
+ */
+function rank_by_ratio(scored)
+{
+    const ranked = []
+    for (const candidate of scored)
+    {
+        insert_by_ratio(ranked, candidate)
+    }
+    return ranked
+}
+
+/**
+ * @param {{ ratio: number }[]} ranked
+ * @param {{ ratio: number }} candidate
+ * @returns {void}
+ */
+function insert_by_ratio(ranked, candidate)
+{
+    let index = 0
+    while (index < ranked.length && lt(ranked[index].ratio, candidate.ratio))
+    {
+        index += 1
+    }
+    ranked.splice(index, 0, candidate)
+}
+
+module.exports = {
+    commit_lowest_ratio_across_bands,
+    lowest_ratio_across_bands,
+    score_preferred,
+    preferred_wins
+}

package/src/Allocation_Optimization/item_consumption_heuristic/select_slot_item.js

@@ -0,0 +1,149 @@
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const No_Suitable_Item_Exception = require('../block_builder/exceptions/No_Suitable_Item_Exception')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+const { distribute_items_by_weight_range } = require('./Weight_Slot_Distribution')
+const {
+    resolve_choose_item_heuristic_context,
+    format_slot_label_for_exception
+} = require('./Choose_Item_Heuristic_Context')
+const {
+    calculate_total_stack_slots,
+    sort_stacking_slots_by_proximity
+} = require('./Stack_Slot_Calculator')
+const { get_item, remove_item_from_candidate_list } = require('./slot_candidate_order')
+const { try_accept_candidate, commit_scored_candidate } = require('./slot_candidate_acceptance')
+const {
+    commit_lowest_ratio_across_bands,
+    lowest_ratio_across_bands,
+    score_preferred,
+    preferred_wins
+} = require('./select_axle_balanced_slot_item')
+
+/**
+ * Chooses a slot item. When the axle gate is on, the legal SKU with the lowest hottest-axle ratio wins.
+ * @param {object} data
+ * @returns {object}
+ */
+function select_slot_item(data)
+{
+    const context = build_band_context(data)
+    if (Cargo_Profile.enable_axle_load_slot_gate())
+    {
+        const selected = commit_lowest_ratio_across_bands(data, context)
+        if (!selected)
+        {
+            throw unsuitable(context.slot)
+        }
+        return selected
+    }
+    for (const band of context.ordered_bands)
+    {
+        const selected = first_accepted_in_band(data, context, band.items)
+        if (selected)
+        {
+            return selected
+        }
+    }
+    throw unsuitable(context.slot)
+}
+
+/**
+ * Same-id preference. Under the axle gate, that SKU wins only when it is not strictly hotter.
+ * @param {object} data
+ * @returns {object}
+ */
+function select_preferred_or_heuristic(data)
+{
+    if (!Cargo_Profile.enable_axle_load_slot_gate())
+    {
+        return preferred_or_first(data)
+    }
+    return preferred_or_balanced(data)
+}
+
+/**
+ * @param {object} data
+ * @returns {object}
+ */
+function preferred_or_first(data)
+{
+    const { container, item_list, previous_chosen_item_id, item_position } = data
+    const allocation_item = item_list.find(item => item.get_id() === previous_chosen_item_id)
+    if (allocation_item)
+    {
+        const accepted_item = try_accept_candidate(data, container, allocation_item, item_position)
+        if (accepted_item)
+        {
+            return accepted_item
+        }
+    }
+    return select_slot_item(data)
+}
+
+/**
+ * @param {object} data
+ * @returns {object}
+ */
+function preferred_or_balanced(data)
+{
+    const context = build_band_context(data)
+    const preferred = score_preferred(data, context)
+    const best = lowest_ratio_across_bands(data, context)
+    const winner = preferred_wins(preferred, best) ? preferred : best
+    if (!winner)
+    {
+        throw unsuitable(context.slot)
+    }
+    return commit_scored_candidate(data, context.container, winner)
+}
+
+/**
+ * @param {object} data
+ * @returns {object}
+ */
+function build_band_context(data)
+{
+    const { slot, container, item_position } = resolve_choose_item_heuristic_context(data)
+    const total_slots = calculate_total_stack_slots(container.get_height(), slot)
+    const stacking_slots = distribute_items_by_weight_range(data.item_list, total_slots)
+    const ordered_bands = sort_stacking_slots_by_proximity(stacking_slots, slot.get_y(), slot.get_height())
+    return { slot, container, item_position, ordered_bands }
+}
+
+/**
+ * @param {object} data
+ * @param {object} context
+ * @param {object[]} candidate_items
+ * @returns {object|undefined}
+ */
+function first_accepted_in_band(data, context, candidate_items)
+{
+    while (candidate_items.length > 0)
+    {
+        const allocation_item = get_item(candidate_items, data.qty_of_slots, context.container)
+        const accepted_item = try_accept_candidate(data, context.container, allocation_item, context.item_position)
+        if (accepted_item)
+        {
+            return accepted_item
+        }
+        remove_item_from_candidate_list(candidate_items, allocation_item)
+    }
+    return undefined
+}
+
+/**
+ * @param {object} slot
+ * @returns {No_Suitable_Item_Exception}
+ */
+function unsuitable(slot)
+{
+    return new No_Suitable_Item_Exception(
+        ALLOCATOR_MESSAGE.NO_SUITABLE_ITEM,
+        [format_slot_label_for_exception(slot)]
+    )
+}
+
+module.exports = {
+    select_slot_item,
+    select_preferred_or_heuristic
+}

package/src/Allocation_Optimization/item_consumption_heuristic/slot_candidate_acceptance.js

@@ -0,0 +1,110 @@
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const Allocated_Item = require('../../models/Allocated_Item')
+const candidate_item_fits_axle_load = require('./axle_load/candidate_item_fits_axle_load')
+const candidate_item_axle_score = require('./axle_load/candidate_item_axle_score')
+
+/**
+ * Builds the allocated item at the slot position.
+ * @param {object} allocation_item
+ * @param {object} item_position
+ * @returns {object}
+ */
+function build_allocated_item(allocation_item, item_position)
+{
+    return new Allocated_Item(allocation_item, item_position.x, item_position.y, item_position.z)
+}
+
+/**
+ * Accepts the first legal candidate and commits stacking.
+ * @param {object} data
+ * @param {object} container
+ * @param {object} allocation_item
+ * @param {object} item_position
+ * @returns {object|undefined}
+ */
+function try_accept_candidate(data, container, allocation_item, item_position)
+{
+    const allocated_item = build_allocated_item(allocation_item, item_position)
+    if (!candidate_item_fits_axle_load(data, allocated_item))
+    {
+        return undefined
+    }
+    if (should_defer_loose_on_block_stacking_validation(data.block))
+    {
+        return allocated_item
+    }
+    if (!container.is_a_valid_stacking(allocated_item))
+    {
+        return undefined
+    }
+    return allocated_item
+}
+
+/**
+ * Scores a candidate without writing the stacking index.
+ * @param {object} data
+ * @param {object} context
+ * @param {object} allocation_item
+ * @returns {{ allocated_item: object, ratio: number, allocation_item: object }|undefined}
+ */
+function score_without_commit(data, context, allocation_item)
+{
+    const allocated_item = build_allocated_item(allocation_item, context.item_position)
+    const score = candidate_item_axle_score(data, allocated_item)
+    if (!score.fits || !stacking_probe_allows(data, context.container, allocated_item))
+    {
+        return undefined
+    }
+    return { allocated_item, ratio: score.ratio, allocation_item }
+}
+
+/**
+ * Commits the chosen candidate into the live stacking index.
+ * @param {object} data
+ * @param {object} container
+ * @param {{ allocated_item: object }} scored
+ * @returns {object|undefined}
+ */
+function commit_scored_candidate(data, container, scored)
+{
+    if (should_defer_loose_on_block_stacking_validation(data.block))
+    {
+        return scored.allocated_item
+    }
+    if (!container.is_a_valid_stacking(scored.allocated_item))
+    {
+        return undefined
+    }
+    return scored.allocated_item
+}
+
+/**
+ * @param {object} data
+ * @param {object} container
+ * @param {object} allocated_item
+ * @returns {boolean}
+ */
+function stacking_probe_allows(data, container, allocated_item)
+{
+    if (should_defer_loose_on_block_stacking_validation(data.block))
+    {
+        return true
+    }
+    if (typeof container.probe_stacking === 'function')
+    {
+        return container.probe_stacking(allocated_item)
+    }
+    return container.is_a_valid_stacking(allocated_item)
+}
+
+function should_defer_loose_on_block_stacking_validation(block)
+{
+    return Cargo_Profile.stack_loose_on_tie_ratio_blocks()
+        && block?.get_slot_list?.().length === 1
+}
+
+module.exports = {
+    try_accept_candidate,
+    score_without_commit,
+    commit_scored_candidate
+}

package/src/Allocation_Optimization/item_consumption_heuristic/slot_candidate_order.js

@@ -0,0 +1,49 @@
+const No_Available_Items_Exception = require('./exceptions/No_Available_Items_Exception')
+const No_Slots_For_Items_Exception = require('./exceptions/No_Slots_For_Items_Exception')
+const { order_items_by_capacity_bias } = require('./Capacity_Bias_Item_Order')
+
+/**
+ * Removes one candidate from the working list.
+ * @param {object[]} candidate_item_list
+ * @param {object} allocation_item
+ * @returns {void}
+ */
+function remove_item_from_candidate_list(candidate_item_list, allocation_item)
+{
+    const index = candidate_item_list.indexOf(allocation_item)
+    if (index > -1)
+    {
+        candidate_item_list.splice(index, 1)
+    }
+}
+
+/**
+ * Next candidate in the existing capacity-bias order.
+ * @param {object[]} item_list
+ * @param {number|undefined} qty_of_slots
+ * @param {object} container
+ * @returns {object}
+ */
+function get_item(item_list, qty_of_slots, container)
+{
+    if (qty_of_slots === undefined)
+    {
+        throw new No_Slots_For_Items_Exception()
+    }
+    if (item_list.length === 0)
+    {
+        throw new No_Available_Items_Exception()
+    }
+    const ordered_item_list = order_items_by_capacity_bias(item_list, container)
+    const preferable_item_list = ordered_item_list.filter(item => item.get_amount() >= qty_of_slots)
+    if (preferable_item_list.length > 0)
+    {
+        return preferable_item_list[0]
+    }
+    return ordered_item_list[0]
+}
+
+module.exports = {
+    get_item,
+    remove_item_from_candidate_list
+}

package/src/models/transport/Container.js

@@ -87,6 +87,17 @@ class Container extends Space
         return this.#stacking_feasibility_checker.validate_stackings(item_data)
     }
 
+    /**
+     * Checks stacking on a clone so the live index stays unchanged.
+     * @param {object} item
+     * @returns {boolean}
+     */
+    probe_stacking(item)
+    {
+        const probe = this.#stacking_feasibility_checker.clone()
+        return probe.validate_stackings(create_input(item))
+    }
+
     /**
      * Drops provisional stacking commits left by failed slot/wall attempts.
      * Restores the pre-attempt checkpoint when stacking was touched; otherwise a no-op.