@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/space_and_block_chooser/leftover_unitary_blocks.js

@@ -0,0 +1,153 @@
+const { cube_map_function } = require('../Blocks_Preparation/Cube_Map_Function')
+const round = require('../tools/Rounder')
+
+/**
+ * 1-slot blocks of leftover SKUs: not used by remaining compounds, or remembered after compounds are gone.
+ * @param {object[]} pre_selected_block_list
+ * @param {object[]} compound_block_list
+ * @param {Set<string>|string[]} [remembered_sku_hashes]
+ * @returns {object[]}
+ */
+function leftover_unitary_blocks(pre_selected_block_list, compound_block_list, remembered_sku_hashes)
+{
+    const remembered = to_hash_set(remembered_sku_hashes)
+    if (remembered.size > 0)
+    {
+        return pre_selected_block_list.filter(block => is_unitary_matching_hashes(block, remembered))
+    }
+    return pre_selected_block_list.filter(
+        block => is_leftover_unitary_block(block, compound_slot_shape_hashes(compound_block_list))
+    )
+}
+
+/**
+ * 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
+ */
+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
+}
+
+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]))
+}
+
+function swapped_length_width_hash(slot)
+{
+    return round(slot.get_length()) + ';' + round(slot.get_height()) + ';' + round(slot.get_width())
+}
+
+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)
+}
+
+function compound_slot_shape_hashes(compound_block_list)
+{
+    const hashes = new Set()
+    for (const block of compound_block_list)
+    {
+        if (typeof block.get_slot_list !== 'function')
+        {
+            continue
+        }
+        for (const slot of block.get_slot_list())
+        {
+            if (typeof slot.get_width !== 'function')
+            {
+                continue
+            }
+            hashes.add(cube_map_function(slot))
+            hashes.add(swapped_length_width_hash(slot))
+        }
+    }
+    return hashes
+}
+
+function is_leftover_unitary_block(block, compound_slot_hashes)
+{
+    if (typeof block.get_slot_list !== 'function')
+    {
+        return false
+    }
+    const slot_list = block.get_slot_list()
+    if (slot_list.length !== 1)
+    {
+        return false
+    }
+    if (compound_slot_hashes.size === 0)
+    {
+        return true
+    }
+    if (typeof slot_list[0].get_width !== 'function')
+    {
+        return true
+    }
+    return !compound_slot_hashes.has(cube_map_function(slot_list[0]))
+        && !compound_slot_hashes.has(swapped_length_width_hash(slot_list[0]))
+}
+
+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]))
+}
+
+leftover_unitary_blocks.remember_leftover_sku_hashes = remember_leftover_sku_hashes
+leftover_unitary_blocks.leftover_sku_shape_hashes = leftover_sku_shape_hashes
+
+module.exports = leftover_unitary_blocks

package/src/space_and_block_chooser/leftover_unitary_empty_spaces.js

@@ -0,0 +1,135 @@
+const leftover_unitary_blocks = require('./leftover_unitary_blocks')
+const empty_spaces_where_post_selection_keeps_blocks = require('./empty_spaces_where_post_selection_keeps_blocks')
+
+/**
+ * Spaces that fail the compound probe but keep at least one pre-selected block.
+ * @param {Function} run_filters
+ * @param {object} filter_data
+ * @param {object[]} empty_space_list
+ * @param {object[]} pre_selected_block_list
+ * @param {object[]} compound_viable_spaces
+ * @returns {Promise<object[]>}
+ */
+async function leftover_unitary_empty_spaces(
+    run_filters,
+    filter_data,
+    empty_space_list,
+    pre_selected_block_list,
+    compound_viable_spaces
+)
+{
+    const leftover_candidates = empty_space_list.filter(
+        space => !compound_viable_spaces.includes(space)
+    )
+    if (leftover_candidates.length === 0)
+    {
+        return []
+    }
+    return empty_spaces_where_post_selection_keeps_blocks(
+        run_filters,
+        filter_data,
+        leftover_candidates,
+        pre_selected_block_list
+    )
+}
+
+/**
+ * Uses leftover spaces with leftover-SKU unitaries, or the original lists when leftover is empty.
+ * @param {object[]} empty_space_list
+ * @param {object[]} pre_selected_block_list
+ * @param {object[]} leftover_empty_spaces
+ * @param {object[]} [leftover_block_list]
+ * @returns {{ empty_spaces_for_chooser: object[], blocks_for_post_selection: object[], leftover_empty_spaces: object[], skip_cluster_rank: boolean }}
+ */
+function leftover_or_legacy_resolution(
+    empty_space_list,
+    pre_selected_block_list,
+    leftover_empty_spaces,
+    leftover_block_list
+)
+{
+    const blocks_for_leftover = leftover_block_list ?? pre_selected_block_list
+    if (leftover_empty_spaces.length > 0 && blocks_for_leftover.length > 0)
+    {
+        return {
+            empty_spaces_for_chooser: leftover_empty_spaces,
+            blocks_for_post_selection: blocks_for_leftover,
+            leftover_empty_spaces,
+            skip_cluster_rank: true
+        }
+    }
+    return {
+        empty_spaces_for_chooser: empty_space_list,
+        blocks_for_post_selection: pre_selected_block_list,
+        leftover_empty_spaces: leftover_empty_spaces.length > 0 ? leftover_empty_spaces : [],
+        skip_cluster_rank: false
+    }
+}
+
+/**
+ * ISSUE-1745 skip: all spaces and blocks, no compound probe, no cluster rank.
+ * @param {object[]} empty_space_list
+ * @param {object[]} pre_selected_block_list
+ * @returns {{ empty_spaces_for_chooser: object[], blocks_for_post_selection: object[], leftover_empty_spaces: object[], skip_cluster_rank: boolean }}
+ */
+function skip_probe_resolution(empty_space_list, pre_selected_block_list)
+{
+    return {
+        empty_spaces_for_chooser: empty_space_list,
+        blocks_for_post_selection: pre_selected_block_list,
+        leftover_empty_spaces: [],
+        skip_cluster_rank: true
+    }
+}
+
+/**
+ * Compound-viable spaces first; leftover or legacy when the probe is skipped or empty.
+ * @param {object} filter_data
+ * @param {object[]} empty_space_list
+ * @param {object[]} pre_selected_block_list
+ * @param {object[]} compound_block_list
+ * @param {object[]} viable_spaces
+ * @param {object[]} leftover_empty_spaces
+ * @returns {object}
+ */
+function resolve_compound_first_or_leftover(
+    filter_data,
+    empty_space_list,
+    pre_selected_block_list,
+    compound_block_list,
+    viable_spaces,
+    leftover_empty_spaces
+)
+{
+    const skip_probe = filter_data.obligate_compound_session?.skip_compound_probe === true
+    if (!skip_probe && viable_spaces.length > 0)
+    {
+        return {
+            empty_spaces_for_chooser: viable_spaces,
+            blocks_for_post_selection: compound_block_list,
+            leftover_empty_spaces,
+            skip_cluster_rank: false
+        }
+    }
+    if (viable_spaces.length === 0 && filter_data.obligate_compound_session)
+    {
+        filter_data.obligate_compound_session.skip_compound_probe = true
+    }
+    return leftover_or_legacy_resolution(
+        empty_space_list,
+        pre_selected_block_list,
+        leftover_empty_spaces,
+        leftover_unitary_blocks(
+            pre_selected_block_list,
+            compound_block_list,
+            filter_data.obligate_compound_session?.leftover_sku_shape_hashes
+        )
+    )
+}
+
+module.exports = {
+    leftover_unitary_empty_spaces,
+    leftover_or_legacy_resolution,
+    skip_probe_resolution,
+    resolve_compound_first_or_leftover
+}

package/src/space_and_block_chooser/probe_set_pool.js

@@ -0,0 +1,35 @@
+const PROBE_SET_POOL = [new Set(), new Set()]
+
+/**
+ * Returns an empty Set from a small pool (probe paths must not retain references).
+ * @returns {Set<object>}
+ */
+function borrow_empty_set()
+{
+    const borrowed = PROBE_SET_POOL.pop()
+    if (borrowed)
+    {
+        borrowed.clear()
+        return borrowed
+    }
+    return new Set()
+}
+
+const MAX_POOLED_SETS = 2
+
+/**
+ * @param {Set<object>} probe_set
+ */
+function release_probe_set(probe_set)
+{
+    if (PROBE_SET_POOL.length < MAX_POOLED_SETS)
+    {
+        probe_set.clear()
+        PROBE_SET_POOL.push(probe_set)
+    }
+}
+
+module.exports = {
+    borrow_empty_set,
+    release_probe_set
+}

package/src/space_and_block_chooser/run_space_and_block_selection_attempt.js

@@ -0,0 +1,88 @@
+const pre_selection_filters = require('./blocks_filters/pre_selection_filter/Pre_Selection_Filter_List')
+const pos_selection_filters = require('./blocks_filters/pos_selection_filters/Post_Selection_Filter_List')
+const resolve_empty_spaces_and_blocks_for_obligate_compound_first = require('./compound_first_empty_space_branch')
+const Cargo_Profile = require('../models/Cargo_Profile')
+const {ClassicEmptySpaceChooser} = require('@jetta/empty-spaces-manager')
+const build_allocated_item_snapshots = require('./build_allocated_item_snapshots')
+const Invalid_Space_To_Allocate_Exception = require('./exceptions/Invalid_Space_To_Allocate_Exception')
+const {Logger} = require('@jetta/logger')
+
+const logger = new Logger('Space and Blocks Creator')
+
+function choose_best_empty_space(
+    container,
+    empty_space_list,
+    item_list,
+    spaces_to_avoid = new Set(),
+    skip_cluster_rank = false
+)
+{
+    const chooser = new ClassicEmptySpaceChooser({
+        container,
+        empty_spaces: empty_space_list,
+        items: item_list,
+        allocated_items: build_allocated_item_snapshots(container),
+        cargo_profile: Cargo_Profile.get_cargo_profile_as_js_object(),
+        spaces_to_avoid
+    })
+    const classic_winner = chooser.evaluate_spaces()
+    if (skip_cluster_rank)
+    {
+        return classic_winner
+    }
+    return classic_winner
+}
+
+async function run_post_selection_or_null_on_invalid_space(run_filters, filter_data)
+{
+    try
+    {
+        const pos_selection_block_list = await run_filters(pos_selection_filters, filter_data)
+        if (pos_selection_block_list.length > 0)
+        {
+            return pos_selection_block_list
+        }
+        return null
+    }
+    catch (error)
+    {
+        if (error instanceof Invalid_Space_To_Allocate_Exception)
+        {
+            return null
+        }
+        throw error
+    }
+}
+
+/**
+ * Runs pre-selection, optional compound-first narrowing, empty-space choice, and post-selection.
+ *
+ * @param {Function} run_filters
+ * @param {Object} filter_data
+ * @param {Array<Object>} empty_space_list
+ * @returns {Promise<{ chosen_empty_space: Object, pos_selection_block_list: Array<Object>|null }>}
+ */
+async function run_space_and_block_selection_attempt(run_filters, filter_data, empty_space_list)
+{
+    logger.debug('filtering blocks before blocks and choosing empty space...')
+    const pre_selected_block_list = await run_filters(pre_selection_filters, filter_data)
+    const resolved = await resolve_empty_spaces_and_blocks_for_obligate_compound_first(
+        run_filters,
+        filter_data,
+        empty_space_list,
+        pre_selected_block_list
+    )
+    const chosen_empty_space = choose_best_empty_space(
+        filter_data.container,
+        resolved.empty_spaces_for_chooser,
+        filter_data.item_list,
+        filter_data.spaces_to_avoid,
+        resolved.skip_cluster_rank === true
+    )
+    filter_data.empty_space = chosen_empty_space
+    filter_data.block_list = resolved.blocks_for_post_selection
+    const pos_selection_block_list = await run_post_selection_or_null_on_invalid_space(run_filters, filter_data)
+    return { chosen_empty_space, pos_selection_block_list }
+}
+
+module.exports = run_space_and_block_selection_attempt

package/src/tools/Array_Validator.js

@@ -0,0 +1,6 @@
+module.exports = function is_valid_array(data)
+{
+    return data !== undefined
+        && Array.isArray(data)
+        && data.length > 0
+}

package/src/tools/Clone.js

@@ -0,0 +1,27 @@
+const is_number = (val) => typeof val === 'number' && !isNaN(val)
+const is_string = (val) => typeof val === 'string'
+
+module.exports = function clone(val)
+{
+    if (is_number(val))
+    {
+        return clone_number(val)
+    }
+
+    if (is_string(val))
+    {
+        return clone_string(val)
+    }
+
+    return JSON.parse(JSON.stringify(val))
+}
+
+function clone_string(val)
+{
+    return String(val)
+}
+
+function clone_number(val)
+{
+    return Number(val)
+}

package/src/tools/Hash.js

@@ -0,0 +1,8 @@
+const crypto = require('crypto')
+module.exports = function create_hash(val)
+{
+    const hash = crypto.createHash('shake256', { outputLength: 12 })
+        .update(val)
+        .digest('hex')
+    return hash
+}

package/src/tools/Rounder.js

@@ -0,0 +1,5 @@
+module.exports = function round(value)
+{
+    value = Number(value)
+    return Number(value.toFixed(3))
+}

package/src/tools/String_To_Boolean.js

@@ -0,0 +1,12 @@
+const is_boolean = (input) => typeof input === 'boolean'
+const is_number = (input) => typeof input === 'number'
+const is_undefined = (input) => input === undefined
+const is_true_str = (input) => ['true', '1', 'yes', 'on'].includes(String(input).trim().toLowerCase())
+
+const str_to_bool = (input, def = false) =>
+    is_boolean(input) ? input :
+        is_number(input) ? input !== 0 :
+            is_undefined(input) ? def :
+                is_true_str(input)
+
+module.exports = str_to_bool

package/src/tools/cargo_profile/Cargo_Profile_Field_Value_Resolver.js

@@ -0,0 +1,44 @@
+/**
+ * Parses a finite number from a numeric value or a decimal string; otherwise returns fallback.
+ * @param {unknown} raw
+ * @param {number} fallback
+ * @returns {number}
+ */
+function finite_float_from_string_or_number(raw, fallback)
+{
+    const parsed = typeof raw === 'number' ? raw : parseFloat(raw)
+    return Number.isFinite(parsed) ? parsed : fallback
+}
+
+/**
+ * Parses a finite integer from a numeric value or a string; otherwise returns fallback.
+ * @param {unknown} raw
+ * @param {number} fallback
+ * @returns {number}
+ */
+function finite_int_from_string_or_number(raw, fallback)
+{
+    const parsed = typeof raw === 'number' ? Math.trunc(raw) : parseInt(raw, 10)
+    return Number.isFinite(parsed) ? parsed : fallback
+}
+
+/**
+ * Like {@link finite_float_from_string_or_number} but returns undefined when raw is nullish or not parseable.
+ * @param {unknown} raw
+ * @returns {number|undefined}
+ */
+function optional_finite_float_from_string_or_number(raw)
+{
+    if (raw === undefined || raw === null)
+    {
+        return undefined
+    }
+    const parsed = typeof raw === 'number' ? raw : parseFloat(raw)
+    return Number.isFinite(parsed) ? parsed : undefined
+}
+
+module.exports = {
+    finite_float_from_string_or_number,
+    finite_int_from_string_or_number,
+    optional_finite_float_from_string_or_number,
+}

package/src/tools/compact_items_with_stock.js

@@ -0,0 +1,9 @@
+/**
+ * Returns a new list containing only items with positive remaining amount.
+ * @param {Array<{ get_amount: () => number }>} item_list
+ * @returns {Array<{ get_amount: () => number }>}
+ */
+module.exports = function compact_items_with_stock(item_list)
+{
+    return item_list.filter(item => item.get_amount() > 0)
+}

package/src/tools/mm_to_allocation_domain.js

@@ -0,0 +1,14 @@
+const round = require('./Rounder')
+
+/**
+ * Converts vertical gap from API millimeters into internal geometry units.
+ * Container and item extents use the same numeric domain (typically millimeters).
+ * @param {number} mm - Non-negative value from `config.algoritmo.empty_space_merge_max_vertical_offset_mm`.
+ * @returns {number} Rounded domain value for {@link EmptySpaceFinder} merge tolerance.
+ */
+function mm_to_allocation_domain(mm)
+{
+    return round(mm)
+}
+
+module.exports = mm_to_allocation_domain

package/src/tracing/Allocation_Tracer.js

@@ -0,0 +1,52 @@
+const { AsyncLocalStorage } = require('async_hooks')
+
+const storage = new AsyncLocalStorage()
+
+/**
+ * Resolves a request trace id from allocation input.
+ * Prefers `trace_id`; falls back to `_id` or a synthetic id so tracing never throws.
+ * @param {object} input - Allocation request payload.
+ * @returns {string}
+ */
+function resolve_trace_id(input)
+{
+    if (input == null || typeof input !== 'object')
+    {
+        return `bw-${Date.now()}`
+    }
+    if (input.trace_id != null && String(input.trace_id).length > 0)
+    {
+        return String(input.trace_id)
+    }
+    if (input._id != null && String(input._id).length > 0)
+    {
+        return String(input._id)
+    }
+    return `bw-${Date.now()}`
+}
+
+/**
+ * @returns {object|null} Current request tracer, or null outside a binding.
+ */
+function get_tracer()
+{
+    const store = storage.getStore()
+    return store?.tracer ?? null
+}
+
+/**
+ * Replaces the active tracer (mainly for tests).
+ * @param {object} tracer
+ * @param {() => Promise<*>|*} fn
+ * @returns {Promise<*>|*}
+ */
+function run_with_existing_tracer(tracer, fn)
+{
+    return storage.run({ tracer }, fn)
+}
+
+module.exports = {
+    resolve_trace_id,
+    run_with_existing_tracer,
+    get_tracer
+}

package/src/tracing/Trace_Context.js

@@ -0,0 +1,18 @@
+/**
+ * Stable English jstracer context names for blocks-wall timing spans.
+ */
+const TRACE_CONTEXT = Object.freeze({
+    MAIN_FLOW: 'main flow',
+    MAP_EMPTY_SPACES: 'map empty spaces',
+    BLOCKS_GENERATION: 'blocks generation',
+    CONTAINER_ALLOCATION: 'container allocation',
+    SPACE_AND_BLOCK_CHOICE: 'space and block choice',
+    LP_OPTIMIZE: 'lp optimize',
+    ITEM_SELECTION_POSITIONING: 'item selection positioning',
+    CHOSEN_BLOCK_STACKING_VALIDATION: 'chosen block stacking validation',
+    BLOCK_WALL_ALLOCATED: 'block wall allocated',
+    BLOCK_WALL_RETRY_OTHER_BLOCKS: 'block wall retry other blocks',
+    BLOCK_WALL_SPACE_EXHAUSTED: 'block wall space exhausted'
+})
+
+module.exports = { TRACE_CONTEXT }

package/src/tracing/trace_outcome.js

@@ -0,0 +1,18 @@
+const { get_tracer } = require('./Allocation_Tracer')
+
+/**
+ * Records a short success transaction for a wall-outcome context (allocated / retry / exhausted).
+ * @param {string} context - Outcome context name.
+ */
+function mark_trace_outcome(context)
+{
+    const tracer = get_tracer()
+    if (!tracer)
+    {
+        return
+    }
+    const tx_id = tracer.start_transaction(context)
+    tracer.end_transaction_succesfully(tx_id)
+}
+
+module.exports = { mark_trace_outcome }

package/src/tracing/traced_step.js

@@ -0,0 +1,57 @@
+const { get_tracer } = require('./Allocation_Tracer')
+
+/**
+ * Runs an async step under a Manual_Tracer transaction that always closes.
+ * @param {string} context - jstracer context name.
+ * @param {() => Promise<*>} fn - Step body.
+ * @returns {Promise<*>}
+ */
+async function traced_step(context, fn)
+{
+    const tracer = get_tracer()
+    if (!tracer)
+    {
+        return await fn()
+    }
+    const tx_id = tracer.start_transaction(context)
+    try
+    {
+        const result = await fn()
+        tracer.end_transaction_succesfully(tx_id)
+        return result
+    }
+    catch (error)
+    {
+        tracer.end_transaction_with_failure(tx_id)
+        throw error
+    }
+}
+
+/**
+ * Runs a sync step under a Manual_Tracer transaction that always closes.
+ * @param {string} context - jstracer context name.
+ * @param {() => *} fn - Step body.
+ * @returns {*}
+ */
+function traced_step_sync(context, fn)
+{
+    const tracer = get_tracer()
+    if (!tracer)
+    {
+        return fn()
+    }
+    const tx_id = tracer.start_transaction(context)
+    try
+    {
+        const result = fn()
+        tracer.end_transaction_succesfully(tx_id)
+        return result
+    }
+    catch (error)
+    {
+        tracer.end_transaction_with_failure(tx_id)
+        throw error
+    }
+}
+
+module.exports = { traced_step, traced_step_sync }