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

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/allocation_flow/leftover_catalog_retry.js

@@ -0,0 +1,67 @@
+const leftover_unitary_blocks = require('../space_and_block_chooser/leftover_unitary_blocks')
+
+/**
+ * Records a stall, unless this is the one-shot retry that admits hidden unitaries.
+ * @param {object} context
+ * @param {object[]} effective_item_list
+ * @param {Record<string, number>} amounts_before
+ * @param {object} empty_space
+ * @param {string} fingerprint
+ * @param {object[]} block_list
+ * @returns {boolean} True when any effective item amount decreased.
+ */
+function update_skip_state_after_attempt(
+    context,
+    effective_item_list,
+    amounts_before,
+    empty_space,
+    fingerprint,
+    block_list
+)
+{
+    if (amount_decreased(effective_item_list, amounts_before))
+    {
+        context.space_skip_state.clear_stalls()
+        context.recovery_state.count = 0
+        return true
+    }
+    if (defer_stall_for_hidden_unitaries(context, block_list))
+    {
+        return false
+    }
+    context.space_skip_state.record_stall(empty_space, fingerprint)
+    return false
+}
+
+/**
+ * @param {object[]} effective_item_list
+ * @param {Record<string, number>} amounts_before
+ * @returns {boolean}
+ */
+function amount_decreased(effective_item_list, amounts_before)
+{
+    return effective_item_list.some(item => item.get_amount() < amounts_before[item.get_id()])
+}
+
+/**
+ * Opens the leftover catalog once when a no-progress attempt used only remembered unitaries.
+ * @param {object} context
+ * @param {object[]} block_list
+ * @returns {boolean} True when the space must be retried before it is stalled.
+ */
+function defer_stall_for_hidden_unitaries(context, block_list)
+{
+    const session = context.chooser_session?.obligate_compound_session
+    const remembered_only = leftover_unitary_blocks.blocks_are_remembered_unitaries_only(
+        block_list ?? [],
+        session
+    )
+    if (!remembered_only)
+    {
+        return false
+    }
+    session.admit_non_remembered_unitaries = true
+    return true
+}
+
+module.exports = { update_skip_state_after_attempt }

package/src/allocation_flow/run_allocation_iteration.js

@@ -9,6 +9,7 @@ const {
     update_item_continuation_lock
 } = require('./item_continuation_lock_gate')
 const { empty_space_stacks_on_tie_ratio_supporter } = require('../Allocation_Optimization/tie_ratio/tie_ratio_orientation_below_empty_space')
+const { update_skip_state_after_attempt } = require('./leftover_catalog_retry')
 
 /**
  * Runs one allocation iteration: chooser, LP attempt, skip-state update.
@@ -69,7 +70,8 @@ async function run_allocation_iteration(context, container, locked_item)
         effective_item_list,
         amounts_before,
         empty_space,
-        fingerprint
+        fingerprint,
+        block_list
     )
     update_item_continuation_lock(context, wall_output.single_slot_allocated_item_ids)
     context.picking_continuity.update_from_wall(wall_output.last_allocated_item_id)
@@ -117,29 +119,6 @@ function update_compound_probe_session(context, block_list, effective_item_list,
     }
 }
 
-/**
- * @param {object} context
- * @param {object[]} effective_item_list
- * @param {Record<string, number>} amounts_before
- * @param {object} empty_space
- * @param {string} fingerprint
- * @returns {boolean} True when any effective item amount decreased.
- */
-function update_skip_state_after_attempt(context, effective_item_list, amounts_before, empty_space, fingerprint)
-{
-    const progressed = effective_item_list.some(
-        item => item.get_amount() < amounts_before[item.get_id()]
-    )
-    if (progressed)
-    {
-        context.space_skip_state.clear_stalls()
-        context.recovery_state.count = 0
-        return true
-    }
-    context.space_skip_state.record_stall(empty_space, fingerprint)
-    return false
-}
-
 /**
  * @param {object[]} block_list
  * @returns {void}
@@ -152,4 +131,4 @@ function assert_blocks_available(block_list)
     }
 }
 
-module.exports = { run_allocation_iteration }
+module.exports = { run_allocation_iteration, update_skip_state_after_attempt }

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.

package/src/space_and_block_chooser/compound_first_with_leftover_fill.js

@@ -24,10 +24,10 @@ async function resolve_after_compound_probe(
 )
 {
     const compound_block_list = compound_blocks_from_list(pre_selected_block_list)
-    const leftover_block_list = leftover_unitary_blocks(
+    const leftover_block_list = leftover_unitary_blocks.from_session(
         pre_selected_block_list,
         compound_block_list,
-        filter_data.obligate_compound_session?.leftover_sku_shape_hashes
+        filter_data.obligate_compound_session
     )
     leftover_unitary_blocks.remember_leftover_sku_hashes(
         filter_data.obligate_compound_session,

package/src/space_and_block_chooser/leftover_sku_hashes.js

@@ -0,0 +1,159 @@
+const { cube_map_function } = require('../Blocks_Preparation/Cube_Map_Function')
+const round = require('../tools/Rounder')
+
+/**
+ * Stores leftover SKU shape hashes while compounds still remain.
+ * @param {{ leftover_sku_shape_hashes?: string[] }|undefined} session
+ * @param {object[]} leftover_block_list
+ * @param {object[]} compound_block_list
+ * @returns {void}
+ */
+function remember_leftover_sku_hashes(session, leftover_block_list, compound_block_list)
+{
+    if (!session || compound_block_list.length === 0 || leftover_block_list.length === 0)
+    {
+        return
+    }
+    if (session.leftover_sku_shape_hashes?.length > 0)
+    {
+        return
+    }
+    session.leftover_sku_shape_hashes = [...leftover_sku_shape_hashes(leftover_block_list)]
+}
+
+/**
+ * Width/height/length hashes for leftover 1-slot blocks, including swapped floor axes.
+ * @param {object[]} leftover_block_list
+ * @returns {Set<string>}
+ */
+function leftover_sku_shape_hashes(leftover_block_list)
+{
+    const hashes = new Set()
+    for (const block of leftover_block_list)
+    {
+        add_slot_orientation_hashes(hashes, block)
+    }
+    return hashes
+}
+
+/**
+ * @param {Set<string>} hashes
+ * @param {object} block
+ * @returns {void}
+ */
+function add_slot_orientation_hashes(hashes, block)
+{
+    if (typeof block.get_slot_list !== 'function')
+    {
+        return
+    }
+    const slot_list = block.get_slot_list()
+    if (slot_list.length !== 1 || typeof slot_list[0].get_width !== 'function')
+    {
+        return
+    }
+    hashes.add(cube_map_function(slot_list[0]))
+    hashes.add(swapped_length_width_hash(slot_list[0]))
+}
+
+/**
+ * @param {object} slot
+ * @returns {string}
+ */
+function swapped_length_width_hash(slot)
+{
+    return round(slot.get_length()) + ';' + round(slot.get_height()) + ';' + round(slot.get_width())
+}
+
+/**
+ * @param {Set<string>|string[]|undefined} remembered_sku_hashes
+ * @returns {Set<string>}
+ */
+function to_hash_set(remembered_sku_hashes)
+{
+    if (!remembered_sku_hashes)
+    {
+        return new Set()
+    }
+    if (remembered_sku_hashes instanceof Set)
+    {
+        return remembered_sku_hashes
+    }
+    return new Set(remembered_sku_hashes)
+}
+
+/**
+ * @param {object[]} compound_block_list
+ * @returns {Set<string>}
+ */
+function compound_slot_shape_hashes(compound_block_list)
+{
+    const hashes = new Set()
+    for (const block of compound_block_list)
+    {
+        add_compound_slot_hashes(hashes, block)
+    }
+    return hashes
+}
+
+/**
+ * @param {Set<string>} hashes
+ * @param {object} block
+ * @returns {void}
+ */
+function add_compound_slot_hashes(hashes, block)
+{
+    if (typeof block.get_slot_list !== 'function')
+    {
+        return
+    }
+    for (const slot of block.get_slot_list())
+    {
+        add_measured_slot_hash(hashes, slot)
+    }
+}
+
+/**
+ * @param {Set<string>} hashes
+ * @param {object} slot
+ * @returns {void}
+ */
+function add_measured_slot_hash(hashes, slot)
+{
+    if (typeof slot.get_width !== 'function')
+    {
+        return
+    }
+    hashes.add(cube_map_function(slot))
+    hashes.add(swapped_length_width_hash(slot))
+}
+
+/**
+ * @param {object} block
+ * @param {Set<string>} remembered
+ * @returns {boolean}
+ */
+function is_unitary_matching_hashes(block, remembered)
+{
+    if (typeof block.get_slot_list !== 'function')
+    {
+        return false
+    }
+    const slot_list = block.get_slot_list()
+    if (slot_list.length !== 1 || typeof slot_list[0].get_width !== 'function')
+    {
+        return false
+    }
+    return remembered.has(cube_map_function(slot_list[0]))
+        || remembered.has(swapped_length_width_hash(slot_list[0]))
+}
+
+module.exports = {
+    remember_leftover_sku_hashes,
+    leftover_sku_shape_hashes,
+    to_hash_set,
+    compound_slot_shape_hashes,
+    is_unitary_matching_hashes,
+    cube_map_function,
+    swapped_length_width_hash
+}

package/src/space_and_block_chooser/leftover_space_memory.js

@@ -56,12 +56,10 @@ function skip_probe_or_leftover_resolution(filter_data, empty_space_list, pre_se
 {
     const session = filter_data.obligate_compound_session
     const leftover_spaces = spaces_matching_remembered_leftover(empty_space_list, session)
-    const leftover_block_list = leftover_unitary_blocks(
+    const leftover_block_list = leftover_unitary_blocks.from_session(
         pre_selected_block_list,
-        pre_selected_block_list.filter(
-            block => typeof block.get_slot_list === 'function' && block.get_slot_list().length > 1
-        ),
-        session?.leftover_sku_shape_hashes
+        compound_blocks(pre_selected_block_list),
+        session
     )
     if (leftover_spaces.length > 0 && leftover_block_list.length > 0)
     {
@@ -75,6 +73,24 @@ function skip_probe_or_leftover_resolution(filter_data, empty_space_list, pre_se
     return skip_probe_resolution(empty_space_list, pre_selected_block_list)
 }
 
+/**
+ * @param {object[]} block_list
+ * @returns {object[]}
+ */
+function compound_blocks(block_list)
+{
+    return block_list.filter(is_compound_block)
+}
+
+/**
+ * @param {object} block
+ * @returns {boolean}
+ */
+function is_compound_block(block)
+{
+    return typeof block.get_slot_list === 'function' && block.get_slot_list().length > 1
+}
+
 function space_bbox(space)
 {
     if (typeof space.get_x !== 'function')

package/src/space_and_block_chooser/leftover_unitary_admission.js

@@ -0,0 +1,89 @@
+const {
+    to_hash_set,
+    is_unitary_matching_hashes
+} = require('./leftover_sku_hashes')
+
+/**
+ * 1-slot blocks whose shape is outside the remembered leftover allow-list.
+ * @param {object[]} pre_selected_block_list
+ * @param {Set<string>|string[]} [remembered_sku_hashes]
+ * @returns {object[]}
+ */
+function unitaries_outside_remembered_hashes(pre_selected_block_list, remembered_sku_hashes)
+{
+    const remembered = to_hash_set(remembered_sku_hashes)
+    return pre_selected_block_list.filter(block => is_hidden_unitary(block, remembered))
+}
+
+/**
+ * Remembered matches plus every other 1-slot block, in pre-selected order.
+ * @param {object[]} pre_selected_block_list
+ * @param {object[]} remembered_matches
+ * @param {Set<string>|string[]|undefined} remembered_sku_hashes
+ * @returns {object[]}
+ */
+function unite_with_hidden_unitaries(pre_selected_block_list, remembered_matches, remembered_sku_hashes)
+{
+    const hidden = new Set(
+        unitaries_outside_remembered_hashes(pre_selected_block_list, remembered_sku_hashes)
+    )
+    const remembered = new Set(remembered_matches)
+    return pre_selected_block_list.filter(block => remembered.has(block) || hidden.has(block))
+}
+
+/**
+ * True when every block is a remembered 1-slot and the one-shot release has not run.
+ * @param {object[]} block_list
+ * @param {{ leftover_sku_shape_hashes?: string[], admit_non_remembered_unitaries?: boolean }|undefined} session
+ * @returns {boolean}
+ */
+function blocks_are_remembered_unitaries_only(block_list, session)
+{
+    if (!session || session.admit_non_remembered_unitaries === true || block_list.length === 0)
+    {
+        return false
+    }
+    const remembered = to_hash_set(session.leftover_sku_shape_hashes)
+    if (remembered.size === 0)
+    {
+        return false
+    }
+    return block_list.every(block => is_unitary_matching_hashes(block, remembered))
+}
+
+/**
+ * @param {object} block
+ * @param {Set<string>} remembered
+ * @returns {boolean}
+ */
+function is_hidden_unitary(block, remembered)
+{
+    if (!is_single_slot_block(block))
+    {
+        return false
+    }
+    if (remembered.size === 0)
+    {
+        return true
+    }
+    return !is_unitary_matching_hashes(block, remembered)
+}
+
+/**
+ * @param {object} block
+ * @returns {boolean}
+ */
+function is_single_slot_block(block)
+{
+    if (typeof block.get_slot_list !== 'function')
+    {
+        return false
+    }
+    return block.get_slot_list().length === 1
+}
+
+module.exports = {
+    unitaries_outside_remembered_hashes,
+    unite_with_hidden_unitaries,
+    blocks_are_remembered_unitaries_only
+}