@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @jetta/blocks-allocator
+
+Library that allocates items into pre-assembled block structures. Queue and Temporal communication live in `blocks-wall-allocation`. This package exposes `run_core_allocation`.
+
+## Requirements
+
+- Node.js 24+
+- npm
+- A reachable optimizer for live allocation (`NATS_SERVERS`). Tests mock the optimizer in process.
+
+## How to install
+
+```bash
+npm install @jetta/blocks-allocator
+```
+
+Local development:
+
+```bash
+npm install
+```
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm test` | Mocha tests |
+| `npm run lint` | ESLint |
+| `npm run lint:package` | publint strict check of the packed tarball |
+
+## Usage
+
+```js
+const run_core_allocation = require('@jetta/blocks-allocator')
+
+const output = await run_core_allocation(request, {
+    object_store: {
+        get_object(bucket_name, object_key)
+        {
+            return object_store_driver.get_object(bucket_name, object_key)
+        }
+    },
+    tracer
+})
+```
+
+`object_store` is required only when manual blocks are enabled. `tracer` is optional. Without it, allocation still runs and tracing steps are skipped.
+
+`run_core_allocation.resolve_trace_id(request)` resolves the id the service should pass to its tracer.
+
+## Dependencies
+
+Algorithm libraries: `@jetta/lp-framework`, `@jetta/empty-spaces-manager`, `@jetta/number-compare`, `@jetta/stacking-constraints`, the block-creator packages, `@jettacargo/stackability-index-calculator-core@1.0.4`, `@jetta/item-amount-controller`, and `zod`.
+
+## Env Variables
+
+`NATS_SERVERS` : NATS URL(s) for optimizer request-reply (required for a live run)
+`OPTIMIZER_NATS_SUBJECT` : subject (default `optimizer.optimize`; dig uses `optimizer.dev.optimize`)
+`OPTIMIZER_NATS_TIMEOUT_MS` : request timeout ms (default 300000; covers dig scale-from-zero)
+`MANUAL_BLOCKS_BUCKET_NAME` : bucket passed to `object_store.get_object` when manual blocks are loaded
+
+## External Dependencies
+- optimizer NATS worker (`python-optimizer-nats-{ENV}`) + JetStream stream/consumer
+- NATS: `nats://nats.nats.svc.cluster.local:4222`
+
+## Supported Cargo Profile Options
+- allocation.blocks.use_unitary_items_as_block
+    - enable the use of individual items as a possible blocks
+    - deafult: false
+- allocation.optimization.enable_blocks_extra_score
+    - gives a extra score to non individual item blocks on LP optimization
+    - deafult: false
+- allocation.optimization.measure_to_optimize
+    - "width" of "length", used to set which dimension is optimized
+    - deafult: "width"
+- allocation.stacking.enable_stacking_constraints_service
+    - enables stacking rules
+    - deafult: true
+- allocation.empty_space.chooser.score_strategy_criterias
+    - empty space chooser score criterias
+- allocation.empty_space.chooser.enable_full_containes_removal
+    - when enabled, the chooser will disconsider all sub containers that is fully contained in other
+
+## Empty-space merge tolerance (optional `config.algoritmo`)
+
+Optional keys on `config.algoritmo` (validated at parse time), alongside other cargo profile keys. In the empty-space model, **width** is axis **X** and **length** is axis **Z** (same as `Space.width` / `Space.length` in `@jetta/empty-spaces-manager`).
+
+- `empty_space_merge_gap_percent_width` (0–100): max horizontal merge gap along **width** (X), as a percent of the smallest item **width** over all rotations.
+- `empty_space_merge_gap_percent_length` (0–100): same for **length** (Z).
+- `empty_space_merge_max_vertical_offset_mm` (≥ 0): max vertical gap in **millimeters** for merging stacked empty regions with overlapping floor projection; absent or `0` disables this merge. Internal geometry uses the same numeric unit as container/item dimensions (typically mm), so the value is rounded into that domain.
+
+Omit the keys or set them to `0` for the previous strict merge behavior.
+
+The same spacing rules are implemented in `@jetta/empty-spaces-manager` as pure APIs (`merge_tolerance_from_operational_gaps`, `horizontal_epsilon_from_gap_percent`) so any allocator can pass **numbers only** (`OperationalMergeGaps` + `RotationMinExtents`) without duplicating formulas.
+
+## Fluxos do agente
+
+Notas de feature em [.cursor/ai_changelog/INDEX.md](.cursor/ai_changelog/INDEX.md).
+
+| Invocação | Skill | Saída |
+|-----------|-------|-------|
+| `KB: JET-XXXX` | `document-feature-knowledge` | Doc em `.cursor/ai_changelog/` |
+| `PR: JET-XXXX` | `create-pr-description` | Rascunho de título e corpo de PR (chat) |

package/package.json

@@ -1,6 +1,68 @@
 {
-  "name": "@jetta/blocks-allocator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@jetta/blocks-allocator",
+    "version": "0.1.0",
+    "description": "Blocks wall allocation library",
+    "main": "src/index.js",
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "files": [
+        "src"
+    ],
+    "private": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "audit": "npm audit --omit=dev",
+        "preversion": "git fetch --prune --tags",
+        "version": "npm run lint && npm run lint:package",
+        "prepack": "npm run lint && npm run lint:package",
+        "postversion": "git push origin HEAD --follow-tags",
+        "publish:alpha": "npm version --tag-version-prefix=alpha-v",
+        "publish:stable": "npm version",
+        "prerelease:alpha": "npm version prerelease --tag-version-prefix=alpha-v",
+        "prerelease:alpha:minor": "npm version preminor --tag-version-prefix=alpha-v",
+        "prerelease:alpha:major": "npm version premajor --tag-version-prefix=alpha-v",
+        "test": "npx mocha --require test/mocha_setup.js --recursive 2>&1",
+        "test:verbose": "npx mocha --require test/mocha_setup_verbose.js --recursive 2>&1",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "lint:package": "publint --strict --pack npm",
+        "memory:profile": "node debug/memory_profile.js",
+        "generate:block-modules-goldens": "node scripts/generate_block_modules_compatibility_goldens.js",
+        "perf": "node scripts/allocation_perf_runner.js"
+    },
+    "type": "commonjs",
+    "engines": {
+        "node": ">=24"
+    },
+    "author": "",
+    "license": "ISC",
+    "dependencies": {
+        "@jetta/empty-spaces-manager": "^0.1.1-0",
+        "@jetta/item-amount-controller": "0.1.0-0",
+        "@jetta/logger": "^2.0.1",
+        "@jetta/lp-framework": "2.1.0-6",
+        "@jetta/number-compare": "^3.0.2-4",
+        "@jetta/stacking-constraints": "^1.1.0",
+        "@jetta/tie-ratio-block-creator-core": "1.2.2-3",
+        "@jetta/z-intersected-block-creator": "^0.0.1-42",
+        "@jettacargo/single-item-block-creator-core": "2.0.1-0",
+        "@jettacargo/spiral-block-creator-core": "2.1.2",
+        "@jettacargo/stackability-index-calculator-core": "1.0.4",
+        "@jettacargo/tower-block-creator-core": "3.0.0-3",
+        "zod": "^4.4.3"
+    },
+    "devDependencies": {
+        "chai": "^6.2.2",
+        "chai-as-promised": "^8.0.2",
+        "dotenv": "^17.4.2",
+        "eslint": "^10.3.0",
+        "eslint-plugin-promise": "^7.3.0",
+        "mocha": "^11.7.5",
+        "proxyquire": "^2.1.3",
+        "publint": "^0.3.25",
+        "sinon": "^22.0.0"
+    }
+}

package/src/Allocation_Attempt.js

@@ -0,0 +1,135 @@
+const { Item_Amount_Controller } = require('@jetta/item-amount-controller')
+const compact_items_with_stock = require('./tools/compact_items_with_stock')
+const { handle_attempt_exception } = require('./Allocation_Error_Handler')
+const Block_Allocator = require('./Allocation_Optimization/Block_Allocator')
+const {Logger} = require('@jetta/logger')
+const logger = new Logger('Allocation Attempt')
+const { mark_trace_outcome } = require('./tracing/trace_outcome')
+const { TRACE_CONTEXT } = require('./tracing/Trace_Context')
+
+function empty_wall_output()
+{
+    return {
+        single_slot_allocated_item_ids: new Set(),
+        last_allocated_item_id: null,
+        placed_tie_ratio_block: false
+    }
+}
+
+class Allocation_Attempt
+{
+    #attempt_id = 0
+    #item_list
+    #amount_controller
+    #allocator
+
+    constructor(input_state)
+    {
+        this.#item_list  = input_state.items_to_allocate
+        this.#amount_controller  = new Item_Amount_Controller(input_state.items_to_allocate)
+        this.#allocator          = new Block_Allocator()
+    }
+
+    /**
+     * Attempts allocation on the chosen space, retrying with reduced block options on recoverable failures.
+     * @param {object[]} block_list - Candidate blocks for the chosen space.
+     * @param {object} space_to_allocate - Empty space selected by the chooser.
+     * @param {Record<string, number>} block_amount_map - Block amount restrictions updated on failures.
+     * @param {object} container - Current transport container.
+     * @param {object[]} effective_item_list - Items exposed to the LP for this iteration.
+     * @param {string|null} picking_continuity_seed - Last allocated SKU id from the prior wall.
+     * @returns {Promise<object>} Wall output ids for continuation hooks.
+     */
+    async try_to_allocate(
+        block_list,
+        space_to_allocate,
+        block_amount_map,
+        container,
+        effective_item_list,
+        picking_continuity_seed
+    )
+    {
+        let wall_output = empty_wall_output()
+        while (block_list.length > 0)
+        {
+            try
+            {
+                wall_output = await this.#allocation_attempt(
+                    container,
+                    space_to_allocate,
+                    block_list,
+                    block_amount_map,
+                    effective_item_list,
+                    picking_continuity_seed
+                )
+                break
+            }
+            catch (exception)
+            {
+                container.discard_provisional_stackings()
+                const keep_trying = handle_attempt_exception(exception, block_list, block_amount_map)
+                if (!keep_trying)
+                {
+                    break
+                }
+            }
+        }
+        return wall_output
+    }
+
+    #update_item_amount(allocated_items)
+    {
+        this.#amount_controller.discount_item_list( allocated_items )
+        this.#amount_controller.update_item_list_amount( this.#item_list )
+        this.#item_list = compact_items_with_stock(this.#item_list)
+    }
+
+    async #allocation_attempt(
+        container,
+        space_to_allocate,
+        avaiable_usable_blocks,
+        block_amount_map,
+        effective_item_list,
+        picking_continuity_seed
+    )
+    {
+        const attempt = this.#attempt_id++
+        logger.debug('allocation attempt ' + attempt)
+        const allocation_output = await this.#allocator.optimize_and_allocate(
+            container,
+            space_to_allocate,
+            avaiable_usable_blocks,
+            this.#amount_controller,
+            this.#item_list,
+            block_amount_map,
+            effective_item_list,
+            picking_continuity_seed
+        )
+        this.#update_state(container, allocation_output)
+        mark_trace_outcome(TRACE_CONTEXT.BLOCK_WALL_ALLOCATED)
+        logger.debug('wall allocated, going to the next wall...')
+        return {
+            single_slot_allocated_item_ids: allocation_output.single_slot_allocated_item_ids ?? new Set(),
+            last_allocated_item_id: allocation_output.last_allocated_item_id ?? null,
+            placed_tie_ratio_block: allocation_output.placed_tie_ratio_block ?? false
+        }
+    }
+
+    #update_state(container, allocation_output)
+    {
+        container.find_empty_spaces(allocation_output.item_to_find_space_list)
+        const existing_items = new Set(container.get_allocated_items())
+        const items_to_merge = allocation_output.allocated_item_list.filter(
+            item => !existing_items.has(item)
+        )
+        container.merge_item_list(items_to_merge)
+        this.#update_item_amount(allocation_output.allocated_item_list)
+    }
+
+    get_attempt_id()
+    {
+        return this.#attempt_id
+    }
+}
+
+module.exports = Allocation_Attempt

package/src/Allocation_Error_Handler.js

@@ -0,0 +1,69 @@
+const {NoSpaceLeftException} = require('@jetta/empty-spaces-manager')
+const There_Is_No_Block_Options_To_Allocate_Exception = require('./exceptions/There_Is_No_Block_Options_To_Allocate_Exception')
+const Optimization_Infeasible_Exception = require('./Allocation_Optimization/exceptions/Optimization_Infeasible_Exception')
+const Restricted_Block_Exception = require('./Allocation_Optimization/block_builder/exceptions/Restricted_Block_Exception')
+const { restrict_block, clean_blocks_restricted_to_0 } = require('./Block_Management')
+const No_Valid_Allocation_Exception = require('./Allocation_Optimization/exceptions/No_Valid_Allocation_Exception')
+const Invalid_Stacking_Exception = require('./Allocation_Optimization/block_builder/exceptions/Invalid_Stacking_Exception')
+const {Logger} = require('@jetta/logger')
+const logger = new Logger('Allocation Attempt Error Handler')
+const { mark_trace_outcome } = require('./tracing/trace_outcome')
+const { TRACE_CONTEXT } = require('./tracing/Trace_Context')
+
+function handle_attempt_exception(exception, block_list, block_amount_restrictions)
+{
+    if (exception instanceof Invalid_Stacking_Exception)
+    {
+        return false
+    }
+
+    if (exception instanceof Restricted_Block_Exception)
+    {
+        restrict_block(exception, block_amount_restrictions)
+        clean_blocks_restricted_to_0(block_list, block_amount_restrictions)
+        logger.warn(JSON.stringify(exception.block_to_restrict))
+        const restricted_block_list = Object.keys(block_amount_restrictions)
+        const has_non_restricted_block = block_list.some(block => !restricted_block_list.includes(block.get_id()))
+        if (has_non_restricted_block)
+        {
+            mark_trace_outcome(TRACE_CONTEXT.BLOCK_WALL_RETRY_OTHER_BLOCKS)
+        }
+        return has_non_restricted_block
+    }
+
+    if (exception instanceof Optimization_Infeasible_Exception || exception instanceof No_Valid_Allocation_Exception)
+    {
+        logger.warn('Optimization_Infeasible_Exception')
+        return false // não tem mais o que fazer
+    }
+
+    logger.error(exception.message)
+    throw exception // erro inesperado, propaga
+}
+
+function handle_allocation_exception(exception, attempt_id)
+{
+    if (can_continue_allocation(exception))
+    {
+        logger.warn('choosen space can\'t fit any of the possible blocks => attempt id ' + attempt_id)
+        return true // ainda vamos tentar
+    }
+    if (exception instanceof NoSpaceLeftException)
+    {
+        logger.warn('no space left => attempt id ' + attempt_id)
+        mark_trace_outcome(TRACE_CONTEXT.BLOCK_WALL_SPACE_EXHAUSTED)
+        return false // não tem mais o que fazer
+    }
+    logger.error(exception.message)
+    throw exception // erro inesperado, propaga
+}
+
+function can_continue_allocation(error)
+{
+    const is_invalid_stacking = error instanceof Invalid_Stacking_Exception
+    const does_not_have_block_for_space = error instanceof There_Is_No_Block_Options_To_Allocate_Exception
+    return is_invalid_stacking || does_not_have_block_for_space
+}
+
+
+module.exports = {handle_attempt_exception,handle_allocation_exception}

package/src/Allocation_Flow.js

@@ -0,0 +1,162 @@
+const { handle_allocation_exception } = require('./Allocation_Error_Handler')
+const Allocation_Attempt = require('./Allocation_Attempt')
+const Preferential_Block_Identifier = require('./Allocation_Optimization/preferential_blocks/Preferential_Block_Identifier')
+const Item_Continuation_Lock = require('./Item_Continuation_Lock')
+const Item_Picking_Continuity = require('./Item_Picking_Continuity')
+const { create_density_group_scheduler } = require('./Allocation_Optimization/density_groups/Density_Group_Scheduler')
+const Space_Skip_State = require('./allocation_flow/space_skip_state')
+const { create_chooser_session_state } = require('./allocation_flow/chooser_session_state')
+const { run_allocation_iteration } = require('./allocation_flow/run_allocation_iteration')
+const { try_no_space_left_recovery } = require('./allocation_flow/try_no_space_left_recovery')
+const { remaining_items_fit_container } = require('./allocation_flow/container_remaining_capacity')
+const {Logger} = require('@jetta/logger')
+const logger = new Logger('Allocation Flow')
+const Cargo_Profile = require('./models/Cargo_Profile')
+const { validate_transport_colocation } = require('./validation/Relational_Colocation_Validator')
+const { validate_relational_completeness } = require('./validation/Relational_Completeness_Validator')
+const {
+    normalize_relational_proportional_allocation
+} = require('./validation/Relational_Proportional_Normalizer')
+const has_relational_items = require('./relational/has_relational_items')
+const { traced_step } = require('./tracing/traced_step')
+const { TRACE_CONTEXT } = require('./tracing/Trace_Context')
+
+/**
+ * Orchestrates allocation over each container in order until items are exhausted or the loop stops.
+ */
+class Allocation_flow
+{
+    #transport
+    #block_list
+    #item_list
+    #preferential_block_identifier
+    #space_skip_state = new Space_Skip_State()
+    #chooser_session = create_chooser_session_state()
+    #allocation_attempt
+    #item_lock = new Item_Continuation_Lock()
+    #picking_continuity = new Item_Picking_Continuity()
+    #density_scheduler = null
+    #recovery_state = { count: 0 }
+
+    /**
+     * @param {object} input_state - Prepared input: `transport`, `items_to_allocate`, `blocks`.
+     */
+    constructor(input_state)
+    {
+        this.#transport              = input_state.transport
+        this.#item_list              = input_state.items_to_allocate
+        this.#block_list             = input_state.blocks
+        this.#preferential_block_identifier = new Preferential_Block_Identifier(this.#transport, this.#item_list)
+        this.#allocation_attempt     = new Allocation_Attempt(input_state)
+        this.#density_scheduler      = create_density_group_scheduler(this.#item_list)
+    }
+
+    #build_iteration_context()
+    {
+        return {
+            item_list: this.#item_list,
+            block_list: this.#block_list,
+            preferential_block_identifier: this.#preferential_block_identifier,
+            space_skip_state: this.#space_skip_state,
+            chooser_session: this.#chooser_session,
+            allocation_attempt: this.#allocation_attempt,
+            item_lock: this.#item_lock,
+            picking_continuity: this.#picking_continuity,
+            density_scheduler: this.#density_scheduler,
+            recovery_state: this.#recovery_state
+        }
+    }
+
+    /**
+     * @returns {Promise<object>}
+     */
+    async allocate()
+    {
+        const container_sequence_list = this.#resolve_container_sequences()
+        for (const container_sequence of container_sequence_list)
+        {
+            const container = this.#transport.get_container_by_sequence(container_sequence)
+            logger.debug(`Allocating container ${container_sequence} of ${this.#transport.container_amount()}`)
+            await traced_step(TRACE_CONTEXT.CONTAINER_ALLOCATION, async () =>
+                this.#run_container_iterations(container)
+            )
+        }
+
+        normalize_relational_proportional_allocation(this.#transport, this.#item_list)
+        validate_relational_completeness(this.#transport, this.#item_list)
+        validate_transport_colocation(this.#transport)
+        return this.#transport
+    }
+
+    #resolve_container_sequences()
+    {
+        const all_sequences = this.#transport.get_container_sequence_list()
+
+        if (!Cargo_Profile.enforce_relational_group_co_location())
+        {
+            return all_sequences
+        }
+
+        const has_relational_items_present = has_relational_items(this.#item_list)
+        if (!has_relational_items_present || all_sequences.length === 0)
+        {
+            return all_sequences
+        }
+
+        return [all_sequences[0]]
+    }
+
+    async #run_container_iterations(container)
+    {
+        this.#picking_continuity.reset()
+        this.#chooser_session.tie_ratio_intercalation_state.reset()
+        let capacity = remaining_items_fit_container(this.#item_list, container)
+        this.#item_list = capacity.item_list
+        while (capacity.has_capacity)
+        {
+            const locked_item = this.#item_lock.resolve_locked_item(this.#item_list)
+            const amount_before = this.#item_lock.snapshot_locked_amount(locked_item)
+            const should_continue = await this.#run_single_iteration(
+                this.#build_iteration_context(),
+                container,
+                locked_item
+            )
+            this.#item_lock.release_if_no_progress(amount_before, locked_item)
+            if (!should_continue)
+            {
+                break
+            }
+            capacity = remaining_items_fit_container(this.#item_list, container)
+            this.#item_list = capacity.item_list
+        }
+    }
+
+    async #run_single_iteration(context, container, locked_item)
+    {
+        try
+        {
+            return await run_allocation_iteration(context, container, locked_item)
+        }
+        catch (error)
+        {
+            const recovery = try_no_space_left_recovery({
+                error,
+                container,
+                locked_item,
+                item_list: this.#item_list,
+                space_skip_state: this.#space_skip_state,
+                chooser_session: this.#chooser_session,
+                density_scheduler: this.#density_scheduler,
+                recovery_state: this.#recovery_state
+            })
+            this.#item_list = recovery.item_list
+            if (recovery.recovered)
+            {
+                return true
+            }
+            return handle_allocation_exception(error, this.#allocation_attempt.get_attempt_id())
+        }
+    }
+}
+
+module.exports = Allocation_flow