@jetta/blocks-allocator 0.0.0-stage → 0.1.0-0

package/src/Allocation_Optimization/block_builder/exceptions/Restricted_Block_Exception.js

@@ -0,0 +1,21 @@
+const { build_message_entry } = require('../../../messages/resolve_error_message_entry')
+const { ALLOCATOR_MESSAGE } = require('../../../messages/Allocator_Message')
+
+class Restricted_Block_Exception extends Error
+{
+    /**
+     * @param {{ id: string|number, restrict_to: number }} block_to_restrict
+     */
+    constructor(block_to_restrict)
+    {
+        const message_key = ALLOCATOR_MESSAGE.RESTRICTED_BLOCK
+        super(message_key)
+        this.message_entry = build_message_entry(
+            message_key,
+            [String(block_to_restrict.id), String(block_to_restrict.restrict_to)]
+        )
+        this.block_to_restrict = block_to_restrict
+    }
+}
+
+module.exports = Restricted_Block_Exception

package/src/Allocation_Optimization/block_builder/should_omit_block_group_id.js

@@ -0,0 +1,29 @@
+const math = require('@jetta/number-compare')
+
+const FULL_TIE_RATIO_SLOT_COUNT = 5
+const FLOOR_HEIGHT_Y = 0
+
+/**
+ * Whether a built block should omit a shared group id.
+ * Single-slot leftovers and remainder tie-ratio blocks (fewer than five slots)
+ * stay ungrouped. Full 3_2/2_3 walls keep a shared id only on the floor.
+ * Generic compounds always keep a shared id.
+ * @param {{ get_slot_list: () => unknown[], is_tie_ratio_block?: () => boolean }} block
+ * @param {number} [wall_height_y=0] - Empty-space y (height) of the wall being built.
+ * @returns {boolean}
+ */
+function should_omit_block_group_id(block, wall_height_y = FLOOR_HEIGHT_Y)
+{
+    const slot_count = block.get_slot_list().length
+    if (slot_count === 1)
+    {
+        return true
+    }
+    if (typeof block.is_tie_ratio_block === 'function' && block.is_tie_ratio_block())
+    {
+        return slot_count < FULL_TIE_RATIO_SLOT_COUNT || math.gt(wall_height_y, FLOOR_HEIGHT_Y)
+    }
+    return false
+}
+
+module.exports = should_omit_block_group_id

package/src/Allocation_Optimization/block_builder/snap_elevated_block_wall_items.js

@@ -0,0 +1,34 @@
+const math = require('@jetta/number-compare')
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const snap_stacked_items_to_floor_footprints = require(
+    '../tie_ratio/snap_stacked_items_to_floor_footprints'
+)
+
+/**
+ * Snaps stacked wall items onto unique floor (x, z) footprints.
+ * @param {object[]} item_in_block_list
+ * @param {object} wall_data
+ * @param {object[]} pending_wall_allocated_items
+ * @returns {object[]}
+ */
+function snap_elevated_block_wall_items(item_in_block_list, wall_data, pending_wall_allocated_items)
+{
+    if (!Cargo_Profile.snap_stacked_items_to_floor_footprints())
+    {
+        return item_in_block_list
+    }
+    if (!math.gt(wall_data.space_to_allocate.get_y(), 0))
+    {
+        return item_in_block_list
+    }
+    const allocated_items = collect_allocated_items(wall_data, pending_wall_allocated_items)
+    return snap_stacked_items_to_floor_footprints(item_in_block_list, allocated_items)
+}
+
+function collect_allocated_items(wall_data, pending_wall_allocated_items)
+{
+    const from_container = wall_data.container.get_allocated_items?.() ?? []
+    return from_container.concat(pending_wall_allocated_items)
+}
+
+module.exports = snap_elevated_block_wall_items

package/src/Allocation_Optimization/block_builder/stacking_rules_input.js

@@ -0,0 +1,52 @@
+const str_to_bool = require('../../tools/String_To_Boolean')
+
+/**
+ * Builds stacking-rules payload for {@link StackingFeasibilityChecker} from stacking metadata.
+ * @param {object} item_stacking_info - Output shape from `build_stacking_info`.
+ * @param {object} json - Item record with at least `stackingUnit`.
+ * @returns {object}
+ */
+function build_stacking_rules_from_info(item_stacking_info, json)
+{
+    const restrictions = item_stacking_info.restrictions ?? {}
+    return {
+        enableStackSameAreaOnly: str_to_bool(restrictions.empilharAreaIgual),
+        enableStackSameItemOnly: str_to_bool(restrictions.empilharItemIgual),
+        maximumNumberOfItemsAbove: item_stacking_info.max_stacking,
+        weight: item_stacking_info.weight,
+        enableMaximumNumberOfItemsAbove: is_maximum_stacking_enabled(json),
+        enableMaximumStackingWeight: is_supported_weight_enabled(json),
+        maximumStackingWeight: item_stacking_info.supported_weight,
+        enableOnlyAllowedFamilies: str_to_bool(restrictions.empilharFamilias),
+        allowedFamilies: item_stacking_info.supported_families,
+        family: item_stacking_info.stacking_family,
+        priority: item_stacking_info.priority ?? -666,
+        enableStackonlySamePriorities: str_to_bool(restrictions.empilharPrioridades)
+    }
+}
+
+/**
+ * @param {object} item - Object exposing `get_stacking_info()` and `get_json()`.
+ * @returns {object}
+ */
+function get_stacking_rules_input(item)
+{
+    return build_stacking_rules_from_info(item.get_stacking_info(), item.get_json())
+}
+
+function is_maximum_stacking_enabled(json)
+{
+    const stacking_unit = json.stackingUnit
+    return stacking_unit === 'maximumStacking' || stacking_unit === 'both'
+}
+
+function is_supported_weight_enabled(json)
+{
+    const stacking_unit = json.stackingUnit
+    return stacking_unit === undefined || stacking_unit === 'supportedWeight' || stacking_unit === 'both'
+}
+
+module.exports = {
+    build_stacking_rules_from_info,
+    get_stacking_rules_input
+}

package/src/Allocation_Optimization/cap_chosen_blocks_by_shape_stock.js

@@ -0,0 +1,110 @@
+const { Item_Amount_Controller } = require('@jetta/item-amount-controller')
+const {
+    block_has_sufficient_shape_stock,
+    build_required_shape_amounts
+} = require('./block_builder/block_shape_stock')
+const { cube_map_function } = require('../Blocks_Preparation/Cube_Map_Function')
+
+/**
+ * Trims chosen block instances using shape stock, simulating consumption in order.
+ *
+ * @param {{ block: object, amount: number }[]} chosen_blocks
+ * @param {object[]} item_list
+ * @returns {{ block: object, amount: number }[]}
+ */
+function cap_chosen_blocks_by_shape_stock(chosen_blocks, item_list)
+{
+    const item_map = build_item_map(item_list)
+    const provisional_amounts = new Item_Amount_Controller(item_list).copy()
+    const capped_choices = []
+
+    for (const choice of chosen_blocks)
+    {
+        const requested = Math.floor(Number(choice.amount) || 0)
+        if (requested <= 0 || choice.block.get_slot_list().length === 0)
+        {
+            continue
+        }
+        let allowed_instances = 0
+        for (let instance_index = 0; instance_index < requested; instance_index++)
+        {
+            if (!block_has_sufficient_shape_stock(choice.block, item_map, provisional_amounts))
+            {
+                break
+            }
+            deduct_block_from_amount_map(choice.block, item_map, provisional_amounts)
+            allowed_instances += 1
+        }
+        if (allowed_instances > 0)
+        {
+            capped_choices.push({ block: choice.block, amount: allowed_instances })
+        }
+    }
+
+    return capped_choices
+}
+
+/**
+ * @param {object[]} item_list
+ * @returns {object}
+ */
+function build_item_map(item_list)
+{
+    const item_map = {}
+    for (const item of item_list)
+    {
+        item_map[item.get_id()] = item
+    }
+    return item_map
+}
+
+/**
+ * @param {object} block
+ * @param {object} item_map
+ * @param {object} amount_map
+ * @returns {void}
+ */
+function deduct_block_from_amount_map(block, item_map, amount_map)
+{
+    const remaining_required = build_required_shape_amounts(block)
+    for (const [shape_hash, required_amount] of remaining_required)
+    {
+        let still_needed = required_amount
+        for (const item_id of Object.keys(item_map))
+        {
+            if (still_needed <= 0)
+            {
+                break
+            }
+            const item = item_map[item_id]
+            if (!item_can_form_shape(item, shape_hash))
+            {
+                continue
+            }
+            while (still_needed > 0 && amount_map.get_item_amount(item) > 0)
+            {
+                amount_map.discount_single_item(item)
+                still_needed -= 1
+            }
+        }
+    }
+}
+
+/**
+ * @param {object} item
+ * @param {string} shape_hash
+ * @returns {boolean}
+ */
+function item_can_form_shape(item, shape_hash)
+{
+    for (const rotated_item of item.get_all_rotated_options())
+    {
+        if (cube_map_function(rotated_item) === shape_hash)
+        {
+            return true
+        }
+    }
+    return false
+}
+
+module.exports = cap_chosen_blocks_by_shape_stock

package/src/Allocation_Optimization/density_groups/Adaptive_Density_Group_Preparer.js

@@ -0,0 +1,21 @@
+const { get_weight_utilization, get_space_utilization } = require('./Container_Utilization')
+const { select_adaptive_group_index } = require('./Adaptive_Density_Group_Selector')
+const { get_groups_with_stock } = require('./Density_Group_Stock')
+
+/**
+ * Computes the adaptive active group index from container utilization.
+ * @param {Map<number, Set<string>>} groups - Density group map.
+ * @param {number} group_count - Total group count.
+ * @param {number} active_group_index - Current active group index.
+ * @param {object} container - Current container.
+ * @param {object[]} item_list - Master item list.
+ * @returns {number}
+ */
+function resolve_adaptive_group_index(groups, group_count, active_group_index, container, item_list)
+{
+    const gap = get_weight_utilization(container) - get_space_utilization(container)
+    const stock_groups = get_groups_with_stock(groups, group_count, item_list)
+    return select_adaptive_group_index(gap, stock_groups, active_group_index)
+}
+
+module.exports = { resolve_adaptive_group_index }

package/src/Allocation_Optimization/density_groups/Adaptive_Density_Group_Selector.js

@@ -0,0 +1,55 @@
+const {
+    DEFAULT_WEIGHT_AHEAD_THRESHOLD,
+    DEFAULT_SPACE_AHEAD_THRESHOLD,
+    get_weight_ahead_threshold,
+    get_space_ahead_threshold,
+} = require('./Adaptive_Density_Group_Threshold_Resolver')
+
+const WEIGHT_AHEAD_THRESHOLD = DEFAULT_WEIGHT_AHEAD_THRESHOLD
+const SPACE_AHEAD_THRESHOLD = DEFAULT_SPACE_AHEAD_THRESHOLD
+const GAP_THRESHOLD = DEFAULT_SPACE_AHEAD_THRESHOLD
+
+/**
+ * Picks the active density group from utilization gap and groups that still have stock.
+ * Weight-ahead and space-ahead thresholds are read from `Cargo_Profile` (defaults 10 pp / 15 pp).
+ * @param {number} gap - Weight utilization minus space utilization.
+ * @param {number[]} groups_with_stock - Group indices that still have items with amount > 0.
+ * @param {number} current_index - Current active group index.
+ * @returns {number} Selected group index.
+ */
+function select_adaptive_group_index(gap, groups_with_stock, current_index)
+{
+    if (groups_with_stock.length === 0)
+    {
+        return current_index
+    }
+
+    const lowest_density_group = Math.min(...groups_with_stock)
+    const highest_density_group = Math.max(...groups_with_stock)
+    const weight_ahead_threshold = get_weight_ahead_threshold()
+    const space_ahead_threshold = get_space_ahead_threshold()
+
+    if (gap > weight_ahead_threshold)
+    {
+        return lowest_density_group
+    }
+
+    if (gap < -space_ahead_threshold)
+    {
+        return highest_density_group
+    }
+
+    if (groups_with_stock.includes(current_index))
+    {
+        return current_index
+    }
+
+    return lowest_density_group
+}
+
+module.exports = {
+    WEIGHT_AHEAD_THRESHOLD,
+    SPACE_AHEAD_THRESHOLD,
+    GAP_THRESHOLD,
+    select_adaptive_group_index
+}

package/src/Allocation_Optimization/density_groups/Adaptive_Density_Group_Threshold_Resolver.js

@@ -0,0 +1,28 @@
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const {
+    DEFAULT_WEIGHT_AHEAD_THRESHOLD,
+    DEFAULT_SPACE_AHEAD_THRESHOLD,
+} = require('./Adaptive_Density_Group_Thresholds')
+
+/**
+ * @returns {number} Weight-ahead gap threshold as a utilization fraction.
+ */
+function get_weight_ahead_threshold()
+{
+    return Cargo_Profile.density_groups_weight_ahead_threshold()
+}
+
+/**
+ * @returns {number} Space-ahead gap threshold as a utilization fraction.
+ */
+function get_space_ahead_threshold()
+{
+    return Cargo_Profile.density_groups_space_ahead_threshold()
+}
+
+module.exports = {
+    DEFAULT_WEIGHT_AHEAD_THRESHOLD,
+    DEFAULT_SPACE_AHEAD_THRESHOLD,
+    get_weight_ahead_threshold,
+    get_space_ahead_threshold,
+}

package/src/Allocation_Optimization/density_groups/Adaptive_Density_Group_Thresholds.js

@@ -0,0 +1,23 @@
+const DEFAULT_WEIGHT_AHEAD_THRESHOLD_PP = 10
+const DEFAULT_SPACE_AHEAD_THRESHOLD_PP = 15
+
+const DEFAULT_WEIGHT_AHEAD_THRESHOLD = DEFAULT_WEIGHT_AHEAD_THRESHOLD_PP / 100
+const DEFAULT_SPACE_AHEAD_THRESHOLD = DEFAULT_SPACE_AHEAD_THRESHOLD_PP / 100
+
+/**
+ * Converts a percentage-point threshold to a utilization fraction.
+ * @param {number} percentage_points - Threshold in percentage points (e.g. 10 for 10 pp).
+ * @returns {number}
+ */
+function percentage_points_to_fraction(percentage_points)
+{
+    return percentage_points / 100
+}
+
+module.exports = {
+    DEFAULT_WEIGHT_AHEAD_THRESHOLD_PP,
+    DEFAULT_SPACE_AHEAD_THRESHOLD_PP,
+    DEFAULT_WEIGHT_AHEAD_THRESHOLD,
+    DEFAULT_SPACE_AHEAD_THRESHOLD,
+    percentage_points_to_fraction,
+}

package/src/Allocation_Optimization/density_groups/Container_Utilization.js

@@ -0,0 +1,67 @@
+/**
+ * Computes the fraction of supported weight already loaded in the container.
+ * @param {object} container - Container with supported_weight() and get_allocated_items().
+ * @returns {number} Value in [0, 1].
+ */
+function get_weight_utilization(container)
+{
+    const allocated_items = container.get_allocated_items()
+    if (allocated_items.length === 0)
+    {
+        return 0
+    }
+
+    const loaded_weight = allocated_items.reduce((sum, item) => sum + item.get_weight(), 0)
+    const remaining_weight = container.supported_weight()
+    const weight_limit = loaded_weight + remaining_weight
+
+    if (weight_limit <= 0)
+    {
+        return 0
+    }
+
+    return loaded_weight / weight_limit
+}
+
+/**
+ * Computes the fraction of container volume occupied by allocated items.
+ * @param {object} container - Container with dimensions and get_allocated_items().
+ * @returns {number} Value in [0, 1].
+ */
+function get_space_utilization(container)
+{
+    const total_volume = get_container_volume(container)
+    if (total_volume <= 0)
+    {
+        return 0
+    }
+
+    const loaded_volume = sum_allocated_volume(container)
+    return Math.min(1, loaded_volume / total_volume)
+}
+
+/**
+ * @param {object} container - Container with get_allocated_items().
+ * @returns {number}
+ */
+function sum_allocated_volume(container)
+{
+    return container.get_allocated_items().reduce((sum, item) =>
+    {
+        return sum + item.get_width() * item.get_height() * item.get_length()
+    }, 0)
+}
+
+/**
+ * @param {object} container - Container with width, height, length accessors.
+ * @returns {number}
+ */
+function get_container_volume(container)
+{
+    return container.get_width() * container.get_height() * container.get_length()
+}
+
+module.exports = {
+    get_weight_utilization,
+    get_space_utilization
+}

package/src/Allocation_Optimization/density_groups/Density_Group_Partitioner.js

@@ -0,0 +1,74 @@
+const { calculate_item_density } = require('./Item_Density_Calculator')
+
+/**
+ * Partitions SKUs into density quantile groups (low to high density).
+ * @param {object[]} item_list - Items with get_id and dimensions.
+ * @param {number} group_count - Number of groups (>= 2).
+ * @returns {{ groups: Map<number, Set<string>>, group_meta: Array<{ index: number, min_density: number, max_density: number, size: number }> }}
+ */
+function partition_items_by_density(item_list, group_count)
+{
+    const count = Math.max(2, group_count)
+    const entries = item_list.map(calculate_item_density)
+
+    entries.sort((left, right) =>
+    {
+        if (left.density !== right.density)
+        {
+            return left.density - right.density
+        }
+        return String(left.item_id).localeCompare(String(right.item_id))
+    })
+
+    const groups = new Map()
+    const group_meta = []
+    const total = entries.length
+
+    for (let group_index = 0; group_index < count; group_index++)
+    {
+        groups.set(group_index, new Set())
+    }
+
+    if (total === 0)
+    {
+        return { groups, group_meta }
+    }
+
+    let cursor = 0
+    for (let group_index = 0; group_index < count; group_index++)
+    {
+        const remaining_groups = count - group_index
+        const remaining_items = total - cursor
+        const bucket_size = Math.ceil(remaining_items / remaining_groups)
+        const bucket = entries.slice(cursor, cursor + bucket_size)
+        cursor += bucket_size
+
+        const id_set = groups.get(group_index)
+        let min_density = Number.POSITIVE_INFINITY
+        let max_density = Number.NEGATIVE_INFINITY
+
+        for (const entry of bucket)
+        {
+            id_set.add(entry.item_id)
+            min_density = Math.min(min_density, entry.density)
+            max_density = Math.max(max_density, entry.density)
+        }
+
+        if (bucket.length === 0)
+        {
+            min_density = 0
+            max_density = 0
+        }
+
+        group_meta.push({
+            index: group_index,
+            min_density,
+            max_density,
+            size: bucket.length
+        })
+    }
+
+    return { groups, group_meta }
+}
+
+module.exports = { partition_items_by_density }

package/src/Allocation_Optimization/density_groups/Density_Group_Scheduler.js

@@ -0,0 +1,168 @@
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const { DENSITY_GROUPS_STRATEGY } = require('./Density_Groups_Strategy')
+const { partition_items_by_density } = require('./Density_Group_Partitioner')
+const { resolve_adaptive_group_index } = require('./Adaptive_Density_Group_Preparer')
+const {
+    find_group_index_for_item_id: find_item_group_index,
+    get_groups_with_stock: resolve_groups_with_stock
+} = require('./Density_Group_Stock')
+
+class Density_Group_Scheduler
+{
+    #groups
+    #group_count
+    #active_group_index = 0
+
+    /**
+     * @param {object[]} item_list - Full master item list at flow start.
+     */
+    constructor(item_list)
+    {
+        this.#group_count = Cargo_Profile.density_groups_count()
+        const { groups } = partition_items_by_density(item_list, this.#group_count)
+        this.#groups = groups
+    }
+
+    /**
+     * @param {object[]} item_list - Candidate items (may already be lock-filtered).
+     * @returns {object[]} Items in the active density group with stock > 0.
+     */
+    filter_item_list(item_list)
+    {
+        const active_ids = this.#groups.get(this.#active_group_index)
+        if (!active_ids)
+        {
+            return []
+        }
+
+        return item_list.filter(item => active_ids.has(item.get_id()) && item.get_amount() > 0)
+    }
+
+    /**
+     * @returns {boolean} True when the active group has at least one item with stock.
+     */
+    active_group_has_stock(item_list)
+    {
+        return this.filter_item_list(item_list).length > 0
+    }
+
+    /**
+     * Advances to the next non-empty group. Returns false when no group has stock.
+     * @param {object[]} item_list - Master item list.
+     * @returns {boolean}
+     */
+    skip_empty_groups(item_list)
+    {
+        if (this.#group_count <= 0)
+        {
+            return false
+        }
+
+        for (let step = 0; step < this.#group_count; step++)
+        {
+            if (this.active_group_has_stock(item_list))
+            {
+                return true
+            }
+            this.#active_group_index = (this.#active_group_index + 1) % this.#group_count
+        }
+
+        return false
+    }
+
+    /**
+     * Sets the active group before an iteration when adaptive strategy is enabled.
+     * @param {object} container - Current container.
+     * @param {object[]} item_list - Master item list.
+     * @param {object|null} locked_item - Item continuation lock, if any.
+     * @returns {void}
+     */
+    prepare_for_iteration(container, item_list, locked_item)
+    {
+        if (locked_item || Cargo_Profile.density_groups_strategy() !== DENSITY_GROUPS_STRATEGY.ADAPTIVE)
+        {
+            return
+        }
+
+        this.#active_group_index = resolve_adaptive_group_index(
+            this.#groups,
+            this.#group_count,
+            this.#active_group_index,
+            container,
+            item_list
+        )
+    }
+
+    /**
+     * Round-robin: move to the next density group after a successful wall allocation.
+     * @returns {void}
+     */
+    advance_after_successful_wall()
+    {
+        this.#active_group_index = (this.#active_group_index + 1) % this.#group_count
+    }
+
+    /**
+     * Notifies the scheduler after a successful wall based on the configured strategy.
+     * @returns {void}
+     */
+    on_successful_wall()
+    {
+        if (Cargo_Profile.density_groups_strategy() === DENSITY_GROUPS_STRATEGY.ADAPTIVE)
+        {
+            return
+        }
+
+        this.advance_after_successful_wall()
+    }
+
+    /**
+     * @returns {number}
+     */
+    get_active_group_index()
+    {
+        return this.#active_group_index
+    }
+
+    /**
+     * @returns {number}
+     */
+    get_group_count()
+    {
+        return this.#group_count
+    }
+
+    /**
+     * @param {string} item_id - Item identifier.
+     * @returns {number|null}
+     */
+    find_group_index_for_item_id(item_id)
+    {
+        return find_item_group_index(this.#groups, this.#group_count, item_id)
+    }
+
+    /**
+     * @param {object[]} item_list - Master item list.
+     * @returns {number[]}
+     */
+    get_groups_with_stock(item_list)
+    {
+        return resolve_groups_with_stock(this.#groups, this.#group_count, item_list)
+    }
+}
+
+/**
+ * @param {object[]} item_list - Master item list.
+ * @returns {Density_Group_Scheduler|null}
+ */
+function create_density_group_scheduler(item_list)
+{
+    if (!Cargo_Profile.enable_density_groups())
+    {
+        return null
+    }
+
+    return new Density_Group_Scheduler(item_list)
+}
+
+module.exports = { Density_Group_Scheduler, create_density_group_scheduler }