@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/Allocation_Optimization/tie_ratio/tie_ratio_orientation_from_group.js

@@ -0,0 +1,48 @@
+/**
+ * @param {object[]} allocated_items
+ * @returns {Map<string|number, '3_2'|'2_3'>}
+ */
+function build_tie_ratio_orientation_by_group_id(allocated_items)
+{
+    const orientation_by_group_id = new Map()
+    for (const item of allocated_items)
+    {
+        const orientation = item.get_tie_ratio_orientation?.()
+        if (orientation !== '3_2' && orientation !== '2_3')
+        {
+            continue
+        }
+        const group_id = item.get_group_id?.()
+        if (group_id === undefined || group_id === null)
+        {
+            continue
+        }
+        orientation_by_group_id.set(group_id, orientation)
+    }
+    return orientation_by_group_id
+}
+
+/**
+ * @param {object} item
+ * @param {Map<string|number, '3_2'|'2_3'>} orientation_by_group_id
+ * @returns {'3_2'|'2_3'|undefined}
+ */
+function tie_ratio_orientation_from_item(item, orientation_by_group_id)
+{
+    const direct_orientation = item.get_tie_ratio_orientation?.()
+    if (direct_orientation === '3_2' || direct_orientation === '2_3')
+    {
+        return direct_orientation
+    }
+    const group_id = item.get_group_id?.()
+    if (group_id === undefined || group_id === null)
+    {
+        return undefined
+    }
+    return orientation_by_group_id.get(group_id)
+}
+
+module.exports = {
+    build_tie_ratio_orientation_by_group_id,
+    tie_ratio_orientation_from_item
+}

package/src/Block_Management.js

@@ -0,0 +1,34 @@
+function clean_blocks_restricted_to_0(avaiable_usable_blocks, block_amount_restrictions)
+{
+    for (const restricted_id in block_amount_restrictions)
+    {
+        if (block_amount_restrictions[restricted_id] > 0)
+        {
+            continue
+        }
+        const removable_indexes = avaiable_usable_blocks
+            .map((item, index) => (item._id  === restricted_id ? index : -1))
+            .filter(index => index !== -1)
+
+        for (let index = removable_indexes.length - 1; index >= 0; index--)
+        {
+            avaiable_usable_blocks.splice(removable_indexes[index], 1)
+        }
+    }
+}
+
+function restrict_block(exception, block_amount_restrictions)
+{
+    const restriction = exception.block_to_restrict
+    if (!block_amount_restrictions[restriction.id])
+    {
+        block_amount_restrictions[restriction.id] = Number.POSITIVE_INFINITY
+    }
+
+    if (block_amount_restrictions[restriction.id] > restriction.restrict_to)
+    {
+        block_amount_restrictions[restriction.id] = restriction.restrict_to
+    }
+}
+
+module.exports = {clean_blocks_restricted_to_0, restrict_block}

package/src/Blocks_Preparation/Cube_Map_Function.js

@@ -0,0 +1,27 @@
+const round = require('../tools/Rounder')
+
+function cube_map_function(cube)
+{
+    return round(cube.get_width()) + ';' + round(cube.get_height()) + ';' + round(cube.get_length())
+}
+
+function item_map_function(item)
+{
+    return round(item.width) + ';' + round(item.height) + ';' + round(item.length)
+}
+
+function allocation_item_map_function(allocation_item)
+{
+    const item =
+    {
+        width: allocation_item.get_width(),
+        height: allocation_item.get_height(),
+        length: allocation_item.get_length()
+    }
+    return item_map_function(item)
+}
+module.exports = {
+    cube_map_function,
+    item_map_function,
+    allocation_item_map_function
+}

package/src/Blocks_Wall_Allocation.js

@@ -0,0 +1,3 @@
+const run_core_allocation = require('./run_core_allocation')
+
+module.exports = run_core_allocation

package/src/IO/Answer_Status.js

@@ -0,0 +1,4 @@
+ERROR = 'error'
+SUCCESS = 'success'
+
+module.exports = {ERROR, SUCCESS}

package/src/IO/Output_Builder.js

@@ -0,0 +1,35 @@
+const {SUCCESS} = require('./Answer_Status')
+const to_string = (data) => typeof data === 'string' ? data : JSON.stringify(data)
+
+module.exports = function build_output_answer(request_status, data)
+{
+    return request_status === SUCCESS ? _build_success_message(data) : to_string(data)
+}
+
+function _build_success_message(transport)
+{
+    const output_data   = []
+    const container_map = transport.get_containers()
+
+    for (const sequence of container_map.keys())
+    {
+        const container            = container_map.get(sequence)
+        const container_data       = {}
+        const environment          = {}
+        environment.id             = container.get_id()
+        environment._id            = container.get_id()
+        environment.sequencia      = sequence
+        container_data.environment = environment
+
+        const items                = _get_items(container.get_allocated_items())
+        container_data.items       = items
+
+        output_data.push(container_data)
+    }
+    return to_string(output_data)
+}
+
+function _get_items(item_list)
+{
+    return item_list.map(item => item.to_json())
+}

package/src/IO/count_allocated_items.js

@@ -0,0 +1,31 @@
+/**
+ * @param {object} transport - Transport after allocate().
+ * @returns {number} Total allocated items across all containers.
+ */
+function count_allocated_items_in_transport(transport)
+{
+    let total = 0
+    for (const sequence of transport.get_container_sequence_list())
+    {
+        const container = transport.get_container_by_sequence(sequence)
+        total += container.get_allocated_items().length
+    }
+    return total
+}
+
+/**
+ * @param {object} safe_input - Parsed allocation request with envs/containers.
+ * @returns {number} Pre-loaded items present in the input payload.
+ */
+function count_preloaded_items_in_input(safe_input)
+{
+    return safe_input.envs
+        .flatMap(transport => transport.containers)
+        .flatMap(container => container.items ?? [])
+        .length
+}
+
+module.exports = {
+    count_allocated_items_in_transport,
+    count_preloaded_items_in_input
+}

package/src/IO/create_error_response.js

@@ -0,0 +1,62 @@
+const resolve_error_message_entry = require('../messages/resolve_error_message_entry')
+const is_relational_error_code = require('../relational/is_relational_error_code')
+
+/**
+ * Builds the standard allocator error response envelope with catalog keys.
+ * @param {unknown} error_value
+ * @param {string} [response_status='error']
+ * @returns {object}
+ */
+function create_error_response(error_value, response_status = 'error')
+{
+    const errors = resolve_error_message_entry(error_value)
+    const primary_key = errors[0][0]
+    const envelope = {
+        data: primary_key,
+        apiError: primary_key,
+        status: response_status,
+        messages: {
+            errors,
+            warnings: [],
+            infos: []
+        }
+    }
+    append_relational_fields(envelope, error_value)
+    return envelope
+}
+
+/**
+ * @param {object} envelope
+ * @param {unknown} error_value
+ * @returns {void}
+ */
+function append_relational_fields(envelope, error_value)
+{
+    if (error_value === null || typeof error_value !== 'object')
+    {
+        return
+    }
+    if (!is_relational_error_code(error_value.code))
+    {
+        return
+    }
+    envelope.code = error_value.code
+    if (error_value.relational_group_id !== undefined)
+    {
+        envelope.relational_group_id = error_value.relational_group_id
+    }
+    if (error_value.container_sequences !== undefined)
+    {
+        envelope.container_sequences = error_value.container_sequences
+    }
+    if (error_value.allocated_counts !== undefined)
+    {
+        envelope.allocated_counts = error_value.allocated_counts
+    }
+    if (error_value.expected_counts !== undefined)
+    {
+        envelope.expected_counts = error_value.expected_counts
+    }
+}
+
+module.exports = create_error_response

package/src/IO/format_allocation_error_message.js

@@ -0,0 +1,25 @@
+const is_relational_error_code = require('../relational/is_relational_error_code')
+
+/**
+ * Copies relational metadata used by create_error_response.
+ * Prefer create_error_response for new wire paths.
+ * @param {Error} error
+ * @returns {object|undefined}
+ */
+function read_relational_error_fields(error)
+{
+    if (!is_relational_error_code(error.code))
+    {
+        return undefined
+    }
+
+    return {
+        code: error.code,
+        relational_group_id: error.relational_group_id,
+        container_sequences: error.container_sequences,
+        allocated_counts: error.allocated_counts,
+        expected_counts: error.expected_counts
+    }
+}
+
+module.exports = read_relational_error_fields

package/src/Item_Continuation_Lock.js

@@ -0,0 +1,129 @@
+/**
+ * Tracks an item that must be reused across iterations once a single-slot
+ * block has allocated it. The lock holds until the item runs out of stock or
+ * an iteration with the lock active produces no consumption of that item.
+ *
+ * Callers are expected to resolve the locked item once per iteration via
+ * {@link Item_Continuation_Lock#resolve_locked_item} and then pass that
+ * reference to the other query methods, keeping per-iteration cost O(n) for
+ * a single lookup instead of repeating it.
+ */
+class Item_Continuation_Lock
+{
+    #locked_item_id = null
+
+    /**
+     * Resolves the locked item against the current master list. Returns
+     * `null` when no lock is set or when the locked id is no longer present.
+     * Memoize the result per iteration and pass it to the other methods.
+     * @param {object[]} item_list - Master item list with current amounts.
+     * @returns {object|null}
+     */
+    resolve_locked_item(item_list)
+    {
+        if (this.#locked_item_id === null)
+        {
+            return null
+        }
+        const locked = item_list.find(item => item.get_id() === this.#locked_item_id)
+        return locked ?? null
+    }
+
+    /**
+     * Returns the item list to expose to the LP / chooser in the next
+     * iteration. When no item is locked, returns the original list. When the
+     * locked item is exhausted or missing, releases the lock and returns the
+     * original. Otherwise returns a list containing only the locked item.
+     * @param {object[]} item_list - Master item list with current amounts.
+     * @param {object|null} locked_item - Item previously resolved via {@link resolve_locked_item}.
+     * @returns {object[]}
+     */
+    get_effective_item_list(item_list, locked_item)
+    {
+        if (this.#locked_item_id === null)
+        {
+            return item_list
+        }
+        if (!locked_item || locked_item.get_amount() <= 0)
+        {
+            this.#locked_item_id = null
+            return item_list
+        }
+        return [locked_item]
+    }
+
+    /**
+     * Sets the lock to the first id reported by a single-slot allocation
+     * (no-op if a lock is already active or the set is empty).
+     * @param {Set<string>} single_slot_allocated_item_ids - Ids allocated via single-slot blocks.
+     * @returns {void}
+     */
+    update_from_iteration(single_slot_allocated_item_ids)
+    {
+        if (this.#locked_item_id !== null)
+        {
+            return
+        }
+        if (!single_slot_allocated_item_ids || single_slot_allocated_item_ids.size === 0)
+        {
+            return
+        }
+        const [first_id] = single_slot_allocated_item_ids
+        this.#locked_item_id = first_id
+    }
+
+    /**
+     * Snapshots the locked item's current amount, to be compared after the
+     * iteration runs. Returns null when no item is currently locked.
+     * @param {object|null} locked_item - Item previously resolved via {@link resolve_locked_item}.
+     * @returns {number|null}
+     */
+    snapshot_locked_amount(locked_item)
+    {
+        if (this.#locked_item_id === null)
+        {
+            return null
+        }
+        return locked_item ? locked_item.get_amount() : 0
+    }
+
+    /**
+     * Releases the lock when the locked item's amount has not changed since
+     * the snapshot, signaling that the last iteration made no progress on it.
+     * @param {number|null} amount_before - Snapshot returned by snapshot_locked_amount.
+     * @param {object|null} locked_item - Item previously resolved via {@link resolve_locked_item}.
+     * @returns {void}
+     */
+    release_if_no_progress(amount_before, locked_item)
+    {
+        if (this.#locked_item_id === null || amount_before === null)
+        {
+            return
+        }
+        const current_amount = locked_item ? locked_item.get_amount() : 0
+        if (current_amount === amount_before)
+        {
+            this.#locked_item_id = null
+        }
+    }
+
+    /**
+     * Clears the lock so density balancing can expose other SKUs.
+     * @returns {void}
+     */
+    release_for_density_balance()
+    {
+        this.#locked_item_id = null
+    }
+
+    /**
+     * Exposed for testing/diagnostics.
+     * @returns {string|null}
+     */
+    get_locked_item_id()
+    {
+        return this.#locked_item_id
+    }
+}
+
+module.exports = Item_Continuation_Lock

package/src/Item_Picking_Continuity.js

@@ -0,0 +1,41 @@
+const Cargo_Profile = require('./models/Cargo_Profile')
+
+/**
+ * Soft SKU continuity across walls: seeds the slot heuristic with the last
+ * allocated item from the previous successful wall without filtering the LP.
+ */
+class Item_Picking_Continuity
+{
+    #seed_item_id = null
+
+    /**
+     * @returns {string|null}
+     */
+    get_seed_item_id()
+    {
+        return this.#seed_item_id
+    }
+
+    /**
+     * @param {string|null|undefined} last_item_id
+     * @returns {void}
+     */
+    update_from_wall(last_item_id)
+    {
+        if (last_item_id == null || last_item_id === '' || !Cargo_Profile.prefer_block_with_same_item())
+        {
+            return
+        }
+        this.#seed_item_id = last_item_id
+    }
+
+    /**
+     * @returns {void}
+     */
+    reset()
+    {
+        this.#seed_item_id = null
+    }
+}
+
+module.exports = Item_Picking_Continuity

package/src/allocation_flow/chooser_session_state.js

@@ -0,0 +1,21 @@
+const Tie_Ratio_Intercalation_State = require('../Allocation_Optimization/tie_ratio/Tie_Ratio_Intercalation_State')
+const Cargo_Profile = require('../models/Cargo_Profile')
+
+/**
+ * Creates persistent chooser session state reused across allocation iterations.
+ * @returns {{
+ *   obligate_compound_session: { skip_compound_probe: boolean },
+ *   tie_ratio_intercalation_state: Tie_Ratio_Intercalation_State
+ * }}
+ */
+function create_chooser_session_state()
+{
+    return {
+        obligate_compound_session: { skip_compound_probe: false },
+        tie_ratio_intercalation_state: new Tie_Ratio_Intercalation_State(
+            Cargo_Profile.allocate_intercalated()
+        )
+    }
+}
+
+module.exports = { create_chooser_session_state }

package/src/allocation_flow/compound_probe_fallback.js

@@ -0,0 +1,17 @@
+const Cargo_Profile = require('../models/Cargo_Profile')
+
+/**
+ * Returns true when compound-first probing should be skipped on the next chooser pass.
+ * @param {object[]} block_list - Blocks selected for the failed allocation attempt.
+ * @returns {boolean}
+ */
+function should_skip_compound_probe_after_failure(block_list)
+{
+    if (!Cargo_Profile.obligate_block_allocation_first())
+    {
+        return false
+    }
+    return block_list.some(block => block.get_slot_list().length > 1)
+}
+
+module.exports = { should_skip_compound_probe_after_failure }

package/src/allocation_flow/container_remaining_capacity.js

@@ -0,0 +1,23 @@
+const compact_items_with_stock = require('../tools/compact_items_with_stock')
+const math = require('@jetta/number-compare')
+
+/**
+ * @param {object[]} item_list
+ * @param {object} container
+ * @returns {{ item_list: object[], has_capacity: boolean }}
+ */
+function remaining_items_fit_container(item_list, container)
+{
+    const compacted_list = compact_items_with_stock(item_list)
+    const has_items = compacted_list.length > 0
+    const has_space = container.has_space(compacted_list)
+    const has_weight = compacted_list.some(
+        item => math.le(item.get_weight(), container.supported_weight())
+    )
+    return {
+        item_list: compacted_list,
+        has_capacity: has_items && has_space && has_weight
+    }
+}
+
+module.exports = { remaining_items_fit_container }

package/src/allocation_flow/density_group_item_filter.js

@@ -0,0 +1,31 @@
+/**
+ * Applies the active density group filter to the effective item list.
+ * @param {object|null} density_scheduler
+ * @param {object[]} master_item_list
+ * @param {object[]} effective_item_list
+ * @param {object|null} locked_item
+ * @returns {object[]}
+ */
+function apply_density_group_item_filter(density_scheduler, master_item_list, effective_item_list, locked_item)
+{
+    if (!density_scheduler || locked_item)
+    {
+        return effective_item_list
+    }
+
+    const filtered = density_scheduler.filter_item_list(effective_item_list)
+    if (filtered.length > 0)
+    {
+        return filtered
+    }
+
+    const has_stock = density_scheduler.skip_empty_groups(master_item_list)
+    if (!has_stock)
+    {
+        return []
+    }
+
+    return density_scheduler.filter_item_list(effective_item_list)
+}
+
+module.exports = { apply_density_group_item_filter }

package/src/allocation_flow/effective_item_fingerprint.js

@@ -0,0 +1,14 @@
+/**
+ * Builds a stable fingerprint from the effective item list used by the chooser and LP.
+ * @param {object[]} effective_item_list - Items exposed to the current allocation iteration.
+ * @returns {string} Sorted `id:amount` pairs joined by `|`, e.g. `3:12|7:4`.
+ */
+function build_effective_item_fingerprint(effective_item_list)
+{
+    const pairs = effective_item_list
+        .map(item => `${item.get_id()}:${item.get_amount()}`)
+        .sort()
+    return pairs.join('|')
+}
+
+module.exports = { build_effective_item_fingerprint }

package/src/allocation_flow/item_continuation_lock_gate.js

@@ -0,0 +1,38 @@
+const Cargo_Profile = require('../models/Cargo_Profile')
+
+/**
+ * Clears the hard SKU lock when the continuation-lock feature flag is off.
+ * @param {object} context
+ * @param {object|null} locked_item
+ * @returns {object|null}
+ */
+function apply_item_continuation_lock_gate(context, locked_item)
+{
+    if (Cargo_Profile.enable_item_continuation_lock())
+    {
+        return locked_item
+    }
+    context.item_lock.release_for_density_balance()
+    return null
+}
+
+/**
+ * Updates or clears the continuation lock after a wall, honoring the feature flag.
+ * @param {object} context
+ * @param {Set<string>} single_slot_allocated_item_ids
+ * @returns {void}
+ */
+function update_item_continuation_lock(context, single_slot_allocated_item_ids)
+{
+    if (!Cargo_Profile.enable_item_continuation_lock())
+    {
+        context.item_lock.release_for_density_balance()
+        return
+    }
+    context.item_lock.update_from_iteration(single_slot_allocated_item_ids)
+}
+
+module.exports = {
+    apply_item_continuation_lock_gate,
+    update_item_continuation_lock
+}

package/src/allocation_flow/no_space_left_recovery.js

@@ -0,0 +1,48 @@
+/**
+ * @param {number|null|undefined} group_count - Density group count when scheduler is active.
+ * @param {boolean} compound_fallback_engaged - True after compound-first probe is skipped.
+ * @returns {number}
+ */
+function compute_max_no_space_left_recoveries(group_count, compound_fallback_engaged)
+{
+    const base = group_count ?? 1
+    if (compound_fallback_engaged)
+    {
+        return base * 2
+    }
+    return base
+}
+
+/**
+ * @param {{ obligate_compound_session: { skip_compound_probe: boolean } }} chooser_session
+ * @returns {boolean}
+ */
+function is_compound_fallback_engaged(chooser_session)
+{
+    return chooser_session.obligate_compound_session.skip_compound_probe === true
+}
+
+/**
+ * Resets skip state and enables legacy block resolution for subsequent chooser calls.
+ * @param {object} params
+ * @param {import('./space_skip_state')} params.space_skip_state
+ * @param {object} params.chooser_session
+ * @param {object|null} params.density_scheduler
+ * @param {object|null} params.locked_item
+ * @returns {void}
+ */
+function apply_no_space_left_recovery(params)
+{
+    params.space_skip_state.clear_stalls()
+    params.chooser_session.obligate_compound_session.skip_compound_probe = true
+    if (params.density_scheduler && !params.locked_item)
+    {
+        params.density_scheduler.advance_after_successful_wall()
+    }
+}
+
+module.exports = {
+    compute_max_no_space_left_recoveries,
+    is_compound_fallback_engaged,
+    apply_no_space_left_recovery
+}