@jetta/cargo-stabilizer

TypeScript library that reorders items to improve whole-cargo transport stability. By default every item is movable; set cargo_stabilizer.pin_tie_ratio_blocks to pin floor five-slot 3_2/2_3 walls. Stacked tie-ratio pieces and generic groups stay movable one item at a time. The reorder objective is transport_score (loose-item score sum is a tie-break). Implements five config-selectable strategies with organization gates (waypoint order, milkrun wall reservation) and empty-space candidate discovery (JET-2262).

Requirements

• Node.js 24+
• npm

How to install

npm ci
npm run build

Local monorepo development uses file: links to cargo-stability, @jetta/axle-load-calculator, @jetta/empty-spaces-manager, @jetta/number-compare, and @jetta/stacking-constraints.

Usage

import { stabilize, REORDER_STRATEGY } from '@jetta/cargo-stabilizer'

const response = await stabilize({
    cargo_state: {
        envs: [{
            containers: [{
                largura: 2.4,
                altura: 2.7,
                comprimento: 6.0,
                items: [
                    { _id: 'block-1', groupId: 'wall-a', x: 0, y: 0, z: 0, w: 1, h: 1, d: 1 },
                    { _id: 'loose-1', groupId: null, x: 0, y: 1.5, z: 0, w: 0.5, h: 0.5, d: 0.5 }
                ]
            }]
        }]
    },
    config: {
        algoritmo: {
            'cargo_stabilizer.reorder_strategy': REORDER_STRATEGY.GRAVITY
        }
    }
})

if (response.status === 'success') {
    console.log(response.data)
}

I/O contract

parse_stabilizer_input(unknown) is the only untyped boundary. run_stabilize(input: StabilizerInput) returns a typed StabilizerResponse. Wire aliases (_id, w/h/d, eixos, algoritmo) are mapped then stripped; original_input and item attributes bags are rejected.

Success data is English cargo_state (items mutated in x,y,z only). Cargo-movement copies those poses onto existing items by _id.

| CM wire | Contract (English) | |---------|-------------------| | _id | item_id | | groupId | group_id | | w, h, d | width, height, depth | | peso / wg | weight | | sequencia | sequence | | largura, altura, comprimento | width, height, length | | eixos | axles |

Flow: map_wire_input_to_contract → strict Zod parse → run_stabilize → output validation.

Exported parsers: parse_stabilizer_input, parse_stabilizer_output, safe_parse_*, run_stabilize.

Configuration

| Key | Default | Description | |-----|---------|-------------| | cargo_stabilizer.reorder_strategy | gravity | gravity, greedy, beam_search, simulated_annealing, genetic | | cargo_stabilizer.transport_stability_floor | 0 | Hard minimum transport stability score (gate, not the maximize objective) | | cargo_stabilizer.max_iteration | 10 | Greedy / SA iteration budget | | cargo_stabilizer.preserve_tie_block_organization | true | When true, enforce waypoint Z zones and macro delivery order | | cargo_stabilizer.pin_tie_ratio_blocks | false | When true, do not move floor five-slot 3_2/2_3 walls; stacked tie-ratio items and other groups remain movable | | cargo_stabilizer.enforce_milkrun_wall_reservation | false | When true, reserve rear compound-wall Z bands using profile key below | | number_of_wall_to_allocate_from_last_waypoints | 0 | Count of trailing waypoints whose compound walls are reserved (read from cargo_state.config.algoritmo when milkrun enforcement is enabled) | | folga_de_peso_nos_eixos | 0 | Axle folga percent |

Errors

| Error | When | |-------|------| | InvalidStabilizerInputError | Zod validation failure on input | | InvalidStabilizerOutputError | Internal response failed output contract parse | | MixedWaypointIdError | Some items have waypoint_id and others omit it | | UnknownReorderStrategyError | Invalid cargo_stabilizer.reorder_strategy |

Import ZodError from zod when validating externally.

Dependencies

Runtime integrations (all declared in package.json):

• @jetta/cargo-stability — transport stability scoring gate and objective (stability_adapter)
• @jetta/axle-load-calculator — axle load validation gate (axle_adapter)
• @jetta/empty-spaces-manager — empty-region candidate slot discovery (empty_space_adapter)
• @jetta/number-compare — face-touch interval tests (has_penetrating_overlap)
• @jetta/stacking-constraints — family and supported-weight gate on candidate moves
• @jetta/logger — structured logging at orchestration boundary (transitive via cargo-stability)
• zod — I/O contract validation

Scripts

| Command | Description | |---------|-------------| | npm test | Mocha tests (208 cases) | | npm run lint | ESLint | | npm run build | TypeScript compile to build/ | | npm run coverage | Tests with 80% coverage gate (local) | | npm run coverage:ci | Tests with 75% coverage gate (CI) | | npm run lint:package | publint strict check |

Layout

• src/index.ts — public API (stabilize, run_stabilize)
• src/core/validation/contract/ — strict English I/O contract and CM wire mapper
• src/core/strategies/reorder/ — five reorder algorithms
• src/core/evaluation/ — shared stability + axle + waypoint gates and search admission
• src/core/candidates/ — empty-space slot discovery, stacking gate, and candidate ranking
• test/src/ — mirrors src/; fixtures under test/data/src/

Testing and coverage

Tests run via Mocha + Chai with quiet logging (test/mocha_setup.ts). Core modules are preloaded at startup so c8 reports accurate coverage when the full suite runs.

| Gate | Command | Threshold | |------|---------|-----------| | Local | npm run coverage | 80% lines, functions, branches, statements | | CI | npm run coverage:ci | 75% on all metrics |

Test plan

npm test -- --grep "wire_mapper_shape"
npm test -- --grep "input_validation"
npm test -- --grep "waypoint_order"
npm test -- --grep "milkrun_wall_reservation"
npm test -- --grep "apply_move"
npm test -- --grep "state_evaluator"
npm test -- --grep "gravity_compaction"
npm test -- --grep "reorder_strategy_depth"
npm test -- --grep "is_search_trial_admissible"
npm test -- --grep "is_candidate_stacking_valid"
npm run coverage