@jetta/cargo-stabilizer 0.1.0-3 → 0.1.0-5

package/CHANGELOG.md

@@ -8,8 +8,28 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### 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`.
+- 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.
+
+### 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.
+- 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

@@ -1,6 +1,6 @@
 # @jetta/cargo-stabilizer
 
-TypeScript library that reorders **loose items only** to improve cargo stability while keeping compound blocks pinned. Implements five config-selectable strategies (JET-2262).
+TypeScript library that reorders **loose items only** to improve cargo stability while keeping compound blocks pinned. Implements five config-selectable strategies with organization gates (waypoint order, milkrun wall reservation) and empty-space candidate discovery (JET-2262).
 
 ## Requirements
 
@@ -47,6 +47,24 @@ if (response.status === 'success') {
 }
 ```
 
+## 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 |
@@ -54,6 +72,9 @@ if (response.status === 'success') {
 | `cargo_stabilizer.reorder_strategy` | `gravity` | `gravity`, `greedy`, `beam_search`, `simulated_annealing`, `genetic` |
 | `cargo_stabilizer.transport_stability_floor` | `0` | Hard minimum transport stability score |
 | `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.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
@@ -61,6 +82,7 @@ if (response.status === 'success') {
 | 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` |
 
@@ -68,36 +90,54 @@ Import `ZodError` from `zod` when validating externally.
 
 ## Dependencies
 
-- `cargo-stability` — transport stability scoring
-- `@jetta/axle-load-calculator` — axle weight validation
-- `@jetta/empty-spaces-manager` — empty region discovery (future slot expansion)
-- `@jetta/logger` — structured logging at orchestration boundary
-- `zod` — input validation
+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 |
+| `npm test` | Mocha tests (126 cases) |
 | `npm run lint` | ESLint |
 | `npm run build` | TypeScript compile to `build/` |
-| `npm run coverage:ci` | Tests with 75% coverage gate |
+| `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/` — Zod schemas
+- `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
-- `test/src/` — mirrors `src/`
+- `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 "greedy_reorder"
+npm test -- --grep "reorder_strategy_depth"
 npm test -- --grep "strategy_factory"
+npm run coverage
 ```

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

@@ -1,15 +1,15 @@
-import type { StabilizerEnv } from '../validation/schemas/stabilizer_input_schema.js';
+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 - Folga percent from profile.
+ * @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 - CM env with containers and eixos.
- * @param folga_pct - Folga percent.
+ * @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;

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

@@ -1 +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,kDAAkD,CAAA;AAErF;;;;;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,CAUjF"}
+{"version":3,"file":"axle_adapter.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/axle_adapter.ts"],"names":[],"mappings":"AAEA,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,CAUjF"}

package/build/core/adapters/axle_adapter.js

@@ -1,8 +1,9 @@
 import { calculate_weight_on_axles_physics } from '@jetta/axle-load-calculator';
+import { map_contract_to_wire_output } from '../validation/contract/cargo_movement_wire_mapper.js';
 /**
  * @param final_kg - Loaded weight including tare.
  * @param max_kg - Axle supported max.
- * @param folga_pct - Folga percent from profile.
+ * @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) {
@@ -10,12 +11,12 @@ export function exceeds_with_folga(final_kg, max_kg, folga_pct) {
 }
 /**
  * Validates axle loads for an env using axle-load-calculator.
- * @param env - CM env with containers and eixos.
- * @param folga_pct - Folga percent.
+ * @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.eixos || env.eixos.length === 0) {
+    if (!env.axles || env.axles.length === 0) {
         return true;
     }
     const output_env = parse_axle_calculator_output(env);
@@ -23,7 +24,8 @@ export function is_axle_load_valid(env, folga_pct) {
     return containers.every(container => container_axles_within_folga(container, folga_pct));
 }
 function parse_axle_calculator_output(env) {
-    const request = { envs: [env] };
+    const wire_cargo_state = map_contract_to_wire_output({ envs: [env] });
+    const request = { envs: wire_cargo_state.envs };
     const output = JSON.parse(calculate_weight_on_axles_physics(JSON.stringify(request)));
     return output.envs[0];
 }

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

@@ -1,4 +1,4 @@
-import type { StabilizerContainer, StabilizerItem } from '../validation/schemas/stabilizer_input_schema.js';
+import type { StabilizerContainer, StabilizerItem } from '../validation/contract/stabilizer_domain_schema.js';
 import { type AxisAlignedBox } from '../geometry/box_geometry.js';
 export interface StabilityItemPayload {
     x: number;
@@ -15,14 +15,14 @@ export interface StabilityContainerPayload {
     item_list: StabilityItemPayload[];
 }
 /**
- * Maps CM wire coordinates to cargo-stability payload coordinates.
- * @param item - CM item record.
+ * 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 CM containers.
- * @param containers - CM container records.
+ * 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[];

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

@@ -1 +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,kDAAkD,CAAA;AAC3G,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"}
+{"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

@@ -1,7 +1,7 @@
 import { item_to_box } from '../geometry/box_geometry.js';
 /**
- * Maps CM wire coordinates to cargo-stability payload coordinates.
- * @param item - CM item record.
+ * 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) {
@@ -9,21 +9,21 @@ export function map_item_to_stability(item) {
         x: item.x,
         y: item.z,
         z: item.y,
-        w: item.w,
-        h: item.h,
-        l: item.d
+        w: item.width,
+        h: item.height,
+        l: item.depth
     };
 }
 /**
- * Builds cargo-stability transport input from CM containers.
- * @param containers - CM container records.
+ * 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.largura,
-        h: container.altura,
-        l: container.comprimento,
+        w: container.width,
+        h: container.height,
+        l: container.length,
         item_list: container.items.map(map_item_to_stability)
     }));
 }
@@ -35,6 +35,6 @@ export function build_stability_containers(containers) {
  */
 export function collect_container_boxes(container, exclude_item_id) {
     return container.items
-        .filter(item => item._id !== exclude_item_id)
+        .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/stability_adapter.d.ts

@@ -1,4 +1,4 @@
-import type { StabilizerContainer } from '../validation/schemas/stabilizer_input_schema.js';
+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[][];

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

@@ -1 +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,kDAAkD,CAAA;AAC3F,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"}
+{"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

@@ -41,7 +41,7 @@ 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._id === loose.item_id);
+        const item_index = container.items.findIndex(item => item.item_id === loose.item_id);
         if (item_index < 0) {
             continue;
         }

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

@@ -1,4 +1,4 @@
-import type { StabilizerContainer } from '../validation/schemas/stabilizer_input_schema.js';
+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';

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

@@ -1 +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,kDAAkD,CAAA;AAC3F,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,CAQ5B"}
+{"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

@@ -10,6 +10,8 @@ export function candidate_context_for_loose(context, containers, loose) {
         containers,
         loose,
         mode: context.waypoint_mode,
-        zones: context.waypoint_zones
+        zones: context.waypoint_zones,
+        preserve_tie_block_organization: context.config.preserve_tie_block_organization,
+        milkrun_reserved_z_bands: context.milkrun_reserved_z_bands
     };
 }

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

@@ -1,10 +1,13 @@
-import type { StabilizerContainer } from '../validation/schemas/stabilizer_input_schema.js';
+import type { StabilizerContainer } from '../validation/contract/stabilizer_domain_schema.js';
 import type { LooseItemRef } from '../filters/loose_item_filter.js';
 import type { WaypointMode, WaypointZone } from '../waypoint/WaypointMode.js';
+import type { MilkrunReservedBand } from '../waypoint/milkrun_wall_reservation.js';
 export interface CandidateGenerationContext {
     containers: StabilizerContainer[];
     loose: LooseItemRef;
     mode: WaypointMode;
     zones: WaypointZone[];
+    preserve_tie_block_organization: boolean;
+    milkrun_reserved_z_bands: MilkrunReservedBand[];
 }
 //# sourceMappingURL=candidate_context.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"candidate_context.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/candidate_context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAA;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAE7E,MAAM,WAAW,0BAA0B;IAEvC,UAAU,EAAE,mBAAmB,EAAE,CAAA;IACjC,KAAK,EAAE,YAAY,CAAA;IACnB,IAAI,EAAE,YAAY,CAAA;IAClB,KAAK,EAAE,YAAY,EAAE,CAAA;CACxB"}
+{"version":3,"file":"candidate_context.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/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,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAA;AAElF,MAAM,WAAW,0BAA0B;IAEvC,UAAU,EAAE,mBAAmB,EAAE,CAAA;IACjC,KAAK,EAAE,YAAY,CAAA;IACnB,IAAI,EAAE,YAAY,CAAA;IAClB,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,+BAA+B,EAAE,OAAO,CAAA;IACxC,wBAAwB,EAAE,mBAAmB,EAAE,CAAA;CAClD"}

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

@@ -1,7 +1,7 @@
 import type { MoveCandidate } from '../move/apply_move.js';
 import type { CandidateGenerationContext } from './candidate_context.js';
 /**
- * Generates ranked floor-first candidate slots for a loose item.
+ * Generates ranked candidate slots from empty-space regions for a loose item.
  * @param context - Candidate generation context.
  * @returns Candidate moves sorted floor-first, same container preferred.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"candidate_generator.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/candidate_generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAIxE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,aAAa,EAAE,CAuBxF"}
+{"version":3,"file":"candidate_generator.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/candidate_generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAKxE;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,aAAa,EAAE,CAMxF"}

package/build/core/candidates/candidate_generator.js

@@ -1,25 +1,28 @@
-import { enumerate_floor_slots, is_candidate_valid } from './candidate_validation.js';
+import { enumerate_empty_space_slots } from './enumerate_empty_space_slots.js';
+import { is_candidate_valid } from './candidate_validation.js';
 import { rank_candidates } from './rank_candidates.js';
 /**
- * Generates ranked floor-first candidate slots for a loose item.
+ * Generates ranked candidate slots from empty-space regions for a loose item.
  * @param context - Candidate generation context.
  * @returns Candidate moves sorted floor-first, same container preferred.
  */
 export function generate_candidates(context) {
+    const candidates = context.containers.flatMap((container, target_index) => build_container_candidates(context, container, target_index));
+    return rank_candidates(candidates, context.loose.container_index);
+}
+function build_container_candidates(context, container, target_index) {
+    const slots = enumerate_empty_space_slots(container, context.loose.item, context.loose.item_id);
     const candidates = [];
-    context.containers.forEach((container, target_index) => {
-        const slots = enumerate_floor_slots(container, context.loose.item);
-        for (const position of slots) {
-            if (!is_candidate_valid(context, target_index, position)) {
-                continue;
-            }
-            candidates.push({
-                item_id: context.loose.item_id,
-                source_container_index: context.loose.container_index,
-                target_container_index: target_index,
-                new_position: position
-            });
+    for (const position of slots) {
+        if (!is_candidate_valid(context, target_index, position)) {
+            continue;
         }
-    });
-    return rank_candidates(candidates, context.loose.container_index);
+        candidates.push({
+            item_id: context.loose.item_id,
+            source_container_index: context.loose.container_index,
+            target_container_index: target_index,
+            new_position: position
+        });
+    }
+    return candidates;
 }

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

@@ -1,16 +1,4 @@
-import type { StabilizerContainer, StabilizerItem } from '../validation/schemas/stabilizer_input_schema.js';
 import type { CandidateGenerationContext } from './candidate_context.js';
-/**
- * Enumerates floor-level slot positions for an item in a container.
- * @param container - Target container.
- * @param item - Item dimensions.
- * @returns Floor slot positions.
- */
-export declare function enumerate_floor_slots(container: StabilizerContainer, item: StabilizerItem): {
-    x: number;
-    y: number;
-    z: number;
-}[];
 /**
  * Validates geometry and waypoint constraints for a candidate position.
  * @param context - Candidate generation context.

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

@@ -1 +1 @@
-{"version":3,"file":"candidate_validation.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/candidate_validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,kDAAkD,CAAA;AAK3G,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAIxE;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACjC,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE,cAAc,GACrB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,CAevC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,0BAA0B,EACnC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAOT"}
+{"version":3,"file":"candidate_validation.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/candidate_validation.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAExE;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,0BAA0B,EACnC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAWT"}

package/build/core/candidates/candidate_validation.js

@@ -1,25 +1,8 @@
 import { collect_container_boxes } from '../adapters/coordinate_mapper.js';
-import { has_overlap, is_on_floor } from '../geometry/box_geometry.js';
+import { has_overlap, is_fully_supported, is_inside_container } from '../geometry/box_geometry.js';
 import { is_position_in_zone } from '../waypoint/build_waypoint_zones.js';
+import { is_position_in_milkrun_reserved_band } from '../waypoint/milkrun_wall_reservation.js';
 import { resolve_item_waypoint_id } from '../waypoint/validate_waypoint_ids.js';
-const POSITION_STEP = 0.05;
-/**
- * Enumerates floor-level slot positions for an item in a container.
- * @param container - Target container.
- * @param item - Item dimensions.
- * @returns Floor slot positions.
- */
-export function enumerate_floor_slots(container, item) {
-    const slots = [];
-    const max_x = container.largura - item.w;
-    const max_z = container.comprimento - item.d;
-    for (let z = 0; z <= max_z + 1e-6; z += POSITION_STEP) {
-        for (let x = 0; x <= max_x + 1e-6; x += POSITION_STEP) {
-            slots.push({ x, y: 0, z });
-        }
-    }
-    return slots;
-}
 /**
  * Validates geometry and waypoint constraints for a candidate position.
  * @param context - Candidate generation context.
@@ -31,26 +14,49 @@ export function is_candidate_valid(context, target_index, position) {
     if (!is_candidate_geometry_valid(context, target_index, position)) {
         return false;
     }
+    if (!is_candidate_milkrun_valid(context, target_index, position)) {
+        return false;
+    }
     return is_candidate_waypoint_valid(context, target_index, position);
 }
+function is_candidate_milkrun_valid(context, target_index, position) {
+    if (context.milkrun_reserved_z_bands.length === 0) {
+        return true;
+    }
+    return !is_position_in_milkrun_reserved_band({
+        bands: context.milkrun_reserved_z_bands,
+        container_index: target_index,
+        item: context.loose.item,
+        position
+    });
+}
 function is_candidate_geometry_valid(context, target_index, position) {
+    const candidate_box = build_candidate_box(context, position);
     const target = context.containers[target_index];
-    const candidate_box = {
+    const boxes = collect_container_boxes(target, context.loose.item_id);
+    return is_valid_candidate_box(candidate_box, target, boxes);
+}
+function build_candidate_box(context, position) {
+    return {
         x: position.x,
         y: position.y,
         z: position.z,
-        w: context.loose.item.w,
-        h: context.loose.item.h,
-        d: context.loose.item.d
+        w: context.loose.item.width,
+        h: context.loose.item.height,
+        d: context.loose.item.depth
     };
-    if (!is_on_floor(candidate_box)) {
+}
+function is_valid_candidate_box(candidate_box, target, boxes) {
+    if (!is_inside_container(candidate_box, target)) {
+        return false;
+    }
+    if (!is_fully_supported(candidate_box, boxes)) {
         return false;
     }
-    const boxes = collect_container_boxes(target, context.loose.item_id);
     return !has_overlap(candidate_box, boxes);
 }
 function is_candidate_waypoint_valid(context, target_index, position) {
-    if (context.mode.kind === 'SINGLE_WAYPOINT') {
+    if (context.mode.kind === 'SINGLE_WAYPOINT' || !context.preserve_tie_block_organization) {
         return true;
     }
     const waypoint_id = resolve_item_waypoint_id(context.loose.item, context.mode);

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

@@ -0,0 +1,15 @@
+import type { StabilizerContainer, StabilizerItem } from '../validation/contract/stabilizer_domain_schema.js';
+export interface EmptySpaceSlot {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Enumerates candidate positions from empty-space regions where the item fits.
+ * @param container - Target container layout.
+ * @param item - Loose item dimensions.
+ * @param exclude_item_id - Item id to omit from obstacle list.
+ * @returns Slot positions at each fitting empty-space origin.
+ */
+export declare function enumerate_empty_space_slots(container: StabilizerContainer, item: StabilizerItem, exclude_item_id: string): EmptySpaceSlot[];
+//# sourceMappingURL=enumerate_empty_space_slots.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"enumerate_empty_space_slots.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/enumerate_empty_space_slots.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AAG7G,MAAM,WAAW,cAAc;IAE3B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACvC,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE,cAAc,EACpB,eAAe,EAAE,MAAM,GACxB,cAAc,EAAE,CAmBlB"}