@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/models/transport/Container.js

@@ -0,0 +1,162 @@
+const { Space, EmptySpaceFinder } = require('@jetta/empty-spaces-manager')
+const create_input = require('../../Allocation_Optimization/block_builder/Stacking_Validation')
+const items_for_empty_space_finder = require('./items_for_empty_space_finder')
+const {
+    define_stacking_cell_size,
+    build_stacking_feasibility_checker
+} = require('./build_stacking_feasibility_checker')
+const {
+    ensure_stacking_checkpoint,
+    restore_stacking_checker_after_discard
+} = require('./container_stacking_checkpoint')
+const { traced_step_sync } = require('../../tracing/traced_step')
+const { TRACE_CONTEXT } = require('../../tracing/Trace_Context')
+
+/**
+ * @typedef {object} Container_Constructor_Data
+ * @property {string} id - Identifier associated with this physical container (often transport `_id`).
+ * @property {number} width - Interior width.
+ * @property {number} height - Interior height.
+ * @property {number} length - Interior length.
+ * @property {number} supported_weight - Maximum cargo weight the container may carry.
+ * @property {Array<object>} allocated_item_list - Already placed items; may be empty.
+ * @property {Array<object>} corner_casting_list - Corner castings passed to {@link EmptySpaceFinder}.
+ * @property {object|undefined} empty_space_finder_options - Optional `{ merge_tolerance }` (width=X, length=Z, vertical in domain units).
+ * @property {object[]|undefined} preloaded_stacking_inputs - Wire-derived stacking DTOs for preloaded cargo.
+ */
+
+/**
+ * Shipping container as a {@link Space} with empty-space tracking and weight capacity.
+ */
+class Container extends Space
+{
+    #id
+    #allocated_item_list = []
+    #supported_weight_limit
+    #stacking_feasibility_checker
+    #stacking_cell_size
+    #stacking_checkpoint = null
+
+    /**
+     * @param {Container_Constructor_Data} data - Geometry, capacity, corner castings, and pre-loaded items.
+     * Pre-loaded items with the same `groupId` are collapsed to one bounding box for empty-space initialization.
+     */
+    constructor(data)
+    {
+        super({ x: 0, y: 0, z: 0, width: data.width, height: data.height, length: data.length })
+        this.#id = data.id
+        this.#supported_weight_limit = data.supported_weight
+        this.finder = new EmptySpaceFinder(
+            this,
+            data.corner_casting_list,
+            data.empty_space_finder_options
+        )
+        this.find_empty_spaces(items_for_empty_space_finder(data.allocated_item_list))
+        this.merge_item_list(data.allocated_item_list)
+        this.#stacking_cell_size = define_stacking_cell_size(this, data.item_list)
+        this.#stacking_feasibility_checker = build_stacking_feasibility_checker({
+            cell_size: this.#stacking_cell_size,
+            preloaded_stacking_inputs: data.preloaded_stacking_inputs,
+            allocated_item_list: data.allocated_item_list
+        })
+    }
+
+    supported_weight()
+    {
+        if (this.#allocated_item_list.length === 0)
+        {
+            return this.#supported_weight_limit
+        }
+        const loaded_weight = this.#allocated_item_list.reduce((sum, cur) => sum + cur.get_weight(), 0)
+        return this.#supported_weight_limit - loaded_weight
+    }
+
+    /**
+     * Validates stacking. On success, `@jetta/stacking-constraints` commits the candidate into the index.
+     * Call {@link discard_provisional_stackings} if the wall/attempt that used this check is aborted.
+     * @param {object} item - Allocated item (or compatible) to validate.
+     * @returns {boolean}
+     */
+    is_a_valid_stacking(item)
+    {
+        this.#stacking_checkpoint = ensure_stacking_checkpoint(
+            this.#stacking_checkpoint,
+            this.#stacking_feasibility_checker
+        )
+        const item_data = create_input(item)
+        return this.#stacking_feasibility_checker.validate_stackings(item_data)
+    }
+
+    /**
+     * Drops provisional stacking commits left by failed slot/wall attempts.
+     * Restores the pre-attempt checkpoint when stacking was touched; otherwise a no-op.
+     * @returns {void}
+     */
+    discard_provisional_stackings()
+    {
+        const restored = restore_stacking_checker_after_discard(
+            this.#stacking_checkpoint,
+            this.#stacking_feasibility_checker
+        )
+        this.#stacking_feasibility_checker = restored.checker
+        this.#stacking_checkpoint = restored.checkpoint
+    }
+
+
+    /**
+     * Registers an allocated item in the stacking index (used by loose-on-block finalize).
+     * @param {object} item
+     * @returns {boolean}
+     */
+    commit_allocated_item_for_stacking(item)
+    {
+        this.#stacking_checkpoint = ensure_stacking_checkpoint(
+            this.#stacking_checkpoint,
+            this.#stacking_feasibility_checker
+        )
+        return this.#stacking_feasibility_checker.validate_stackings(create_input(item))
+    }
+
+    merge_item_list(item_list)
+    {
+        this.#allocated_item_list.push(...item_list)
+        this.#stacking_checkpoint = null
+    }
+
+    find_empty_spaces(item_list)
+    {
+        traced_step_sync(TRACE_CONTEXT.MAP_EMPTY_SPACES, () =>
+        {
+            this.finder.allocate_item_list(item_list)
+        })
+    }
+
+    add_item(item)
+    {
+        this.#allocated_item_list.push(item)
+        this.finder.allocate_item(item)
+        this.#stacking_checkpoint = null
+    }
+
+    empty_spaces()
+    {
+        return this.finder.empty_spaces()
+    }
+
+    has_space(items)
+    {
+        return items.some(item => this.fits_rotated_item(item))
+    }
+
+    get_id()
+    {
+        return this.#id
+    }
+
+    get_allocated_items()
+    {
+        return this.#allocated_item_list
+    }
+}
+
+module.exports = Container

package/src/models/transport/Transport.js

@@ -0,0 +1,62 @@
+const create_container_map = require('./factory/Container_Factory')
+
+/**
+ * In-memory representation of one transport environment: a map of sequence → container model.
+ */
+class Transport
+{
+    #containers = new Map()
+    /**
+     * @param {object} transport_data - First element shape from `input_data.envs` (includes `containers` array).
+     * @param {object|undefined} empty_space_finder_options - Optional merge tolerance for each {@link Container} finder.
+     */
+    constructor(data)
+    {
+        this.#containers = create_container_map(data)
+    }
+
+    /**
+     * @returns {Map<number, object>} Container instances keyed by `sequencia`.
+     */
+    get_containers()
+    {
+        return this.#containers
+    }
+
+    /**
+     * @returns {number} Number of containers in this transport.
+     */
+    container_amount()
+    {
+        return this.#containers.size
+    }
+
+    /**
+     * @param {number} sequence - Container `sequencia` from input data.
+     * @returns {object} The matching container instance.
+     * @throws {Error} When no container exists for the sequence.
+     */
+    get_container_by_sequence(sequence)
+    {
+        if (this.#containers.has(sequence))
+        {
+            return this.#containers.get(sequence)
+        }
+        throw new Error('there is no container with sequence ' + sequence)
+    }
+
+    /**
+     * Sorted list of container sequences (ascending).
+     * @returns {number[]}
+     */
+    get_container_sequence_list()
+    {
+        const keys   = Array.from(this.#containers.keys())
+        const sorted = keys.sort((a, b) => a - b)
+        return sorted
+    }
+
+
+}
+
+module.exports = Transport

package/src/models/transport/build_stacking_feasibility_checker.js

@@ -0,0 +1,64 @@
+const { StackingFeasibilityChecker } = require('@jetta/stacking-constraints')
+const create_input = require('../../Allocation_Optimization/block_builder/Stacking_Validation')
+const resolve_container_stacking_inputs = require('./resolve_container_stacking_inputs')
+
+/**
+ * Resolves uniform grid cell size from cargo item footprints, else container plan dimensions.
+ * @param {object} container_space - Space with get_width() and get_length().
+ * @param {object[]|undefined} item_list - Items exposing get_width() and get_length().
+ * @returns {number}
+ */
+function define_stacking_cell_size(container_space, item_list)
+{
+    const list = item_list ?? []
+    if (list.length === 0)
+    {
+        return Math.max(container_space.get_width(), container_space.get_length())
+    }
+    const widths = list.map(item => item.get_width())
+    const lengths = list.map(item => item.get_length())
+    return Math.max(...widths, ...lengths)
+}
+
+/**
+ * Builds the stacking index from wire DTOs or allocated items.
+ * @param {object} data - Constructor bag plus resolved cell size.
+ * @param {number} data.cell_size - Fallback cell size when no allocated stacking inputs exist.
+ * @param {object[]|undefined} data.preloaded_stacking_inputs - Wire-derived stacking DTOs.
+ * @param {object[]} data.allocated_item_list - Committed allocated items.
+ * @returns {StackingFeasibilityChecker}
+ */
+function build_stacking_feasibility_checker(data)
+{
+    const stacking_inputs = resolve_container_stacking_inputs(
+        data.preloaded_stacking_inputs,
+        data.allocated_item_list
+    )
+    if (stacking_inputs.length === 0)
+    {
+        return new StackingFeasibilityChecker(data.cell_size)
+    }
+    return StackingFeasibilityChecker.from_allocated(stacking_inputs)
+}
+
+/**
+ * Rebuilds the stacking index from committed allocated items only (drops provisional validates).
+ * @param {object[]} allocated_item_list - Items already committed on the container.
+ * @param {number} cell_size - Cell size used when the list is empty.
+ * @returns {StackingFeasibilityChecker}
+ */
+function stacking_checker_from_allocated_items(allocated_item_list, cell_size)
+{
+    if (allocated_item_list.length === 0)
+    {
+        return new StackingFeasibilityChecker(cell_size)
+    }
+    const stacking_inputs = allocated_item_list.map(allocated => create_input(allocated))
+    return StackingFeasibilityChecker.from_allocated(stacking_inputs)
+}
+
+module.exports = {
+    define_stacking_cell_size,
+    build_stacking_feasibility_checker,
+    stacking_checker_from_allocated_items
+}

package/src/models/transport/container_stacking_checkpoint.js

@@ -0,0 +1,42 @@
+/**
+ * Lazy stacking-index checkpoint helpers for cheap provisional discard.
+ * Baseline is a structural clone taken before the first validate of an attempt.
+ */
+
+/**
+ * @param {object|null} stacking_checkpoint - Prior baseline clone, if any.
+ * @param {object} stacking_feasibility_checker - Live checker to snapshot.
+ * @returns {object} Existing or newly cloned baseline
+ */
+function ensure_stacking_checkpoint(stacking_checkpoint, stacking_feasibility_checker)
+{
+    if (stacking_checkpoint != null)
+    {
+        return stacking_checkpoint
+    }
+    return stacking_feasibility_checker.clone()
+}
+
+/**
+ * Restores the live checker from a checkpoint when provisionals may exist.
+ * If there is no checkpoint, stacking was not mutated — return the live checker unchanged.
+ * @param {object|null} stacking_checkpoint - Baseline for this attempt, if any.
+ * @param {object} stacking_feasibility_checker - Current live checker.
+ * @returns {{ checker: object, checkpoint: null }}
+ */
+function restore_stacking_checker_after_discard(
+    stacking_checkpoint,
+    stacking_feasibility_checker
+)
+{
+    if (stacking_checkpoint != null)
+    {
+        return { checker: stacking_checkpoint, checkpoint: null }
+    }
+    return { checker: stacking_feasibility_checker, checkpoint: null }
+}
+
+module.exports = {
+    ensure_stacking_checkpoint,
+    restore_stacking_checker_after_discard
+}

package/src/models/transport/factory/Container_Factory.js

@@ -0,0 +1,46 @@
+const create_allocated_item_list = require('./Previously_Allocated_Item_Factory')
+const create_corner_castings = require('./Corner_Casting_Factory')
+const Container = require('../Container')
+const { build_stacking_inputs_from_wire_list } = require('../stacking_input_from_wire')
+
+function create_container_data(data)
+{
+    const {transport_data, container_data, empty_space_finder_options, item_list}  = data
+    const allocated_item_list = create_allocated_item_list(container_data.items)
+    const preloaded_stacking_inputs = build_stacking_inputs_from_wire_list(container_data.items ?? [])
+    const corner_casting_list = create_corner_castings(transport_data, container_data)
+    return new Container({
+        id: transport_data._id,
+        width: container_data.largura,
+        height: container_data.altura,
+        length: container_data.comprimento,
+        supported_weight: container_data.pesoDeCarga,
+        allocated_item_list: allocated_item_list,
+        preloaded_stacking_inputs,
+        corner_casting_list,
+        empty_space_finder_options,
+        item_list
+    })
+}
+
+/**
+ * Builds a `Map` of container `sequencia` to constructed container instances for one transport env.
+ * Call after request validation so `container_data_list` is a non-empty array.
+ * @param {object} transport_data - Raw transport/env object (`_id`, `tipo`, `props`, etc.).
+ * @param {object[]} container_data_list - Elements of `transport_data.containers`.
+ * @param {object|undefined} empty_space_finder_options - Optional `{ merge_tolerance }` for {@link EmptySpaceFinder}.
+ * @returns {Map<number, object>}
+ */
+module.exports = function create_container_map(data)
+{
+    const container_map = new Map()
+
+    const { transport_data, empty_space_finder_options, item_list } = data
+    for (const container_data of transport_data.containers)
+    {
+        const container = create_container_data({transport_data, container_data, empty_space_finder_options, item_list})
+        container_map.set(container_data.sequencia, container)
+    }
+
+    return container_map
+}

package/src/models/transport/factory/Corner_Casting_Factory.js

@@ -0,0 +1,62 @@
+const {CornerCasting, Direction} = require('@jetta/empty-spaces-manager')
+
+const round = require('../../../tools/Rounder')
+
+function create_corner_casting_data_list(container, value, direction)
+{
+    const corner_casting_list = []
+
+    if (value <= 0)
+    {
+        return corner_casting_list
+    }
+
+    for (let index = 0; index < 2; index++)
+    {
+        const corner_casting_data = create_corner_casting_data(index, container, value, direction)
+        const corner_casting      = new CornerCasting(corner_casting_data, direction)
+        corner_casting_list.push(corner_casting)
+    }
+
+    return corner_casting_list
+}
+
+function create_corner_casting_data(index, container, value, direction)
+{
+    const x = index === 0 ? 0 : round(container.largura - value)
+    const y = round(container.altura - value)
+    const z = direction.toLowerCase() === Direction.FRONT ? 0 : round(container.comprimento - value)
+    const corner_casting_data = {x: x, y: y, z: z, w: value, h: value, l: value}
+
+    return corner_casting_data
+}
+
+/**
+ * Builds corner-casting geometry for the empty-space manager when transport is a container with props.
+ * @param {object} transport_data - Env root; must define string `tipo` and, when tipo is `container`, may define `props`.
+ * @param {object} container_data - Raw container row (`largura`, `altura`, `comprimento`).
+ * @returns {Array<object>} CornerCasting instances; empty when tipo is not `container` or `props` is missing.
+ * @throws {TypeError} When `transport_data.tipo` is not a string (e.g. missing).
+ */
+module.exports = function create_all_corner_castings(transport_data, container_data)
+{
+    if (transport_data.tipo.toLowerCase() !== 'container' || transport_data.props === undefined)
+    {
+        return []
+    }
+
+    const corner_castings_data = transport_data.props
+
+    const front_casting = create_corner_casting_data_list(
+        container_data,
+        corner_castings_data.espacoSuperiorFrente,
+        Direction.FRONT
+    )
+    const back_casting  = create_corner_casting_data_list(
+        container_data,
+        corner_castings_data.espacoSuperiorPorta,
+        Direction.BACK
+    )
+
+    return [...front_casting, ...back_casting]
+}

package/src/models/transport/factory/Previously_Allocated_Item_Factory.js

@@ -0,0 +1,28 @@
+const Allocated_Item = require('../../Allocated_Item')
+const Preloaded_Allocated_Item = require('../../Preloaded_Allocated_Item')
+
+/**
+ * Converts raw `items` from a container payload into allocated item instances for the finder.
+ * @param {object[]|undefined} allocated_item_list - `container_data.items` from input JSON.
+ * @returns {Array<object>} Empty array when input is missing or not an array; otherwise allocated items.
+ */
+module.exports = function create_previously_allocated_item_list(allocated_item_list)
+{
+    if (allocated_item_list === undefined || !Array.isArray(allocated_item_list))
+    {
+        return []
+    }
+
+    return allocated_item_list.map(create_previously_allocated_item)
+}
+
+function create_previously_allocated_item(item_data)
+{
+    const allocation_item = new Preloaded_Allocated_Item(item_data)
+    return new Allocated_Item(
+        allocation_item,
+        allocation_item.get_x(),
+        allocation_item.get_y(),
+        allocation_item.get_z()
+    )
+}

package/src/models/transport/factory/Transport_Factory.js

@@ -0,0 +1,13 @@
+const Transport = require('../Transport')
+
+/**
+ * Selects the first transport definition from `envs` and returns a ready transport instance.
+ * Call after `parse_allocation_request` (or equivalent) so `transport_data_list` is non-empty.
+ * @param {object[]} transport_data_list - Typically `input_data.envs`.
+ * @param {object|undefined} empty_space_finder_options - Optional `{ merge_tolerance }` for {@link EmptySpaceFinder}.
+ * @returns {object} Transport model built from `transport_data_list[0]`.
+ */
+module.exports = function create_transport(data)
+{
+    return new Transport(data)
+}

package/src/models/transport/items_for_empty_space_finder.js

@@ -0,0 +1,91 @@
+const { Space } = require('@jetta/empty-spaces-manager')
+
+function has_group_id(group_id)
+{
+    return group_id !== undefined && group_id !== null
+}
+
+function group_key(item, index)
+{
+    const group_id = item.get_group_id()
+    if (!has_group_id(group_id))
+    {
+        return `__no_group_${index}`
+    }
+    return group_id
+}
+
+function group_items_by_group_id(allocated_item_list)
+{
+    const groups = new Map()
+    allocated_item_list.forEach((item, index) =>
+    {
+        const key = group_key(item, index)
+        if (!groups.has(key))
+        {
+            groups.set(key, [])
+        }
+        groups.get(key).push(item)
+    })
+    return groups
+}
+
+function bounding_box_space_from_items(item_list)
+{
+    let min_x = Infinity
+    let min_y = Infinity
+    let min_z = Infinity
+    let max_x = -Infinity
+    let max_y = -Infinity
+    let max_z = -Infinity
+    for (const item of item_list)
+    {
+        min_x = Math.min(min_x, item.get_x())
+        min_y = Math.min(min_y, item.get_y())
+        min_z = Math.min(min_z, item.get_z())
+        const end_point = item.get_end_point()
+        max_x = Math.max(max_x, end_point.x)
+        max_y = Math.max(max_y, end_point.y)
+        max_z = Math.max(max_z, end_point.z)
+    }
+    return new Space({
+        x: min_x,
+        y: min_y,
+        z: min_z,
+        width: max_x - min_x,
+        height: max_y - min_y,
+        length: max_z - min_z
+    })
+}
+
+function item_or_bounding_box_for_group(item_list)
+{
+    if (item_list.length === 1)
+    {
+        return item_list[0]
+    }
+    return bounding_box_space_from_items(item_list)
+}
+
+/**
+ * Builds the item list passed to {@link EmptySpaceFinder}: one entry per block group
+ * (bounding box when multiple slots share a groupId), or each item when groupId is absent.
+ * @param {Array<object>} allocated_item_list - Pre-placed allocated items.
+ * @returns {Array<object>} Items for empty-space subtraction.
+ */
+function items_for_empty_space_finder(allocated_item_list)
+{
+    if (allocated_item_list.length === 0)
+    {
+        return []
+    }
+    const groups = group_items_by_group_id(allocated_item_list)
+    const finder_items = []
+    for (const item_list of groups.values())
+    {
+        finder_items.push(item_or_bounding_box_for_group(item_list))
+    }
+    return finder_items
+}
+
+module.exports = items_for_empty_space_finder

package/src/models/transport/resolve_container_stacking_inputs.js

@@ -0,0 +1,23 @@
+const create_input = require('../../Allocation_Optimization/block_builder/Stacking_Validation')
+
+/**
+ * Prefers wire-derived stacking DTOs; falls back to allocated items for direct {@link Container} construction.
+ * @param {object[]|undefined} preloaded_stacking_inputs - Wire-derived DTOs from the factory path.
+ * @param {object[]|undefined} allocated_item_list - Allocated items when wire DTOs are absent.
+ * @returns {object[]}
+ */
+function resolve_container_stacking_inputs(preloaded_stacking_inputs, allocated_item_list)
+{
+    const wire_inputs = preloaded_stacking_inputs ?? []
+    if (wire_inputs.length > 0)
+    {
+        return wire_inputs
+    }
+    if (allocated_item_list === undefined || allocated_item_list.length === 0)
+    {
+        return []
+    }
+    return allocated_item_list.map(allocated => create_input(allocated))
+}
+
+module.exports = resolve_container_stacking_inputs

package/src/models/transport/stacking_input_from_wire.js

@@ -0,0 +1,58 @@
+const {
+    build_placed_item_record,
+    build_stacking_info,
+    read_placed_position
+} = require('../placed_item_record')
+const { build_stacking_rules_from_info } = require(
+    '../../Allocation_Optimization/block_builder/stacking_rules_input'
+)
+
+function read_wire_dimensions(wire_item)
+{
+    return {
+        width: wire_item.w ?? wire_item.largura ?? wire_item.width,
+        height: wire_item.h ?? wire_item.altura ?? wire_item.height,
+        length: wire_item.d ?? wire_item.comprimento ?? wire_item.length
+    }
+}
+
+/**
+ * Builds a {@link StackingFeasibilityChecker} input DTO from a raw placed item wire payload.
+ * @param {object} wire_item - Element of `container.items`.
+ * @returns {object}
+ */
+function build_stacking_input_from_wire(wire_item)
+{
+    const record = build_placed_item_record(wire_item)
+    const stacking_info = build_stacking_info(wire_item)
+    const position = read_placed_position(wire_item)
+    const dimensions = read_wire_dimensions(wire_item)
+    return {
+        itemId: record._id,
+        x: position.x,
+        y: position.y,
+        z: position.z,
+        width: dimensions.width,
+        height: dimensions.height,
+        length: dimensions.length,
+        stackingRules: build_stacking_rules_from_info(stacking_info, record)
+    }
+}
+
+/**
+ * @param {object[]} wire_list - Raw `container.items` entries.
+ * @returns {object[]}
+ */
+function build_stacking_inputs_from_wire_list(wire_list)
+{
+    if (!Array.isArray(wire_list) || wire_list.length === 0)
+    {
+        return []
+    }
+    return wire_list.map(build_stacking_input_from_wire)
+}
+
+module.exports = {
+    build_stacking_input_from_wire,
+    build_stacking_inputs_from_wire_list
+}