@jetta/cargo-stabilizer 0.1.0-7 → 0.1.0-9

package/CHANGELOG.md

@@ -11,6 +11,8 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - 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.
 - Public contract exports: `parse_stabilizer_input`, `parse_stabilizer_output`, `safe_parse_stabilizer_input`, `safe_parse_stabilizer_output`, and related domain types.
 
 ### Changed

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 candidate slots from empty-space regions for a loose item.
+ * Generates ranked candidate slots from empty-space regions and supporter tops.
  * @param context - Candidate generation context.
  * @returns Candidate moves sorted floor-first, same container preferred.
  */

package/build/core/candidates/candidate_generator.js

@@ -1,8 +1,8 @@
-import { enumerate_empty_space_slots } from './enumerate_empty_space_slots.js';
+import { collect_container_slots } from './collect_container_slots.js';
 import { is_candidate_valid } from './candidate_validation.js';
 import { rank_candidates } from './rank_candidates.js';
 /**
- * Generates ranked candidate slots from empty-space regions for a loose item.
+ * Generates ranked candidate slots from empty-space regions and supporter tops.
  * @param context - Candidate generation context.
  * @returns Candidate moves sorted floor-first, same container preferred.
  */
@@ -11,18 +11,32 @@ export function generate_candidates(context) {
     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 = [];
-    for (const position of slots) {
-        if (!is_candidate_valid(context, target_index, position)) {
+    for (const tagged of collect_container_slots(container, context.loose.item, context.loose.item_id)) {
+        if (!is_candidate_valid(context, target_index, tagged.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
+            new_position: tagged.position,
+            slot_kind: tagged.slot_kind
         });
     }
-    return candidates;
+    return unique_kind_positions(candidates);
+}
+function unique_kind_positions(candidates) {
+    const seen = new Set();
+    const unique = [];
+    for (const candidate of candidates) {
+        const position = candidate.new_position;
+        const key = `${position.x}:${position.y}:${position.z}:${candidate.target_container_index}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(candidate);
+    }
+    return unique;
 }

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;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"}
+{"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"}

package/build/core/candidates/candidate_validation.js

@@ -3,6 +3,7 @@ import { has_overlap, is_fully_supported, is_inside_container } from '../geometr
 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';
 /**
  * Validates geometry and waypoint constraints for a candidate position.
  * @param context - Candidate generation context.
@@ -14,6 +15,9 @@ export function is_candidate_valid(context, target_index, position) {
     if (!is_candidate_geometry_valid(context, target_index, position)) {
         return false;
     }
+    if (!is_elevated_on_supporter_origin(context, target_index, position)) {
+        return false;
+    }
     if (!is_candidate_milkrun_valid(context, target_index, position)) {
         return false;
     }

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

@@ -0,0 +1,16 @@
+import type { StabilizerContainer } from '../validation/contract/stabilizer_domain_schema.js';
+import type { CandidateSlotKind } from '../move/apply_move.js';
+import type { EmptySpaceSlot } from './enumerate_empty_space_slots.js';
+export interface TaggedSlot {
+    position: EmptySpaceSlot;
+    slot_kind: CandidateSlotKind;
+}
+/**
+ * Collects empty-space origins and per-supporter top origins, supporter first.
+ * @param container - Target container layout.
+ * @param item - Loose item to place.
+ * @param exclude_item_id - Loose item id omitted from obstacles and supporters.
+ * @returns Tagged slots with supporter-top entries before empty-space entries.
+ */
+export declare function collect_container_slots(container: StabilizerContainer, item: StabilizerContainer['items'][number], exclude_item_id: string): TaggedSlot[];
+//# sourceMappingURL=collect_container_slots.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collect_container_slots.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/collect_container_slots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAA;AAC7F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AAItE,MAAM,WAAW,UAAU;IAEvB,QAAQ,EAAE,cAAc,CAAA;IACxB,SAAS,EAAE,iBAAiB,CAAA;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACnC,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,EAC1C,eAAe,EAAE,MAAM,GACxB,UAAU,EAAE,CAQd"}

package/build/core/candidates/collect_container_slots.js

@@ -0,0 +1,20 @@
+import { enumerate_empty_space_slots } from './enumerate_empty_space_slots.js';
+import { enumerate_supporter_top_slots } from './enumerate_supporter_top_slots.js';
+/**
+ * Collects empty-space origins and per-supporter top origins, supporter first.
+ * @param container - Target container layout.
+ * @param item - Loose item to place.
+ * @param exclude_item_id - Loose item id omitted from obstacles and supporters.
+ * @returns Tagged slots with supporter-top entries before empty-space entries.
+ */
+export function collect_container_slots(container, item, exclude_item_id) {
+    const supporter = enumerate_supporter_top_slots(container, item, exclude_item_id);
+    const empty = enumerate_empty_space_slots(container, item, exclude_item_id);
+    return [
+        ...tag_slots(supporter, 'supporter_top'),
+        ...tag_slots(empty, 'empty_space')
+    ];
+}
+function tag_slots(slots, slot_kind) {
+    return slots.map(position => ({ position, slot_kind }));
+}

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

@@ -0,0 +1,11 @@
+import type { StabilizerContainer, StabilizerItem } from '../validation/contract/stabilizer_domain_schema.js';
+import type { EmptySpaceSlot } from './enumerate_empty_space_slots.js';
+/**
+ * Emits one candidate origin per supporter footprint (x, supporter top y, z).
+ * @param container - Target container layout.
+ * @param item - Loose item dimensions.
+ * @param exclude_item_id - Loose item id omitted as a supporter.
+ * @returns Slot positions aligned to each supporter origin.
+ */
+export declare function enumerate_supporter_top_slots(container: StabilizerContainer, item: StabilizerItem, exclude_item_id: string): EmptySpaceSlot[];
+//# sourceMappingURL=enumerate_supporter_top_slots.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"enumerate_supporter_top_slots.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/enumerate_supporter_top_slots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AAC7G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AAItE;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CACzC,SAAS,EAAE,mBAAmB,EAC9B,IAAI,EAAE,cAAc,EACpB,eAAe,EAAE,MAAM,GACxB,cAAc,EAAE,CAgBlB"}

package/build/core/candidates/enumerate_supporter_top_slots.js

@@ -0,0 +1,36 @@
+const CONTAINER_EPSILON = 1e-6;
+/**
+ * Emits one candidate origin per supporter footprint (x, supporter top y, z).
+ * @param container - Target container layout.
+ * @param item - Loose item dimensions.
+ * @param exclude_item_id - Loose item id omitted as a supporter.
+ * @returns Slot positions aligned to each supporter origin.
+ */
+export function enumerate_supporter_top_slots(container, item, exclude_item_id) {
+    const slots = [];
+    for (const supporter of container.items) {
+        if (supporter.item_id === exclude_item_id) {
+            continue;
+        }
+        const slot = supporter_top_slot(supporter);
+        if (slot_fits_in_container(container, item, slot)) {
+            slots.push(slot);
+        }
+    }
+    return slots;
+}
+function supporter_top_slot(supporter) {
+    return {
+        x: supporter.x,
+        y: supporter.y + supporter.height,
+        z: supporter.z
+    };
+}
+function slot_fits_in_container(container, item, slot) {
+    return slot.x >= -CONTAINER_EPSILON &&
+        slot.y >= -CONTAINER_EPSILON &&
+        slot.z >= -CONTAINER_EPSILON &&
+        slot.x + item.width <= container.width + CONTAINER_EPSILON &&
+        slot.y + item.height <= container.height + CONTAINER_EPSILON &&
+        slot.z + item.depth <= container.length + CONTAINER_EPSILON;
+}

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

@@ -0,0 +1,14 @@
+import type { CandidateGenerationContext } from './candidate_context.js';
+/**
+ * Floor candidates stay free; elevated ones must copy a supporter (x, z) origin.
+ * @param context - Candidate generation context.
+ * @param target_index - Target container index.
+ * @param position - Candidate position.
+ * @returns True when the candidate is on the floor or on a supporter origin.
+ */
+export declare function is_elevated_on_supporter_origin(context: CandidateGenerationContext, target_index: number, position: {
+    x: number;
+    y: number;
+    z: number;
+}): boolean;
+//# sourceMappingURL=is_elevated_on_supporter_origin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"is_elevated_on_supporter_origin.d.ts","sourceRoot":"","sources":["../../../src/core/candidates/is_elevated_on_supporter_origin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA;AAIxE;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC3C,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,CAQT"}

package/build/core/candidates/is_elevated_on_supporter_origin.js

@@ -0,0 +1,28 @@
+const ORIGIN_EPSILON = 1e-6;
+/**
+ * Floor candidates stay free; elevated ones must copy a supporter (x, z) origin.
+ * @param context - Candidate generation context.
+ * @param target_index - Target container index.
+ * @param position - Candidate position.
+ * @returns True when the candidate is on the floor or on a supporter origin.
+ */
+export function is_elevated_on_supporter_origin(context, target_index, position) {
+    if (position.y <= ORIGIN_EPSILON) {
+        return true;
+    }
+    const items = context.containers[target_index].items;
+    return items.some(item => matches_supporter_origin(item, context.loose.item_id, position));
+}
+function matches_supporter_origin(item, exclude_item_id, position) {
+    if (item.item_id === exclude_item_id) {
+        return false;
+    }
+    return is_same_origin(item, position) && is_supporter_top(item, position.y);
+}
+function is_same_origin(item, position) {
+    return Math.abs(item.x - position.x) <= ORIGIN_EPSILON
+        && Math.abs(item.z - position.z) <= ORIGIN_EPSILON;
+}
+function is_supporter_top(item, candidate_y) {
+    return Math.abs(item.y + item.height - candidate_y) <= ORIGIN_EPSILON;
+}

package/build/core/move/apply_move.d.ts

@@ -1,4 +1,5 @@
 import type { StabilizerContainer } from '../validation/contract/stabilizer_domain_schema.js';
+export type CandidateSlotKind = 'empty_space' | 'supporter_top';
 export interface MoveCandidate {
     item_id: string;
     source_container_index: number;
@@ -8,6 +9,7 @@ export interface MoveCandidate {
         y: number;
         z: number;
     };
+    slot_kind?: CandidateSlotKind;
 }
 /**
  * Applies a move candidate to containers (mutates arrays in place).

package/build/core/move/apply_move.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply_move.d.ts","sourceRoot":"","sources":["../../../src/core/move/apply_move.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAA;AAE7F,MAAM,WAAW,aAAa;IAE1B,OAAO,EAAE,MAAM,CAAA;IACf,sBAAsB,EAAE,MAAM,CAAA;IAC9B,sBAAsB,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACpD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACtB,UAAU,EAAE,mBAAmB,EAAE,EACjC,SAAS,EAAE,aAAa,GACzB,IAAI,CAgBN;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CAGzF"}
+{"version":3,"file":"apply_move.d.ts","sourceRoot":"","sources":["../../../src/core/move/apply_move.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oDAAoD,CAAA;AAE7F,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,eAAe,CAAA;AAE/D,MAAM,WAAW,aAAa;IAE1B,OAAO,EAAE,MAAM,CAAA;IACf,sBAAsB,EAAE,MAAM,CAAA;IAC9B,sBAAsB,EAAE,MAAM,CAAA;IAC9B,YAAY,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACjD,SAAS,CAAC,EAAE,iBAAiB,CAAA;CAChC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACtB,UAAU,EAAE,mBAAmB,EAAE,EACjC,SAAS,EAAE,aAAa,GACzB,IAAI,CAgBN;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CAGzF"}

package/build/core/strategies/reorder/BeamSearchReorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BeamSearchReorder.d.ts","sourceRoot":"","sources":["../../../../src/core/strategies/reorder/BeamSearchReorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAA;AAYhG;;GAEG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IAErD,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,mBAAmB,EAAE;CAkBtD"}
+{"version":3,"file":"BeamSearchReorder.d.ts","sourceRoot":"","sources":["../../../../src/core/strategies/reorder/BeamSearchReorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAA;AAahG;;GAEG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IAErD,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,mBAAmB,EAAE;CAkBtD"}

package/build/core/strategies/reorder/BeamSearchReorder.js

@@ -1,5 +1,6 @@
 import { generate_candidates } from '../../candidates/candidate_generator.js';
 import { candidate_context_for_loose } from '../../candidates/build_candidate_context.js';
+import { select_beam_expansion_candidates } from './select_beam_expansion_candidates.js';
 import { apply_move, clone_containers } from '../../move/apply_move.js';
 import { evaluate_trial_layout, evaluation_context_from_reorder } from '../../evaluation/state_evaluator.js';
 import { read_item_score } from '../../adapters/stability_adapter.js';
@@ -39,7 +40,7 @@ function expand_beam(request) {
 function append_beam_branches(beam_context) {
     const { reorder, evaluation, expanded, state, loose } = beam_context;
     const loose_ref = { ...loose, container_index: find_container_index(state.containers, loose.item_id) };
-    const candidates = generate_candidates(candidate_context_for_loose(reorder, state.containers, loose_ref)).slice(0, reorder.config.beam_top_k);
+    const candidates = select_beam_expansion_candidates(generate_candidates(candidate_context_for_loose(reorder, state.containers, loose_ref)), reorder.config.beam_top_k);
     for (const candidate of candidates) {
         const trial = clone_containers(state.containers);
         apply_move(trial, candidate);

package/build/core/strategies/reorder/select_beam_expansion_candidates.d.ts

@@ -0,0 +1,9 @@
+import type { MoveCandidate } from '../../move/apply_move.js';
+/**
+ * Selects beam expansions: ranked top_k plus every supporter-top slot.
+ * @param ranked - Candidates already ranked floor-first.
+ * @param top_k - Beam top-k from config.
+ * @returns Candidates for trial evaluation.
+ */
+export declare function select_beam_expansion_candidates(ranked: MoveCandidate[], top_k: number): MoveCandidate[];
+//# sourceMappingURL=select_beam_expansion_candidates.d.ts.map

package/build/core/strategies/reorder/select_beam_expansion_candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select_beam_expansion_candidates.d.ts","sourceRoot":"","sources":["../../../../src/core/strategies/reorder/select_beam_expansion_candidates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAE7D;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC5C,MAAM,EAAE,aAAa,EAAE,EACvB,KAAK,EAAE,MAAM,GACd,aAAa,EAAE,CAKjB"}

package/build/core/strategies/reorder/select_beam_expansion_candidates.js

@@ -0,0 +1,28 @@
+/**
+ * Selects beam expansions: ranked top_k plus every supporter-top slot.
+ * @param ranked - Candidates already ranked floor-first.
+ * @param top_k - Beam top-k from config.
+ * @returns Candidates for trial evaluation.
+ */
+export function select_beam_expansion_candidates(ranked, top_k) {
+    const leading = ranked.slice(0, top_k);
+    const supporter_top = ranked.filter(candidate => candidate.slot_kind === 'supporter_top');
+    return unique_move_positions([...leading, ...supporter_top]);
+}
+function unique_move_positions(candidates) {
+    const seen = new Set();
+    const unique = [];
+    for (const candidate of candidates) {
+        const key = position_key(candidate);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(candidate);
+    }
+    return unique;
+}
+function position_key(candidate) {
+    const position = candidate.new_position;
+    return `${position.x}:${position.y}:${position.z}:${candidate.target_container_index}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jetta/cargo-stabilizer",
-    "version": "0.1.0-7",
+    "version": "0.1.0-9",
     "description": "Stable loose-item reorder library for cargo-movement (JET-2262)",
     "main": "build/index.js",
     "types": "build/index.d.ts",