@jetta/cargo-stabilizer 0.1.0-9 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @jetta/cargo-stabilizer
 
-TypeScript library that reorders **loose items only** to improve **whole-cargo transport stability** while keeping compound blocks pinned. 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).
+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
 
@@ -14,7 +14,7 @@ npm ci
 npm run build
 ```
 
-Local monorepo development uses `file:` links to `cargo-stability`, `@jetta/axle-load-calculator`, and `@jetta/empty-spaces-manager`.
+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
 
@@ -49,21 +49,23 @@ 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.
+`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` | `weight` |
+| `peso` / `wg` | `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`.
+Flow: `map_wire_input_to_contract` → strict Zod parse → `run_stabilize` → output validation.
 
-Exported parsers: `parse_stabilizer_input`, `parse_stabilizer_output`, `safe_parse_*`.
+Exported parsers: `parse_stabilizer_input`, `parse_stabilizer_output`, `safe_parse_*`, `run_stabilize`.
 
 ## Configuration
 
@@ -73,6 +75,7 @@ Exported parsers: `parse_stabilizer_input`, `parse_stabilizer_output`, `safe_par
 | `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 |
@@ -95,6 +98,8 @@ 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
 
@@ -102,7 +107,7 @@ Runtime integrations (all declared in `package.json`):
 
 | Command | Description |
 |---------|-------------|
-| `npm test` | Mocha tests (126 cases) |
+| `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) |
@@ -111,11 +116,11 @@ Runtime integrations (all declared in `package.json`):
 
 ## Layout
 
-- `src/index.ts` — public API (`stabilize`)
+- `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
-- `src/core/candidates/` — empty-space slot discovery and candidate ranking
+- `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
@@ -138,6 +143,7 @@ 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 test -- --grep "is_search_trial_admissible"
+npm test -- --grep "is_candidate_stacking_valid"
 npm run coverage
 ```

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

@@ -8,6 +8,7 @@ import type { StabilizerEnv } from '../validation/contract/stabilizer_domain_sch
 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.
+ * Layout overlap from the calculator is a failed gate, not a skip of kg checks.
  * @param env - Stabilizer env with containers and axles.
  * @param folga_pct - Axle load margin percent.
  * @returns True when all axles are within limits.

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,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"}
+{"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;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAGjF"}

package/build/core/adapters/axle_adapter.js

@@ -1,4 +1,4 @@
-import { run_axle_calculator } from './run_axle_calculator.js';
+import { evaluate_axle_load } from './evaluate_axle_load.js';
 /**
  * @param final_kg - Loaded weight including tare.
  * @param max_kg - Axle supported max.
@@ -10,26 +10,11 @@ export function exceeds_with_folga(final_kg, max_kg, folga_pct) {
 }
 /**
  * Validates axle loads for an env using axle-load-calculator.
+ * Layout overlap from the calculator is a failed gate, not a skip of kg checks.
  * @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);
-    });
+    return evaluate_axle_load(env, folga_pct).valid;
 }

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

@@ -0,0 +1,8 @@
+/**
+ * Result of one axle-load calculator pass.
+ */
+export interface AxleLoadEvaluation {
+    valid: boolean;
+    excess_kg: number;
+}
+//# sourceMappingURL=axle_load_evaluation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"axle_load_evaluation.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/axle_load_evaluation.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAE/B,KAAK,EAAE,OAAO,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CACpB"}

package/build/core/adapters/axle_load_evaluation.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,14 +1,7 @@
 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.
+ * Builds the axle-load-calculator request from typed stabilizer env fields.
+ * @param env - Stabilizer env with containers, vehicle, and axles.
  * @returns Calculator request payload.
  */
 export declare function build_axle_request(env: StabilizerEnv): Record<string, unknown>;

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

@@ -1 +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"}
+{"version":3,"file":"build_axle_request.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/build_axle_request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAER,aAAa,EAGhB,MAAM,oDAAoD,CAAA;AAE3D;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkB9E"}

package/build/core/adapters/build_axle_request.js

@@ -1,36 +1,64 @@
-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.
+ * Builds the axle-load-calculator request from typed stabilizer env fields.
+ * @param env - Stabilizer env with containers, vehicle, 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 };
+    const wire_env = {
+        ...map_vehicle_to_wire(env.vehicle),
+        containers: env.containers.map(map_container_to_axle_wire)
+    };
+    if (env.axles !== undefined) {
+        wire_env.eixos = env.axles.map(axle => ({
+            distanciaOrigem: axle.distance_from_origin,
+            pesoMaxSuportado: axle.max_supported_weight,
+            pesoDnit: axle.dnit_weight,
+            tara: axle.tare,
+            sequenciaContainer: axle.container_sequence,
+            sequence: axle.sequence
+        }));
+    }
+    return { envs: [wire_env] };
 }
-function stamp_container_physics_aliases(wire_container, container) {
-    const wire_items = (wire_container.items ?? []);
+function map_vehicle_to_wire(vehicle) {
+    if (vehicle === undefined) {
+        return {};
+    }
     return {
-        ...wire_container,
-        items: wire_items.map((wire_item, index) => stamp_item_physics_aliases(wire_item, container?.items[index]))
+        _id: vehicle.vehicle_id,
+        tipoVeiculo: vehicle.vehicle_type,
+        tipoVersao: vehicle.version_type,
+        tipoSuspensao: vehicle.suspension_type,
+        primeiroEixo: vehicle.first_axle,
+        tara: vehicle.tare,
+        pesoMaxSuportado: vehicle.max_supported_weight,
+        qtd: vehicle.quantity
     };
 }
-function stamp_item_physics_aliases(wire_item, item) {
-    if (item === undefined) {
-        return wire_item;
-    }
+function map_container_to_axle_wire(container) {
+    return {
+        sequencia: container.sequence,
+        largura: container.width,
+        altura: container.height,
+        comprimento: container.length,
+        distPinoRei: container.kingpin_distance,
+        containerDistanceAhead: container.container_distance_ahead,
+        pesoMaxSuportado: container.max_supported_weight,
+        tara: container.tare,
+        pesoDeCarga: container.cargo_weight,
+        grouper: container.grouper,
+        items: container.items.map(map_item_to_axle_wire)
+    };
+}
+function map_item_to_axle_wire(item) {
     return {
-        ...wire_item,
+        _id: item.item_id,
+        x: item.x,
+        y: item.z,
+        z: item.y,
+        w: item.width,
+        h: item.height,
+        d: item.depth,
         peso: item.weight ?? 0,
         largura: item.width,
         altura: item.height,

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

@@ -0,0 +1,8 @@
+/**
+ * Sums kilograms over the folga limit across container axle rows.
+ * @param axles - Calculator pesoEixos rows.
+ * @param folga_pct - Axle load margin percent.
+ * @returns Total excess kilograms; zero when all axles are within limits.
+ */
+export declare function compute_axle_excess_kg(axles: Record<string, unknown>[], folga_pct: number): number;
+//# sourceMappingURL=compute_axle_excess_kg.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compute_axle_excess_kg.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/compute_axle_excess_kg.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAChC,SAAS,EAAE,MAAM,GAClB,MAAM,CAQR"}

package/build/core/adapters/compute_axle_excess_kg.js

@@ -0,0 +1,19 @@
+/**
+ * Sums kilograms over the folga limit across container axle rows.
+ * @param axles - Calculator pesoEixos rows.
+ * @param folga_pct - Axle load margin percent.
+ * @returns Total excess kilograms; zero when all axles are within limits.
+ */
+export function compute_axle_excess_kg(axles, folga_pct) {
+    let excess_kg = 0;
+    for (const axle of axles) {
+        excess_kg += axle_row_excess_kg(axle, folga_pct);
+    }
+    return excess_kg;
+}
+function axle_row_excess_kg(axle, folga_pct) {
+    const final_kg = Number(axle.pesoCarregadoFinal ?? 0);
+    const max_kg = Number(axle.pesoMaxFinal ?? 0);
+    const limit_kg = max_kg * (1 + folga_pct / 100);
+    return Math.max(0, final_kg - limit_kg);
+}

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

@@ -15,7 +15,7 @@ export interface StabilityContainerPayload {
     item_list: StabilityItemPayload[];
 }
 /**
- * Maps contract coordinates to cargo-stability payload coordinates.
+ * Maps contract coordinates onto cargo-stability axes (y = height, z = length).
  * @param item - Stabilizer item record.
  * @returns Stability item payload entry.
  */

package/build/core/adapters/coordinate_mapper.js

@@ -1,14 +1,14 @@
 import { item_to_box } from '../geometry/box_geometry.js';
 /**
- * Maps contract coordinates to cargo-stability payload coordinates.
+ * Maps contract coordinates onto cargo-stability axes (y = height, z = length).
  * @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,
+        y: item.y,
+        z: item.z,
         w: item.width,
         h: item.height,
         l: item.depth

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

@@ -0,0 +1,10 @@
+import type { StabilizerEnv } from '../validation/contract/stabilizer_domain_schema.js';
+import type { AxleLoadEvaluation } from './axle_load_evaluation.js';
+/**
+ * Evaluates axle legality and excess kilograms in one calculator pass.
+ * @param env - Stabilizer env with containers and axles.
+ * @param folga_pct - Axle load margin percent.
+ * @returns Validity and excess over the folga-adjusted max.
+ */
+export declare function evaluate_axle_load(env: StabilizerEnv, folga_pct: number): AxleLoadEvaluation;
+//# sourceMappingURL=evaluate_axle_load.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate_axle_load.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/evaluate_axle_load.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oDAAoD,CAAA;AACvF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAEnE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,kBAAkB,CAc5F"}

package/build/core/adapters/evaluate_axle_load.js

@@ -0,0 +1,32 @@
+import { run_axle_calculator } from './run_axle_calculator.js';
+import { compute_axle_excess_kg } from './compute_axle_excess_kg.js';
+/**
+ * Evaluates axle legality and excess kilograms in one calculator pass.
+ * @param env - Stabilizer env with containers and axles.
+ * @param folga_pct - Axle load margin percent.
+ * @returns Validity and excess over the folga-adjusted max.
+ */
+export function evaluate_axle_load(env, folga_pct) {
+    if (!env.axles || env.axles.length === 0) {
+        return { valid: true, excess_kg: 0 };
+    }
+    const result = run_axle_calculator(env);
+    if (!result.calculated) {
+        return { valid: false, excess_kg: Number.POSITIVE_INFINITY };
+    }
+    return evaluation_from_calculated_env(result.env, folga_pct);
+}
+function evaluation_from_calculated_env(calculated_env, folga_pct) {
+    const containers = (calculated_env.containers ?? []);
+    const axles = collect_container_axle_rows(containers);
+    const excess_kg = compute_axle_excess_kg(axles, folga_pct);
+    return { valid: excess_kg === 0, excess_kg };
+}
+function collect_container_axle_rows(containers) {
+    const rows = [];
+    for (const container of containers) {
+        const axles = (container.pesoEixos ?? []);
+        rows.push(...axles);
+    }
+    return rows;
+}

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

@@ -0,0 +1,14 @@
+import { type Item } from '@jetta/stacking-constraints';
+import type { StabilizerItem } from '../validation/contract/stabilizer_domain_schema.js';
+/**
+ * Maps a stabilizer item onto a stacking-constraints Item.
+ * @param item - Stabilizer item.
+ * @param position - Optional pose override for a candidate slot.
+ * @returns Stacking-constraints item.
+ */
+export declare function map_item_to_stacking_item(item: StabilizerItem, position?: {
+    x: number;
+    y: number;
+    z: number;
+}): Item;
+//# sourceMappingURL=map_item_to_stacking_item.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"map_item_to_stacking_item.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/map_item_to_stacking_item.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,IAAI,EAAsB,MAAM,6BAA6B,CAAA;AACnG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AAKxF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACrC,IAAI,EAAE,cAAc,EACpB,QAAQ,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,IAAI,CAYN"}

package/build/core/adapters/map_item_to_stacking_item.js

@@ -0,0 +1,40 @@
+import { default_stacking_rules } from '@jetta/stacking-constraints';
+const ALLOWED_FAMILIES_CONSTRAINT = 'ALLOWED_FAMILIES';
+const SUPPORTED_WEIGHT_UNIT = 'supportedWeight';
+/**
+ * Maps a stabilizer item onto a stacking-constraints Item.
+ * @param item - Stabilizer item.
+ * @param position - Optional pose override for a candidate slot.
+ * @returns Stacking-constraints item.
+ */
+export function map_item_to_stacking_item(item, position) {
+    return {
+        itemId: item.item_id,
+        x: position?.x ?? item.x,
+        y: position?.y ?? item.y,
+        z: position?.z ?? item.z,
+        width: item.width,
+        height: item.height,
+        length: item.depth,
+        stackingRules: build_stacking_rules(item)
+    };
+}
+function build_stacking_rules(item) {
+    const rules = default_stacking_rules();
+    return {
+        ...rules,
+        family: item.family ?? rules.family,
+        allowedFamilies: item.supported_families ?? [...rules.allowedFamilies],
+        enableOnlyAllowedFamilies: is_family_constraint_enabled(item),
+        weight: item.weight !== undefined && item.weight > 0 ? item.weight : rules.weight,
+        enableMaximumStackingWeight: item.stacking_unit === SUPPORTED_WEIGHT_UNIT,
+        maximumStackingWeight: item.supported_weight ?? rules.maximumStackingWeight,
+        enableStackSameItemOnly: item.stack_same_item === true,
+        enableStackSameAreaOnly: item.stack_same_area === true,
+        priority: item.priority ?? rules.priority,
+        ...(item.waypoint_id !== undefined ? { waypoint_id: item.waypoint_id } : {})
+    };
+}
+function is_family_constraint_enabled(item) {
+    return item.constraint === ALLOWED_FAMILIES_CONSTRAINT || item.stack_families === true;
+}

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

@@ -1 +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"}
+{"version":3,"file":"run_axle_calculator.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/run_axle_calculator.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oDAAoD,CAAA;AAEvF,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,CAW5E"}

package/build/core/adapters/run_axle_calculator.js

@@ -1,13 +1,7 @@
-import { calculate_weight_on_axles_physics } from '@jetta/axle-load-calculator';
+import { calculate_weight_on_axles_physics, ItemOverlapError } 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.
@@ -16,17 +10,28 @@ const LAYOUT_REJECTION_MESSAGES = Object.freeze(['Item overlap error']);
  */
 export function run_axle_calculator(env) {
     const request = build_axle_request(env);
-    const output = JSON.parse(calculate_weight_on_axles_physics(JSON.stringify(request)));
+    try {
+        return calculated_env_from_physics(request);
+    }
+    catch (error) {
+        return handle_calculator_failure(error);
+    }
+}
+function calculated_env_from_physics(request) {
+    const output = calculate_weight_on_axles_physics(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 };
+    throw new AxleCalculationError('calculator returned no envs');
 }
-function is_layout_rejection(reason) {
-    return LAYOUT_REJECTION_MESSAGES.some(message => reason.includes(message));
+function handle_calculator_failure(error) {
+    if (error instanceof ItemOverlapError) {
+        stabilizer_logger.debug('axle gate rejected candidate layout: ' + error.message);
+        return { calculated: false, reason: error.message };
+    }
+    if (error instanceof AxleCalculationError) {
+        throw error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new AxleCalculationError(message);
 }

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":"AAUA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAGxE;;;;;;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,CAeT"}
+{"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;AAIxE;;;;;;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,CAmBT"}

package/build/core/candidates/candidate_validation.js

@@ -4,6 +4,7 @@ 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';
 import { is_elevated_on_supporter_origin } from './is_elevated_on_supporter_origin.js';
+import { is_candidate_stacking_valid } from './is_candidate_stacking_valid.js';
 /**
  * Validates geometry and waypoint constraints for a candidate position.
  * @param context - Candidate generation context.
@@ -21,6 +22,9 @@ export function is_candidate_valid(context, target_index, position) {
     if (!is_candidate_milkrun_valid(context, target_index, position)) {
         return false;
     }
+    if (!is_candidate_stacking_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) {

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

@@ -0,0 +1,14 @@
+import type { CandidateGenerationContext } from './candidate_context.js';
+/**
+ * Returns true when placing the loose item at position keeps stacking legal.
+ * @param context - Candidate generation context.
+ * @param target_index - Target container index.
+ * @param position - Candidate pose.
+ * @returns True when stacking-constraints accepts the pose.
+ */
+export declare function is_candidate_stacking_valid(context: CandidateGenerationContext, target_index: number, position: {
+    x: number;
+    y: number;
+    z: number;
+}): boolean;
+//# sourceMappingURL=is_candidate_stacking_valid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"is_candidate_stacking_valid.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/is_candidate_stacking_valid.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAIxE;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACvC,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,CAcT"}

package/build/core/candidates/is_candidate_stacking_valid.js

@@ -0,0 +1,43 @@
+import { StackingFeasibilityChecker } from '@jetta/stacking-constraints';
+import { map_item_to_stacking_item } from '../adapters/map_item_to_stacking_item.js';
+const Y_SUPPORT_EPSILON = 1e-6;
+/**
+ * Returns true when placing the loose item at position keeps stacking legal.
+ * @param context - Candidate generation context.
+ * @param target_index - Target container index.
+ * @param position - Candidate pose.
+ * @returns True when stacking-constraints accepts the pose.
+ */
+export function is_candidate_stacking_valid(context, target_index, position) {
+    const remaining = context.containers[target_index].items
+        .filter(item => item.item_id !== context.loose.item_id)
+        .map(item => map_item_to_stacking_item(item));
+    const mover = map_item_to_stacking_item(context.loose.item, position);
+    try {
+        return build_checker(remaining).clone().validate_stackings(mover);
+    }
+    catch {
+        return false;
+    }
+}
+function build_checker(remaining) {
+    if (remaining.length === 0) {
+        return new StackingFeasibilityChecker(1, { y_support_epsilon: Y_SUPPORT_EPSILON });
+    }
+    try {
+        return StackingFeasibilityChecker.from_allocated(remaining, {
+            y_support_epsilon: Y_SUPPORT_EPSILON
+        });
+    }
+    catch {
+        return hydrate_bottom_up(remaining);
+    }
+}
+function hydrate_bottom_up(remaining) {
+    const checker = new StackingFeasibilityChecker(1, { y_support_epsilon: Y_SUPPORT_EPSILON });
+    const ordered = [...remaining].sort((left, right) => left.y - right.y);
+    for (const item of ordered) {
+        checker.validate_stackings(item);
+    }
+    return checker;
+}

package/build/core/constants/TieRatioOrientation.d.ts

@@ -0,0 +1,6 @@
+export declare const TIE_RATIO_ORIENTATION: Readonly<{
+    THREE_TWO: "3_2";
+    TWO_THREE: "2_3";
+}>;
+export declare const TIE_RATIO_ORIENTATION_VALUES: readonly ("3_2" | "2_3")[];
+//# sourceMappingURL=TieRatioOrientation.d.ts.map

package/build/core/constants/TieRatioOrientation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TieRatioOrientation.d.ts","sourceRoot":"","sources":["../../../src/core/constants/TieRatioOrientation.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB;;;EAGhC,CAAA;AAEF,eAAO,MAAM,4BAA4B,4BAExC,CAAA"}

package/build/core/constants/TieRatioOrientation.js

@@ -0,0 +1,5 @@
+export const TIE_RATIO_ORIENTATION = Object.freeze({
+    THREE_TWO: '3_2',
+    TWO_THREE: '2_3'
+});
+export const TIE_RATIO_ORIENTATION_VALUES = Object.freeze(Object.values(TIE_RATIO_ORIENTATION));

package/build/core/evaluation/compare_search_states.d.ts

@@ -0,0 +1,12 @@
+export interface SearchRankFields {
+    axle_excess_kg: number;
+    objective: number;
+}
+/**
+ * Ranks search states: lower axle excess first, then higher stability objective.
+ * @param left - Left state.
+ * @param right - Right state.
+ * @returns Negative when left ranks ahead of right.
+ */
+export declare function compare_search_states(left: SearchRankFields, right: SearchRankFields): number;
+//# sourceMappingURL=compare_search_states.d.ts.map

package/build/core/evaluation/compare_search_states.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare_search_states.d.ts","sourceRoot":"","sources":["../../../src/core/evaluation/compare_search_states.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAE7B,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAO7F"}