@jetta/cargo-stabilizer 0.1.0-10

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `@jetta/cargo-stabilizer` are documented in this file.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Added
+
+- Strict English internal I/O contract with bidirectional cargo-movement wire mapper (`map_wire_input_to_contract`, `map_contract_to_wire_output`).
+- Organization gates: waypoint Z zones, macro delivery order (`preserve_tie_block_organization`), and milkrun wall reservation (`enforce_milkrun_wall_reservation`).
+- Empty-space candidate discovery for floor and elevated slots via `@jetta/empty-spaces-manager`.
+- Supporter-top candidate slots aligned to each stacked item footprint, included in beam expansion (`top_k ∪ supporter_top`).
+- Elevated candidates must sit on a supporter `(x, z)` origin so stacked loose items copy the supporter footprint.
+- `cargo_stabilizer.pin_tie_ratio_blocks` (default `false`): when true, 3_2/2_3 groups stay pinned; otherwise every item is movable.
+- Public contract exports: `parse_stabilizer_input`, `parse_stabilizer_output`, `safe_parse_stabilizer_input`, `safe_parse_stabilizer_output`, and related domain types.
+
+### Changed
+
+- README documents I/O contract mapping, configuration keys, dependencies, and test/coverage commands.
+- Reorder objective is whole-cargo `transport_score`; loose-item score sum is only a tie-break. Axle, waypoint, and milkrun gates are unchanged.
+
+### Testing
+
+- Expanded Mocha suite to 126 tests mirroring `src/` under `test/src/`.
+- Local coverage gate at 80% on lines, functions, branches, and statements (`npm run coverage`).
+- CI coverage gate at 75% (`npm run coverage:ci`).
+- Mocha setup preloads core modules so c8 attributes coverage consistently across the full suite.
+
+## [0.1.0-3] - 2026-08-14
+
+### Added
+
+- Initial library scaffold (JET-2262).
+- Five config-selectable reorder strategies: gravity, greedy, beam search, simulated annealing, genetic.
+- Zod-validated input contract with `waypoint_id` rules and multi-container support.
+- Shared evaluator: cargo-stability transport gate, axle-load-calculator folga gate, waypoint order.
+- Public `stabilize()` API compatible with cargo-movement legacy response shape.

package/README.md

@@ -0,0 +1,144 @@
+# @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 3_2/2_3 groups. 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
+
+```bash
+npm ci
+npm run build
+```
+
+Local monorepo development uses `file:` links to `cargo-stability`, `@jetta/axle-load-calculator`, and `@jetta/empty-spaces-manager`.
+
+## Usage
+
+```typescript
+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
+
+The stabilizer uses a **strict English contract** internally (`src/core/validation/contract/`). Cargo-movement wire payloads keep legacy Portuguese keys; a bidirectional mapper translates at the public boundary.
+
+| CM wire | Contract (English) |
+|---------|-------------------|
+| `_id` | `item_id` |
+| `groupId` | `group_id` |
+| `w`, `h`, `d` | `width`, `height`, `depth` |
+| `peso` | `weight` |
+| `sequencia` | `sequence` |
+| `largura`, `altura`, `comprimento` | `width`, `height`, `length` |
+| `eixos` | `axles` |
+
+Flow: `map_wire_input_to_contract` → strict Zod parse → stabilizer flow → output validation → `map_contract_to_wire_output`.
+
+Exported parsers: `parse_stabilizer_input`, `parse_stabilizer_output`, `safe_parse_*`.
+
+## 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 3_2/2_3 groups; other items 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/logger` — structured logging at orchestration boundary (transitive via cargo-stability)
+- `zod` — I/O contract validation
+
+## Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm test` | Mocha tests (126 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`)
+- `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
+- `src/core/candidates/` — empty-space slot discovery 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
+
+```bash
+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 "strategy_factory"
+npm run coverage
+```

package/build/core/adapters/axle_adapter.d.ts

@@ -0,0 +1,16 @@
+import type { StabilizerEnv } from '../validation/contract/stabilizer_domain_schema.js';
+/**
+ * @param final_kg - Loaded weight including tare.
+ * @param max_kg - Axle supported max.
+ * @param folga_pct - Axle load margin percent from profile.
+ * @returns True when axle exceeds under folga rule.
+ */
+export declare function exceeds_with_folga(final_kg: number, max_kg: number, folga_pct: number): boolean;
+/**
+ * Validates axle loads for an env using axle-load-calculator.
+ * @param env - Stabilizer env with containers and axles.
+ * @param folga_pct - Axle load margin percent.
+ * @returns True when all axles are within limits.
+ */
+export declare function is_axle_load_valid(env: StabilizerEnv, folga_pct: number): boolean;
+//# sourceMappingURL=axle_adapter.d.ts.map

package/build/core/adapters/axle_adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axle_adapter.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/axle_adapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oDAAoD,CAAA;AAEvF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAC9B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAClB,OAAO,CAGT;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAejF"}

package/build/core/adapters/axle_adapter.js

@@ -0,0 +1,35 @@
+import { run_axle_calculator } from './run_axle_calculator.js';
+/**
+ * @param final_kg - Loaded weight including tare.
+ * @param max_kg - Axle supported max.
+ * @param folga_pct - Axle load margin percent from profile.
+ * @returns True when axle exceeds under folga rule.
+ */
+export function exceeds_with_folga(final_kg, max_kg, folga_pct) {
+    return final_kg > max_kg * (1 + folga_pct / 100);
+}
+/**
+ * Validates axle loads for an env using axle-load-calculator.
+ * @param env - Stabilizer env with containers and axles.
+ * @param folga_pct - Axle load margin percent.
+ * @returns True when all axles are within limits.
+ */
+export function is_axle_load_valid(env, folga_pct) {
+    if (!env.axles || env.axles.length === 0) {
+        return true;
+    }
+    const result = run_axle_calculator(env);
+    if (!result.calculated) {
+        return false;
+    }
+    const containers = (result.env.containers ?? []);
+    return containers.every(container => container_axles_within_folga(container, folga_pct));
+}
+function container_axles_within_folga(container, folga_pct) {
+    const axles = (container.pesoEixos ?? []);
+    return axles.every(axle => {
+        const final_kg = Number(axle.pesoCarregadoFinal ?? 0);
+        const max_kg = Number(axle.pesoMaxFinal ?? 0);
+        return !exceeds_with_folga(final_kg, max_kg, folga_pct);
+    });
+}

package/build/core/adapters/build_axle_request.d.ts

@@ -0,0 +1,15 @@
+import type { StabilizerEnv } from '../validation/contract/stabilizer_domain_schema.js';
+/**
+ * Builds the axle-load-calculator request for a single env.
+ *
+ * The calculator physics reads `peso`, `largura`, `altura` and `comprimento`
+ * (ItemTemplates and JavaMassCenter), none of which exist in the
+ * cargo-movement wire item shape (`wg`, `w`, `h`, `d`). Without these aliases
+ * every item weighs zero and the axle gate can never reject a layout, so the
+ * contract values are stamped onto each request item here. Longitudinal extent
+ * is `depth`, matching the wire `y` axis the calculator uses for equilibrium.
+ * @param env - Stabilizer env with containers and axles.
+ * @returns Calculator request payload.
+ */
+export declare function build_axle_request(env: StabilizerEnv): Record<string, unknown>;
+//# sourceMappingURL=build_axle_request.d.ts.map

package/build/core/adapters/build_axle_request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build_axle_request.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/build_axle_request.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAER,aAAa,EAEhB,MAAM,oDAAoD,CAAA;AAE3D;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAS9E"}

package/build/core/adapters/build_axle_request.js

@@ -0,0 +1,39 @@
+import { map_contract_to_wire_output } from '../validation/contract/cargo_movement_wire_mapper.js';
+/**
+ * Builds the axle-load-calculator request for a single env.
+ *
+ * The calculator physics reads `peso`, `largura`, `altura` and `comprimento`
+ * (ItemTemplates and JavaMassCenter), none of which exist in the
+ * cargo-movement wire item shape (`wg`, `w`, `h`, `d`). Without these aliases
+ * every item weighs zero and the axle gate can never reject a layout, so the
+ * contract values are stamped onto each request item here. Longitudinal extent
+ * is `depth`, matching the wire `y` axis the calculator uses for equilibrium.
+ * @param env - Stabilizer env with containers and axles.
+ * @returns Calculator request payload.
+ */
+export function build_axle_request(env) {
+    const wire = map_contract_to_wire_output({ envs: [env] });
+    const wire_env = wire.envs[0];
+    const wire_containers = (wire_env.containers ?? []);
+    wire_env.containers = wire_containers.map((wire_container, index) => stamp_container_physics_aliases(wire_container, env.containers[index]));
+    return { envs: wire.envs };
+}
+function stamp_container_physics_aliases(wire_container, container) {
+    const wire_items = (wire_container.items ?? []);
+    return {
+        ...wire_container,
+        items: wire_items.map((wire_item, index) => stamp_item_physics_aliases(wire_item, container?.items[index]))
+    };
+}
+function stamp_item_physics_aliases(wire_item, item) {
+    if (item === undefined) {
+        return wire_item;
+    }
+    return {
+        ...wire_item,
+        peso: item.weight ?? 0,
+        largura: item.width,
+        altura: item.height,
+        comprimento: item.depth
+    };
+}

package/build/core/adapters/coordinate_mapper.d.ts

@@ -0,0 +1,36 @@
+import type { StabilizerContainer, StabilizerItem } from '../validation/contract/stabilizer_domain_schema.js';
+import { type AxisAlignedBox } from '../geometry/box_geometry.js';
+export interface StabilityItemPayload {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+    h: number;
+    l: number;
+}
+export interface StabilityContainerPayload {
+    w: number;
+    h: number;
+    l: number;
+    item_list: StabilityItemPayload[];
+}
+/**
+ * Maps contract coordinates to cargo-stability payload coordinates.
+ * @param item - Stabilizer item record.
+ * @returns Stability item payload entry.
+ */
+export declare function map_item_to_stability(item: StabilizerItem): StabilityItemPayload;
+/**
+ * Builds cargo-stability transport input from stabilizer containers.
+ * @param containers - Stabilizer container records.
+ * @returns Stability containers array.
+ */
+export declare function build_stability_containers(containers: StabilizerContainer[]): StabilityContainerPayload[];
+/**
+ * Collects all item boxes in a container, optionally excluding one item id.
+ * @param container - Container with items.
+ * @param exclude_item_id - Item id to skip (virtual remove).
+ * @returns Bounding boxes for remaining items.
+ */
+export declare function collect_container_boxes(container: StabilizerContainer, exclude_item_id?: string): AxisAlignedBox[];
+//# sourceMappingURL=coordinate_mapper.d.ts.map

package/build/core/adapters/coordinate_mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinate_mapper.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/coordinate_mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AAC7G,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAE9E,MAAM,WAAW,oBAAoB;IAEjC,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,yBAAyB;IAEtC,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,SAAS,EAAE,oBAAoB,EAAE,CAAA;CACpC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,GAAG,oBAAoB,CAUhF;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACtC,UAAU,EAAE,mBAAmB,EAAE,GAClC,yBAAyB,EAAE,CAQ7B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,SAAS,EAAE,mBAAmB,EAC9B,eAAe,CAAC,EAAE,MAAM,GACzB,cAAc,EAAE,CAKlB"}

package/build/core/adapters/coordinate_mapper.js

@@ -0,0 +1,40 @@
+import { item_to_box } from '../geometry/box_geometry.js';
+/**
+ * Maps contract coordinates to cargo-stability payload coordinates.
+ * @param item - Stabilizer item record.
+ * @returns Stability item payload entry.
+ */
+export function map_item_to_stability(item) {
+    return {
+        x: item.x,
+        y: item.z,
+        z: item.y,
+        w: item.width,
+        h: item.height,
+        l: item.depth
+    };
+}
+/**
+ * Builds cargo-stability transport input from stabilizer containers.
+ * @param containers - Stabilizer container records.
+ * @returns Stability containers array.
+ */
+export function build_stability_containers(containers) {
+    return containers.map(container => ({
+        w: container.width,
+        h: container.height,
+        l: container.length,
+        item_list: container.items.map(map_item_to_stability)
+    }));
+}
+/**
+ * Collects all item boxes in a container, optionally excluding one item id.
+ * @param container - Container with items.
+ * @param exclude_item_id - Item id to skip (virtual remove).
+ * @returns Bounding boxes for remaining items.
+ */
+export function collect_container_boxes(container, exclude_item_id) {
+    return container.items
+        .filter(item => item.item_id !== exclude_item_id)
+        .map(item_to_box);
+}

package/build/core/adapters/empty_space_adapter.d.ts

@@ -0,0 +1,10 @@
+import { Space } from '@jetta/empty-spaces-manager';
+import type { StabilizerContainer } from '../validation/contract/stabilizer_domain_schema.js';
+/**
+ * Finds empty regions in a container after allocating pinned and other items.
+ * @param container - Stabilizer container layout.
+ * @param exclude_item_id - Loose item id to omit from obstacles (virtual remove).
+ * @returns Empty space fragments from EmptySpaceFinder.
+ */
+export declare function find_empty_spaces_in_container(container: StabilizerContainer, exclude_item_id?: string): Space[];
+//# sourceMappingURL=empty_space_adapter.d.ts.map

package/build/core/adapters/empty_space_adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"empty_space_adapter.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/empty_space_adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,EAAE,MAAM,6BAA6B,CAAA;AAErE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAA;AAE7F;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC1C,SAAS,EAAE,mBAAmB,EAC9B,eAAe,CAAC,EAAE,MAAM,GACzB,KAAK,EAAE,CAgBT"}

package/build/core/adapters/empty_space_adapter.js

@@ -0,0 +1,24 @@
+import { EmptySpaceFinder, Space } from '@jetta/empty-spaces-manager';
+import { map_item_to_positioned_cube } from './map_item_to_positioned_cube.js';
+/**
+ * Finds empty regions in a container after allocating pinned and other items.
+ * @param container - Stabilizer container layout.
+ * @param exclude_item_id - Loose item id to omit from obstacles (virtual remove).
+ * @returns Empty space fragments from EmptySpaceFinder.
+ */
+export function find_empty_spaces_in_container(container, exclude_item_id) {
+    const container_space = new Space({
+        x: 0,
+        y: 0,
+        z: 0,
+        width: container.width,
+        height: container.height,
+        length: container.length
+    });
+    const obstacles = container.items
+        .filter(item => item.item_id !== exclude_item_id)
+        .map(map_item_to_positioned_cube);
+    const finder = new EmptySpaceFinder(container_space, []);
+    finder.allocate_item_list(obstacles);
+    return finder.empty_spaces();
+}

package/build/core/adapters/map_item_to_positioned_cube.d.ts

@@ -0,0 +1,9 @@
+import { Space } from '@jetta/empty-spaces-manager';
+import type { StabilizerItem } from '../validation/contract/stabilizer_domain_schema.js';
+/**
+ * Maps a stabilizer item to an empty-spaces positioned cube.
+ * @param item - Stabilizer item record.
+ * @returns Positioned cube for EmptySpaceFinder allocation.
+ */
+export declare function map_item_to_positioned_cube(item: StabilizerItem): Space;
+//# sourceMappingURL=map_item_to_positioned_cube.d.ts.map

package/build/core/adapters/map_item_to_positioned_cube.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map_item_to_positioned_cube.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/map_item_to_positioned_cube.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAA;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AAExF;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,cAAc,GAAG,KAAK,CAUvE"}

package/build/core/adapters/map_item_to_positioned_cube.js

@@ -0,0 +1,16 @@
+import { Space } from '@jetta/empty-spaces-manager';
+/**
+ * Maps a stabilizer item to an empty-spaces positioned cube.
+ * @param item - Stabilizer item record.
+ * @returns Positioned cube for EmptySpaceFinder allocation.
+ */
+export function map_item_to_positioned_cube(item) {
+    return new Space({
+        x: item.x,
+        y: item.y,
+        z: item.z,
+        width: item.width,
+        height: item.height,
+        length: item.depth
+    });
+}

package/build/core/adapters/run_axle_calculator.d.ts

@@ -0,0 +1,16 @@
+import type { StabilizerEnv } from '../validation/contract/stabilizer_domain_schema.js';
+export type AxleCalculatorResult = {
+    calculated: true;
+    env: Record<string, unknown>;
+} | {
+    calculated: false;
+    reason: string;
+};
+/**
+ * Runs the axle-load calculator for a candidate env layout.
+ * @param env - Stabilizer env with containers and axles.
+ * @returns Calculated env, or the reason the layout was rejected.
+ * @throws {AxleCalculationError} When the vehicle or item configuration cannot be calculated.
+ */
+export declare function run_axle_calculator(env: StabilizerEnv): AxleCalculatorResult;
+//# sourceMappingURL=run_axle_calculator.d.ts.map

package/build/core/adapters/run_axle_calculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run_axle_calculator.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/run_axle_calculator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oDAAoD,CAAA;AASvF,MAAM,MAAM,oBAAoB,GAC1B;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAClD;IAAE,UAAU,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,GAAG,oBAAoB,CAoB5E"}

package/build/core/adapters/run_axle_calculator.js

@@ -0,0 +1,32 @@
+import { calculate_weight_on_axles_physics } from '@jetta/axle-load-calculator';
+import { build_axle_request } from './build_axle_request.js';
+import { AxleCalculationError } from '../exceptions/AxleCalculationError.js';
+import { stabilizer_logger } from '../logging/stabilizer_logger.js';
+/**
+ * Calculator failures caused by the candidate layout rather than by the vehicle
+ * or item configuration. These reject the candidate layout; every other failure
+ * means the env can never be evaluated and aborts the run.
+ */
+const LAYOUT_REJECTION_MESSAGES = Object.freeze(['Item overlap error']);
+/**
+ * Runs the axle-load calculator for a candidate env layout.
+ * @param env - Stabilizer env with containers and axles.
+ * @returns Calculated env, or the reason the layout was rejected.
+ * @throws {AxleCalculationError} When the vehicle or item configuration cannot be calculated.
+ */
+export function run_axle_calculator(env) {
+    const request = build_axle_request(env);
+    const output = JSON.parse(calculate_weight_on_axles_physics(JSON.stringify(request)));
+    if (Array.isArray(output.envs) && output.envs.length > 0) {
+        return { calculated: true, env: output.envs[0] };
+    }
+    const reason = output.apiError ?? 'calculator returned no envs';
+    if (!is_layout_rejection(reason)) {
+        throw new AxleCalculationError(reason);
+    }
+    stabilizer_logger.debug('axle gate rejected candidate layout: ' + reason);
+    return { calculated: false, reason };
+}
+function is_layout_rejection(reason) {
+    return LAYOUT_REJECTION_MESSAGES.some(message => reason.includes(message));
+}

package/build/core/adapters/stability_adapter.d.ts

@@ -0,0 +1,36 @@
+import type { StabilizerContainer } from '../validation/contract/stabilizer_domain_schema.js';
+import type { LooseItemRef } from '../filters/loose_item_filter.js';
+export interface StabilityEvaluation {
+    item_scores: number[][];
+    container_scores: number[];
+    transport_score: number;
+}
+/**
+ * Evaluates transport stability for CM containers.
+ * @param containers - CM container list.
+ * @returns Per-item and transport stability scores.
+ */
+export declare function evaluate_transport_stability(containers: StabilizerContainer[]): StabilityEvaluation;
+/**
+ * Evaluates transport stability, returning undefined when cargo-stability rejects layout.
+ * @param containers - CM container list.
+ * @returns Stability scores or undefined on invalid geometry/score.
+ */
+export declare function try_evaluate_transport_stability(containers: StabilizerContainer[]): StabilityEvaluation | undefined;
+/**
+ * Sums stability scores for loose items only.
+ * @param stability - Stability evaluation result.
+ * @param containers - CM containers (for index lookup).
+ * @param loose_items - Loose item references.
+ * @returns Sum of loose item scores.
+ */
+export declare function sum_loose_item_scores(stability: StabilityEvaluation, containers: StabilizerContainer[], loose_items: LooseItemRef[]): number;
+/**
+ * Reads a single item stability score.
+ * @param stability - Stability evaluation.
+ * @param container_index - Container index.
+ * @param item_index - Item index in container.
+ * @returns Item score or zero when missing.
+ */
+export declare function read_item_score(stability: StabilityEvaluation, container_index: number, item_index: number): number;
+//# sourceMappingURL=stability_adapter.d.ts.map

package/build/core/adapters/stability_adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stability_adapter.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/stability_adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAA;AAC7F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AAEnE,MAAM,WAAW,mBAAmB;IAEhC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAA;IACvB,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,eAAe,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CACxC,UAAU,EAAE,mBAAmB,EAAE,GAClC,mBAAmB,CAiBrB;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC5C,UAAU,EAAE,mBAAmB,EAAE,GAClC,mBAAmB,GAAG,SAAS,CAUjC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACjC,SAAS,EAAE,mBAAmB,EAC9B,UAAU,EAAE,mBAAmB,EAAE,EACjC,WAAW,EAAE,YAAY,EAAE,GAC5B,MAAM,CAgBR;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC3B,SAAS,EAAE,mBAAmB,EAC9B,eAAe,EAAE,MAAM,EACvB,UAAU,EAAE,MAAM,GACnB,MAAM,CAGR"}

package/build/core/adapters/stability_adapter.js

@@ -0,0 +1,61 @@
+import { calculate_cargo_stability } from '@jetta/cargo-stability';
+import { build_stability_containers } from './coordinate_mapper.js';
+/**
+ * Evaluates transport stability for CM containers.
+ * @param containers - CM container list.
+ * @returns Per-item and transport stability scores.
+ */
+export function evaluate_transport_stability(containers) {
+    const payload = {
+        calculation_type: 'transport',
+        containers: build_stability_containers(containers)
+    };
+    const result = calculate_cargo_stability(payload);
+    return {
+        item_scores: result.items,
+        container_scores: result.containers,
+        transport_score: result.transport
+    };
+}
+/**
+ * Evaluates transport stability, returning undefined when cargo-stability rejects layout.
+ * @param containers - CM container list.
+ * @returns Stability scores or undefined on invalid geometry/score.
+ */
+export function try_evaluate_transport_stability(containers) {
+    try {
+        return evaluate_transport_stability(containers);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Sums stability scores for loose items only.
+ * @param stability - Stability evaluation result.
+ * @param containers - CM containers (for index lookup).
+ * @param loose_items - Loose item references.
+ * @returns Sum of loose item scores.
+ */
+export function sum_loose_item_scores(stability, containers, loose_items) {
+    let total = 0;
+    for (const loose of loose_items) {
+        const container = containers[loose.container_index];
+        const item_index = container.items.findIndex(item => item.item_id === loose.item_id);
+        if (item_index < 0) {
+            continue;
+        }
+        total += stability.item_scores[loose.container_index]?.[item_index] ?? 0;
+    }
+    return total;
+}
+/**
+ * Reads a single item stability score.
+ * @param stability - Stability evaluation.
+ * @param container_index - Container index.
+ * @param item_index - Item index in container.
+ * @returns Item score or zero when missing.
+ */
+export function read_item_score(stability, container_index, item_index) {
+    return stability.item_scores[container_index]?.[item_index] ?? 0;
+}

package/build/core/candidates/build_candidate_context.d.ts

@@ -0,0 +1,13 @@
+import type { StabilizerContainer } from '../validation/contract/stabilizer_domain_schema.js';
+import type { LooseItemRef } from '../filters/loose_item_filter.js';
+import type { ReorderContext } from '../strategies/reorder/ReorderStrategy.js';
+import type { CandidateGenerationContext } from './candidate_context.js';
+/**
+ * Builds candidate generation context for one loose item.
+ * @param context - Reorder context.
+ * @param containers - Working container layout.
+ * @param loose - Loose item reference.
+ * @returns Candidate generation context.
+ */
+export declare function candidate_context_for_loose(context: ReorderContext, containers: StabilizerContainer[], loose: LooseItemRef): CandidateGenerationContext;
+//# sourceMappingURL=build_candidate_context.d.ts.map

package/build/core/candidates/build_candidate_context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build_candidate_context.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/build_candidate_context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAA;AAC7F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAA;AAC9E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAExE;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACvC,OAAO,EAAE,cAAc,EACvB,UAAU,EAAE,mBAAmB,EAAE,EACjC,KAAK,EAAE,YAAY,GACpB,0BAA0B,CAU5B"}

package/build/core/candidates/build_candidate_context.js

@@ -0,0 +1,17 @@
+/**
+ * Builds candidate generation context for one loose item.
+ * @param context - Reorder context.
+ * @param containers - Working container layout.
+ * @param loose - Loose item reference.
+ * @returns Candidate generation context.
+ */
+export function candidate_context_for_loose(context, containers, loose) {
+    return {
+        containers,
+        loose,
+        mode: context.waypoint_mode,
+        zones: context.waypoint_zones,
+        preserve_tie_block_organization: context.config.preserve_tie_block_organization,
+        milkrun_reserved_z_bands: context.milkrun_reserved_z_bands
+    };
+}