@jetta/cargo-stabilizer 0.1.0-10

package/build/core/evaluation/state_evaluator.js

@@ -0,0 +1,95 @@
+import { try_evaluate_transport_stability } from '../adapters/stability_adapter.js';
+import { compute_reorder_objective } from './compute_reorder_objective.js';
+import { is_axle_load_valid } from '../adapters/axle_adapter.js';
+import { preserves_waypoint_order } from '../waypoint/preserves_waypoint_order.js';
+import { is_layout_milkrun_valid } from '../waypoint/milkrun_wall_reservation.js';
+import { clone_containers } from '../move/apply_move.js';
+/**
+ * Evaluates a container layout against all stabilizer gates.
+ * @param containers - Container layout to evaluate.
+ * @param context - Evaluation context.
+ * @returns Evaluation result with gate flags.
+ */
+export function evaluate_state(containers, context) {
+    const stability = try_evaluate_transport_stability(containers);
+    if (!stability) {
+        return invalid_evaluation_result();
+    }
+    const gates = evaluate_gates(containers, context, stability);
+    return { stability, objective: gates.objective, ...gates.flags, all_gates_pass: gates.pass };
+}
+/**
+ * Evaluates a trial layout cloned from baseline with a move applied elsewhere.
+ * @param trial - Trial containers after move.
+ * @param context - Evaluation context.
+ * @returns Evaluation result.
+ */
+export function evaluate_trial_layout(trial, context) {
+    return evaluate_state(trial, context);
+}
+/**
+ * Builds evaluation context from reorder context.
+ * @param context - Reorder context.
+ * @returns State evaluation context.
+ */
+export function evaluation_context_from_reorder(context) {
+    return {
+        env: context.env,
+        loose_items: context.loose_items,
+        config: context.config,
+        waypoint_mode: context.waypoint_mode,
+        baseline_containers: context.baseline_containers,
+        milkrun_reserved_z_bands: context.milkrun_reserved_z_bands
+    };
+}
+/**
+ * Clones baseline containers for safe trial mutation.
+ * @param containers - Source containers.
+ * @returns Deep clone.
+ */
+export function clone_baseline(containers) {
+    return clone_containers(containers);
+}
+function evaluate_gates(containers, context, stability) {
+    const objective = compute_reorder_objective(stability, containers, context.loose_items);
+    const transport_floor_valid = stability.transport_score >= context.config.transport_stability_floor;
+    const axle_valid = is_axle_load_valid({ ...context.env, containers }, context.config.axle_load_margin_percent);
+    const waypoint_valid = is_waypoint_order_valid(containers, context);
+    const milkrun_valid = is_layout_milkrun_valid(containers, context.milkrun_reserved_z_bands);
+    const flags = { transport_floor_valid, axle_valid, waypoint_valid, milkrun_valid };
+    return {
+        objective,
+        pass: transport_floor_valid && axle_valid && waypoint_valid && milkrun_valid,
+        flags
+    };
+}
+/**
+ * Evaluates organization constraint gates without stability or axle checks.
+ * @param containers - Container layout to evaluate.
+ * @param context - Evaluation context.
+ * @returns Waypoint and milkrun gate flags.
+ */
+export function evaluate_organization_gates(containers, context) {
+    return {
+        waypoint_valid: is_waypoint_order_valid(containers, context),
+        milkrun_valid: is_layout_milkrun_valid(containers, context.milkrun_reserved_z_bands)
+    };
+}
+function is_waypoint_order_valid(containers, context) {
+    if (context.waypoint_mode.kind === 'SINGLE_WAYPOINT' ||
+        !context.config.preserve_tie_block_organization) {
+        return true;
+    }
+    return preserves_waypoint_order(context.baseline_containers, containers, context.waypoint_mode);
+}
+function invalid_evaluation_result() {
+    return {
+        stability: { item_scores: [], container_scores: [], transport_score: 0 },
+        objective: Number.NEGATIVE_INFINITY,
+        transport_floor_valid: false,
+        axle_valid: false,
+        waypoint_valid: false,
+        milkrun_valid: false,
+        all_gates_pass: false
+    };
+}

package/build/core/exceptions/AxleCalculationError.d.ts

@@ -0,0 +1,4 @@
+export declare class AxleCalculationError extends Error {
+    constructor(reason: string);
+}
+//# sourceMappingURL=AxleCalculationError.d.ts.map

package/build/core/exceptions/AxleCalculationError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AxleCalculationError.d.ts","sourceRoot":"","sources":["../../../src/core/exceptions/AxleCalculationError.ts"],"names":[],"mappings":"AAAA,qBAAa,oBAAqB,SAAQ,KAAK;gBAE/B,MAAM,EAAE,MAAM;CAK7B"}

package/build/core/exceptions/AxleCalculationError.js

@@ -0,0 +1,6 @@
+export class AxleCalculationError extends Error {
+    constructor(reason) {
+        super('Axle load calculation failed: ' + reason);
+        this.name = 'AxleCalculationError';
+    }
+}

package/build/core/exceptions/InvalidStabilizerInputError.d.ts

@@ -0,0 +1,4 @@
+export declare class InvalidStabilizerInputError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=InvalidStabilizerInputError.d.ts.map

package/build/core/exceptions/InvalidStabilizerInputError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvalidStabilizerInputError.d.ts","sourceRoot":"","sources":["../../../src/core/exceptions/InvalidStabilizerInputError.ts"],"names":[],"mappings":"AAAA,qBAAa,2BAA4B,SAAQ,KAAK;gBAEtC,OAAO,EAAE,MAAM;CAK9B"}

package/build/core/exceptions/InvalidStabilizerInputError.js

@@ -0,0 +1,6 @@
+export class InvalidStabilizerInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidStabilizerInputError';
+    }
+}

package/build/core/exceptions/InvalidStabilizerOutputError.d.ts

@@ -0,0 +1,4 @@
+export declare class InvalidStabilizerOutputError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=InvalidStabilizerOutputError.d.ts.map

package/build/core/exceptions/InvalidStabilizerOutputError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvalidStabilizerOutputError.d.ts","sourceRoot":"","sources":["../../../src/core/exceptions/InvalidStabilizerOutputError.ts"],"names":[],"mappings":"AAAA,qBAAa,4BAA6B,SAAQ,KAAK;gBAEvC,OAAO,EAAE,MAAM;CAK9B"}

package/build/core/exceptions/InvalidStabilizerOutputError.js

@@ -0,0 +1,6 @@
+export class InvalidStabilizerOutputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidStabilizerOutputError';
+    }
+}

package/build/core/exceptions/MixedWaypointIdError.d.ts

@@ -0,0 +1,4 @@
+export declare class MixedWaypointIdError extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=MixedWaypointIdError.d.ts.map

package/build/core/exceptions/MixedWaypointIdError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MixedWaypointIdError.d.ts","sourceRoot":"","sources":["../../../src/core/exceptions/MixedWaypointIdError.ts"],"names":[],"mappings":"AAAA,qBAAa,oBAAqB,SAAQ,KAAK;gBAE/B,OAAO,SAA+D;CAKrF"}

package/build/core/exceptions/MixedWaypointIdError.js

@@ -0,0 +1,6 @@
+export class MixedWaypointIdError extends Error {
+    constructor(message = 'All items must either have waypoint_id or all must omit it') {
+        super(message);
+        this.name = 'MixedWaypointIdError';
+    }
+}

package/build/core/exceptions/UnknownReorderStrategyError.d.ts

@@ -0,0 +1,4 @@
+export declare class UnknownReorderStrategyError extends Error {
+    constructor(strategy: string);
+}
+//# sourceMappingURL=UnknownReorderStrategyError.d.ts.map

package/build/core/exceptions/UnknownReorderStrategyError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UnknownReorderStrategyError.d.ts","sourceRoot":"","sources":["../../../src/core/exceptions/UnknownReorderStrategyError.ts"],"names":[],"mappings":"AAAA,qBAAa,2BAA4B,SAAQ,KAAK;gBAEtC,QAAQ,EAAE,MAAM;CAK/B"}

package/build/core/exceptions/UnknownReorderStrategyError.js

@@ -0,0 +1,6 @@
+export class UnknownReorderStrategyError extends Error {
+    constructor(strategy) {
+        super('Unknown reorder strategy: ' + strategy);
+        this.name = 'UnknownReorderStrategyError';
+    }
+}

package/build/core/factory/read_stabilizer_config.d.ts

@@ -0,0 +1,10 @@
+import { type StabilizerConfig } from '../validation/schemas/stabilizer_config_schema.js';
+import type { StabilizerCargoState } from '../validation/contract/stabilizer_domain_schema.js';
+/**
+ * Reads stabilizer config from cargo-movement config and cargo profile algoritmo maps.
+ * @param config - Top-level stabilizer input config object.
+ * @param cargo_state - Cargo profile (optional) for merged algoritmo keys.
+ * @returns Parsed stabilizer configuration.
+ */
+export declare function read_stabilizer_config(config: Record<string, unknown> | undefined, cargo_state?: StabilizerCargoState): StabilizerConfig;
+//# sourceMappingURL=read_stabilizer_config.d.ts.map

package/build/core/factory/read_stabilizer_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_stabilizer_config.d.ts","sourceRoot":"","sources":["../../../src/core/factory/read_stabilizer_config.ts"],"names":[],"mappings":"AAKA,OAAO,EAEH,KAAK,gBAAgB,EACxB,MAAM,mDAAmD,CAAA;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAG9F;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,WAAW,CAAC,EAAE,oBAAoB,GACnC,gBAAgB,CAYlB"}

package/build/core/factory/read_stabilizer_config.js

@@ -0,0 +1,26 @@
+import { REORDER_STRATEGY } from '../constants/ReorderStrategy.js';
+import { UnknownReorderStrategyError } from '../exceptions/UnknownReorderStrategyError.js';
+import { stabilizer_config_schema } from '../validation/schemas/stabilizer_config_schema.js';
+import { merge_algoritmo_maps, read_raw_stabilizer_config } from './read_stabilizer_config_helpers.js';
+/**
+ * Reads stabilizer config from cargo-movement config and cargo profile algoritmo maps.
+ * @param config - Top-level stabilizer input config object.
+ * @param cargo_state - Cargo profile (optional) for merged algoritmo keys.
+ * @returns Parsed stabilizer configuration.
+ */
+export function read_stabilizer_config(config, cargo_state) {
+    const algoritmo = merge_algoritmo_maps(config, cargo_state);
+    const raw = read_raw_stabilizer_config(algoritmo);
+    const parsed = stabilizer_config_schema.safeParse(raw);
+    if (!parsed.success) {
+        throw new UnknownReorderStrategyError(String(raw.reorder_strategy));
+    }
+    assert_known_strategy(parsed.data.reorder_strategy);
+    return parsed.data;
+}
+function assert_known_strategy(strategy) {
+    const values = Object.values(REORDER_STRATEGY);
+    if (!values.includes(strategy)) {
+        throw new UnknownReorderStrategyError(strategy);
+    }
+}

package/build/core/factory/read_stabilizer_config_helpers.d.ts

@@ -0,0 +1,29 @@
+import type { StabilizerCargoState } from '../validation/contract/stabilizer_domain_schema.js';
+/**
+ * Merges root and cargo profile algoritmo maps (profile overrides root).
+ * @param config - Root stabilizer input config.
+ * @param cargo_state - Cargo profile state.
+ * @returns Merged algoritmo map.
+ */
+export declare function merge_algoritmo_maps(config: Record<string, unknown> | undefined, cargo_state?: StabilizerCargoState): Record<string, unknown>;
+/**
+ * Reads raw stabilizer config fields from merged algoritmo map.
+ * @param algoritmo - Merged algoritmo configuration map.
+ * @returns Raw config object for schema parsing.
+ */
+export declare function read_raw_stabilizer_config(algoritmo: Record<string, unknown>): {
+    preserve_tie_block_organization: boolean;
+    pin_tie_ratio_blocks: boolean;
+    enforce_milkrun_wall_reservation: boolean;
+    number_of_wall_to_allocate_from_last_waypoints: number;
+    reorder_strategy: string;
+    transport_stability_floor: number;
+    max_iteration: number;
+    genetic_population: number;
+    genetic_generations: number;
+    genetic_mutation_rate: number;
+    beam_width: number;
+    beam_top_k: number;
+    axle_load_margin_percent: number;
+};
+//# sourceMappingURL=read_stabilizer_config_helpers.d.ts.map

package/build/core/factory/read_stabilizer_config_helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_stabilizer_config_helpers.d.ts","sourceRoot":"","sources":["../../../src/core/factory/read_stabilizer_config_helpers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAK9F;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,WAAW,CAAC,EAAE,oBAAoB,GACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;;;;;;EAM5E"}

package/build/core/factory/read_stabilizer_config_helpers.js

@@ -0,0 +1,73 @@
+import { REORDER_STRATEGY } from '../constants/ReorderStrategy.js';
+const CONFIG_PREFIX = 'cargo_stabilizer.';
+const MILKRUN_WALL_COUNT_KEY = 'number_of_wall_to_allocate_from_last_waypoints';
+/**
+ * Merges root and cargo profile algoritmo maps (profile overrides root).
+ * @param config - Root stabilizer input config.
+ * @param cargo_state - Cargo profile state.
+ * @returns Merged algoritmo map.
+ */
+export function merge_algoritmo_maps(config, cargo_state) {
+    const root_algoritmo = (config?.algoritmo ?? config ?? {});
+    const profile_config = cargo_state?.config;
+    const profile_algoritmo = (profile_config?.algoritmo ?? {});
+    return { ...root_algoritmo, ...profile_algoritmo };
+}
+/**
+ * Reads raw stabilizer config fields from merged algoritmo map.
+ * @param algoritmo - Merged algoritmo configuration map.
+ * @returns Raw config object for schema parsing.
+ */
+export function read_raw_stabilizer_config(algoritmo) {
+    return {
+        ...read_search_raw(algoritmo),
+        ...read_organization_raw(algoritmo)
+    };
+}
+function read_search_raw(algoritmo) {
+    return {
+        reorder_strategy: read_config_string(algoritmo, 'reorder_strategy', REORDER_STRATEGY.GRAVITY),
+        transport_stability_floor: read_config_number(algoritmo, 'transport_stability_floor', 0),
+        max_iteration: read_config_number(algoritmo, 'max_iteration', 10),
+        genetic_population: read_config_number(algoritmo, 'genetic_population', 30),
+        genetic_generations: read_config_number(algoritmo, 'genetic_generations', 50),
+        genetic_mutation_rate: read_config_number(algoritmo, 'genetic_mutation_rate', 0.15),
+        beam_width: read_config_number(algoritmo, 'beam_width', 5),
+        beam_top_k: read_config_number(algoritmo, 'beam_top_k', 3),
+        axle_load_margin_percent: read_config_number(algoritmo, 'folga_de_peso_nos_eixos', 0)
+    };
+}
+function read_organization_raw(algoritmo) {
+    return {
+        preserve_tie_block_organization: read_config_boolean(algoritmo, 'preserve_tie_block_organization', true),
+        pin_tie_ratio_blocks: read_config_boolean(algoritmo, 'pin_tie_ratio_blocks', false),
+        enforce_milkrun_wall_reservation: read_config_boolean(algoritmo, 'enforce_milkrun_wall_reservation', false),
+        number_of_wall_to_allocate_from_last_waypoints: read_milkrun_wall_count(algoritmo)
+    };
+}
+function read_config_string(algoritmo, key, default_value) {
+    const full_key = CONFIG_PREFIX + key;
+    const value = algoritmo[full_key] ?? algoritmo[key];
+    return typeof value === 'string' ? value : default_value;
+}
+function read_config_number(algoritmo, key, default_value) {
+    const full_key = CONFIG_PREFIX + key;
+    const value = algoritmo[full_key] ?? algoritmo[key];
+    return typeof value === 'number' ? value : default_value;
+}
+function read_config_boolean(algoritmo, key, default_value) {
+    const full_key = CONFIG_PREFIX + key;
+    const value = algoritmo[full_key] ?? algoritmo[key];
+    return typeof value === 'boolean' ? value : default_value;
+}
+function read_milkrun_wall_count(algoritmo) {
+    const value = algoritmo[MILKRUN_WALL_COUNT_KEY];
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.max(0, Math.trunc(value));
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseInt(value, 10);
+        return Number.isFinite(parsed) ? Math.max(0, parsed) : 0;
+    }
+    return 0;
+}

package/build/core/factory/strategy_factory.d.ts

@@ -0,0 +1,9 @@
+import type { StabilizerConfig } from '../validation/schemas/stabilizer_config_schema.js';
+import type { ReorderStrategy } from '../strategies/reorder/ReorderStrategy.js';
+/**
+ * Creates a reorder strategy implementation from config.
+ * @param config - Parsed stabilizer config.
+ * @returns Strategy instance.
+ */
+export declare function create_reorder_strategy(config: StabilizerConfig): ReorderStrategy;
+//# sourceMappingURL=strategy_factory.d.ts.map

package/build/core/factory/strategy_factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy_factory.d.ts","sourceRoot":"","sources":["../../../src/core/factory/strategy_factory.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAA;AAQ/E;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAmBjF"}

package/build/core/factory/strategy_factory.js

@@ -0,0 +1,29 @@
+import { REORDER_STRATEGY } from '../constants/ReorderStrategy.js';
+import { GravityCompaction } from '../strategies/reorder/GravityCompaction.js';
+import { GreedyReorder } from '../strategies/reorder/GreedyReorder.js';
+import { BeamSearchReorder } from '../strategies/reorder/BeamSearchReorder.js';
+import { SimulatedAnnealingReorder } from '../strategies/reorder/SimulatedAnnealingReorder.js';
+import { GeneticReorder } from '../strategies/reorder/GeneticReorder.js';
+import { UnknownReorderStrategyError } from '../exceptions/UnknownReorderStrategyError.js';
+/**
+ * Creates a reorder strategy implementation from config.
+ * @param config - Parsed stabilizer config.
+ * @returns Strategy instance.
+ */
+export function create_reorder_strategy(config) {
+    const strategy = config.reorder_strategy;
+    switch (strategy) {
+        case REORDER_STRATEGY.GRAVITY:
+            return new GravityCompaction();
+        case REORDER_STRATEGY.GREEDY:
+            return new GreedyReorder();
+        case REORDER_STRATEGY.BEAM_SEARCH:
+            return new BeamSearchReorder();
+        case REORDER_STRATEGY.SIMULATED_ANNEALING:
+            return new SimulatedAnnealingReorder();
+        case REORDER_STRATEGY.GENETIC:
+            return new GeneticReorder();
+        default:
+            throw new UnknownReorderStrategyError(String(strategy));
+    }
+}

package/build/core/filters/collect_movable_items.d.ts

@@ -0,0 +1,18 @@
+import type { StabilizerItem } from '../validation/contract/stabilizer_domain_schema.js';
+import type { LooseItemRef } from './loose_item_filter.js';
+/**
+ * Collects items the stabilizer may move.
+ * @param containers - Container list from env.
+ * @param pin_tie_ratio_blocks - When true, skip 3_2/2_3 groups.
+ * @returns Movable item references with container index.
+ */
+export declare function collect_movable_items(containers: {
+    items: StabilizerItem[];
+}[], pin_tie_ratio_blocks: boolean): LooseItemRef[];
+/**
+ * @param item - Item record.
+ * @param tie_ratio_group_ids - Group ids that contain a 3_2/2_3 member.
+ * @returns True when the item belongs to a pinned tie-ratio group.
+ */
+export declare function is_tie_ratio_block_item(item: StabilizerItem, tie_ratio_group_ids: Set<string>): boolean;
+//# sourceMappingURL=collect_movable_items.d.ts.map

package/build/core/filters/collect_movable_items.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect_movable_items.d.ts","sourceRoot":"","sources":["../../../src/core/filters/collect_movable_items.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AAExF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAA;AAE1D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACjC,UAAU,EAAE;IAAE,KAAK,EAAE,cAAc,EAAE,CAAA;CAAE,EAAE,EACzC,oBAAoB,EAAE,OAAO,GAC9B,YAAY,EAAE,CAMhB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACnC,IAAI,EAAE,cAAc,EACpB,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,GACjC,OAAO,CAOT"}

package/build/core/filters/collect_movable_items.js

@@ -0,0 +1,72 @@
+import { TIE_RATIO_ORIENTATION } from '../constants/TieRatioOrientation.js';
+/**
+ * Collects items the stabilizer may move.
+ * @param containers - Container list from env.
+ * @param pin_tie_ratio_blocks - When true, skip 3_2/2_3 groups.
+ * @returns Movable item references with container index.
+ */
+export function collect_movable_items(containers, pin_tie_ratio_blocks) {
+    const pinned_groups = pin_tie_ratio_blocks
+        ? collect_tie_ratio_group_ids(flatten_container_items(containers))
+        : new Set();
+    return collect_items_except_pinned(containers, pinned_groups);
+}
+/**
+ * @param item - Item record.
+ * @param tie_ratio_group_ids - Group ids that contain a 3_2/2_3 member.
+ * @returns True when the item belongs to a pinned tie-ratio group.
+ */
+export function is_tie_ratio_block_item(item, tie_ratio_group_ids) {
+    if (item.group_id == null) {
+        return false;
+    }
+    return tie_ratio_group_ids.has(item.group_id);
+}
+function collect_tie_ratio_group_ids(items) {
+    const group_ids = new Set();
+    for (const item of items) {
+        if (item.group_id == null) {
+            continue;
+        }
+        if (is_tie_ratio_orientation(read_tie_ratio_orientation(item))) {
+            group_ids.add(item.group_id);
+        }
+    }
+    return group_ids;
+}
+function collect_items_except_pinned(containers, pinned_groups) {
+    const movable = [];
+    for (let container_index = 0; container_index < containers.length; container_index++) {
+        movable.push(...collect_container_movable_items(containers[container_index].items, container_index, pinned_groups));
+    }
+    return movable;
+}
+function collect_container_movable_items(items, container_index, pinned_groups) {
+    const movable = [];
+    for (const item of items) {
+        if (is_tie_ratio_block_item(item, pinned_groups)) {
+            continue;
+        }
+        movable.push({
+            item_id: item.item_id,
+            container_index,
+            item
+        });
+    }
+    return movable;
+}
+function flatten_container_items(containers) {
+    const items = [];
+    for (const container of containers) {
+        items.push(...container.items);
+    }
+    return items;
+}
+function read_tie_ratio_orientation(item) {
+    const orientation = item.attributes?.tie_ratio_orientation;
+    return typeof orientation === 'string' ? orientation : undefined;
+}
+function is_tie_ratio_orientation(orientation) {
+    return orientation === TIE_RATIO_ORIENTATION.THREE_TWO
+        || orientation === TIE_RATIO_ORIENTATION.TWO_THREE;
+}

package/build/core/filters/loose_item_filter.d.ts

@@ -0,0 +1,20 @@
+import type { StabilizerItem } from '../validation/contract/stabilizer_domain_schema.js';
+export interface LooseItemRef {
+    item_id: string;
+    container_index: number;
+    item: StabilizerItem;
+}
+/**
+ * @param item - Item record from cargo_state.
+ * @returns True when item is loose (no group_id).
+ */
+export declare function is_loose_item(item: StabilizerItem): boolean;
+/**
+ * Collects loose items across all containers in one env.
+ * @param containers - Container list from env.
+ * @returns Loose item references with container index.
+ */
+export declare function collect_loose_items(containers: {
+    items: StabilizerItem[];
+}[]): LooseItemRef[];
+//# sourceMappingURL=loose_item_filter.d.ts.map

package/build/core/filters/loose_item_filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loose_item_filter.d.ts","sourceRoot":"","sources":["../../../src/core/filters/loose_item_filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AAExF,MAAM,WAAW,YAAY;IAEzB,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,MAAM,CAAA;IACvB,IAAI,EAAE,cAAc,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAG3D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAC/B,UAAU,EAAE;IAAE,KAAK,EAAE,cAAc,EAAE,CAAA;CAAE,EAAE,GAC1C,YAAY,EAAE,CAqBhB"}

package/build/core/filters/loose_item_filter.js

@@ -0,0 +1,28 @@
+/**
+ * @param item - Item record from cargo_state.
+ * @returns True when item is loose (no group_id).
+ */
+export function is_loose_item(item) {
+    return item.group_id === null || item.group_id === undefined;
+}
+/**
+ * Collects loose items across all containers in one env.
+ * @param containers - Container list from env.
+ * @returns Loose item references with container index.
+ */
+export function collect_loose_items(containers) {
+    const loose_items = [];
+    containers.forEach((container, container_index) => {
+        for (const item of container.items) {
+            if (!is_loose_item(item)) {
+                continue;
+            }
+            loose_items.push({
+                item_id: item.item_id,
+                container_index,
+                item
+            });
+        }
+    });
+    return loose_items;
+}

package/build/core/geometry/box_geometry.d.ts

@@ -0,0 +1,48 @@
+import type { StabilizerItem } from '../validation/contract/stabilizer_domain_schema.js';
+export interface AxisAlignedBox {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+    h: number;
+    d: number;
+}
+/**
+ * @param item - Cargo item with position and dimensions.
+ * @returns Axis-aligned bounding box.
+ */
+export declare function item_to_box(item: StabilizerItem): AxisAlignedBox;
+/**
+ * @param left - First box.
+ * @param right - Second box.
+ * @returns True when boxes overlap in 3D.
+ */
+export declare function boxes_overlap(left: AxisAlignedBox, right: AxisAlignedBox): boolean;
+/**
+ * @param candidate - Candidate placement box.
+ * @param others - Existing item boxes to avoid.
+ * @returns True when candidate overlaps any other box.
+ */
+export declare function has_overlap(candidate: AxisAlignedBox, others: AxisAlignedBox[]): boolean;
+/**
+ * @param candidate - Candidate box.
+ * @returns True when candidate rests on container floor.
+ */
+export declare function is_on_floor(candidate: AxisAlignedBox): boolean;
+/**
+ * @param candidate - Candidate placement box.
+ * @param container - Container dimensions.
+ * @returns True when candidate fits inside container bounds.
+ */
+export declare function is_inside_container(candidate: AxisAlignedBox, container: {
+    width: number;
+    height: number;
+    length: number;
+}): boolean;
+/**
+ * @param candidate - Candidate placement box.
+ * @param supporters - Existing item boxes (excluding candidate).
+ * @returns True when bottom face is on floor or supporter tops.
+ */
+export declare function is_fully_supported(candidate: AxisAlignedBox, supporters: AxisAlignedBox[]): boolean;
+//# sourceMappingURL=box_geometry.d.ts.map

package/build/core/geometry/box_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"box_geometry.d.ts","sourceRoot":"","sources":["../../../src/core/geometry/box_geometry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AAExF,MAAM,WAAW,cAAc;IAE3B,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;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAUhE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAMlF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAGxF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAG9D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAC/B,SAAS,EAAE,cAAc,EACzB,SAAS,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D,OAAO,CAeT;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,GAAG,OAAO,CAUnG"}