@jetta/cargo-stabilizer 0.1.0-10

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

@@ -0,0 +1,61 @@
+import { apply_move, clone_containers } from '../../move/apply_move.js';
+import { evaluate_trial_layout, evaluation_context_from_reorder } from '../../evaluation/state_evaluator.js';
+import { accept_move, propose_neighbor } from './anneal_helpers.js';
+/**
+ * Simulated annealing reorder with hard gate rejection on invalid neighbors.
+ */
+export class SimulatedAnnealingReorder {
+    run(context) {
+        const eval_context = evaluation_context_from_reorder(context);
+        const state = {
+            working: clone_containers(context.containers),
+            best: clone_containers(context.containers),
+            best_energy: energy(context.containers, eval_context)
+        };
+        let temperature = 1.0;
+        const cooling_rate = 0.995;
+        const steps = context.config.max_iteration * 10;
+        for (let step = 0; step < steps; step++) {
+            anneal_step({ reorder: context, evaluation: eval_context, state, temperature });
+            temperature *= cooling_rate;
+        }
+        context.containers.splice(0, context.containers.length, ...state.best);
+        return state.best;
+    }
+}
+function anneal_step(step_context) {
+    const neighbor = propose_neighbor(step_context.reorder, step_context.state.working);
+    if (!neighbor) {
+        return;
+    }
+    const trial_energy = evaluate_neighbor(step_context, neighbor);
+    if (trial_energy === undefined) {
+        return;
+    }
+    apply_accepted_neighbor(step_context, neighbor, trial_energy);
+}
+function evaluate_neighbor(step_context, neighbor) {
+    const trial = clone_containers(step_context.state.working);
+    apply_move(trial, neighbor);
+    const evaluation = evaluate_trial_layout(trial, step_context.evaluation);
+    if (!evaluation.all_gates_pass) {
+        return undefined;
+    }
+    const trial_energy = -evaluation.objective;
+    const delta = trial_energy - energy(step_context.state.working, step_context.evaluation);
+    if (!accept_move(delta, step_context.temperature)) {
+        return undefined;
+    }
+    return trial_energy;
+}
+function apply_accepted_neighbor(step_context, neighbor, trial_energy) {
+    apply_move(step_context.state.working, neighbor);
+    if (trial_energy >= step_context.state.best_energy) {
+        return;
+    }
+    step_context.state.best = clone_containers(step_context.state.working);
+    step_context.state.best_energy = trial_energy;
+}
+function energy(containers, eval_context) {
+    return -evaluate_trial_layout(containers, eval_context).objective;
+}

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

@@ -0,0 +1,18 @@
+import type { ReorderContext } from './ReorderStrategy.js';
+import type { StabilizerContainer } from '../../validation/contract/stabilizer_domain_schema.js';
+import type { MoveCandidate } from '../../move/apply_move.js';
+/**
+ * Proposes a random valid neighbor move for simulated annealing.
+ * @param context - Reorder context.
+ * @param working - Current working layout.
+ * @returns Random candidate or undefined.
+ */
+export declare function propose_neighbor(context: ReorderContext, working: StabilizerContainer[]): MoveCandidate | undefined;
+/**
+ * Metropolis acceptance rule for simulated annealing.
+ * @param delta - Energy delta.
+ * @param temperature - Current temperature.
+ * @returns True when move is accepted.
+ */
+export declare function accept_move(delta: number, temperature: number): boolean;
+//# sourceMappingURL=anneal_helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"anneal_helpers.d.ts","sourceRoot":"","sources":["../../../../src/core/strategies/reorder/anneal_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAA;AAChG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAI7D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC5B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,mBAAmB,EAAE,GAC/B,aAAa,GAAG,SAAS,CAgB3B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAWvE"}

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

@@ -0,0 +1,39 @@
+import { generate_candidates } from '../../candidates/candidate_generator.js';
+import { candidate_context_for_loose } from '../../candidates/build_candidate_context.js';
+/**
+ * Proposes a random valid neighbor move for simulated annealing.
+ * @param context - Reorder context.
+ * @param working - Current working layout.
+ * @returns Random candidate or undefined.
+ */
+export function propose_neighbor(context, working) {
+    if (context.loose_items.length === 0) {
+        return undefined;
+    }
+    const index = Math.floor(Math.random() * context.loose_items.length);
+    const loose = { ...context.loose_items[index] };
+    loose.container_index = find_container_index(working, loose.item_id);
+    const candidates = generate_candidates(candidate_context_for_loose(context, working, loose));
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    return candidates[Math.floor(Math.random() * candidates.length)];
+}
+/**
+ * Metropolis acceptance rule for simulated annealing.
+ * @param delta - Energy delta.
+ * @param temperature - Current temperature.
+ * @returns True when move is accepted.
+ */
+export function accept_move(delta, temperature) {
+    if (delta < 0) {
+        return true;
+    }
+    if (temperature <= 1e-6) {
+        return false;
+    }
+    return Math.random() < Math.exp(-delta / temperature);
+}
+function find_container_index(containers, item_id) {
+    return containers.findIndex(container => container.items.some(item => item.item_id === item_id));
+}

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

@@ -0,0 +1,12 @@
+import type { StabilizerContainer } from '../../validation/contract/stabilizer_domain_schema.js';
+import type { ReorderContext } from './ReorderStrategy.js';
+import type { MoveCandidate } from '../../move/apply_move.js';
+/**
+ * Applies a candidate when all gates pass.
+ * @param context - Reorder context.
+ * @param working - Working container layout.
+ * @param candidate - Move candidate.
+ * @returns True when move was applied.
+ */
+export declare function apply_if_gates_pass(context: ReorderContext, working: StabilizerContainer[], candidate: MoveCandidate): boolean;
+//# sourceMappingURL=apply_if_gates_pass.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"apply_if_gates_pass.d.ts","sourceRoot":"","sources":["../../../../src/core/strategies/reorder/apply_if_gates_pass.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAA;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAO7D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,mBAAmB,EAAE,EAC9B,SAAS,EAAE,aAAa,GACzB,OAAO,CAWT"}

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

@@ -0,0 +1,19 @@
+import { apply_move, clone_containers } from '../../move/apply_move.js';
+import { evaluate_trial_layout, evaluation_context_from_reorder } from '../../evaluation/state_evaluator.js';
+/**
+ * Applies a candidate when all gates pass.
+ * @param context - Reorder context.
+ * @param working - Working container layout.
+ * @param candidate - Move candidate.
+ * @returns True when move was applied.
+ */
+export function apply_if_gates_pass(context, working, candidate) {
+    const trial = clone_containers(working);
+    apply_move(trial, candidate);
+    const evaluation = evaluate_trial_layout(trial, evaluation_context_from_reorder(context));
+    if (!evaluation.all_gates_pass) {
+        return false;
+    }
+    apply_move(working, candidate);
+    return true;
+}

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

@@ -0,0 +1,16 @@
+import type { ReorderContext } from './ReorderStrategy.js';
+import type { StabilizerContainer } from '../../validation/contract/stabilizer_domain_schema.js';
+import type { LooseItemRef } from '../../filters/loose_item_filter.js';
+import type { StateEvaluationContext } from '../../evaluation/evaluation_context.js';
+export interface BeamExpansionContext {
+    reorder: ReorderContext;
+    evaluation: StateEvaluationContext;
+    expanded: BeamState[];
+    state: BeamState;
+    loose: LooseItemRef;
+}
+export interface BeamState {
+    containers: StabilizerContainer[];
+    objective: number;
+}
+//# sourceMappingURL=beam_context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"beam_context.d.ts","sourceRoot":"","sources":["../../../../src/core/strategies/reorder/beam_context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAA;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AACtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAA;AAEpF,MAAM,WAAW,oBAAoB;IAEjC,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,sBAAsB,CAAA;IAClC,QAAQ,EAAE,SAAS,EAAE,CAAA;IACrB,KAAK,EAAE,SAAS,CAAA;IAChB,KAAK,EAAE,YAAY,CAAA;CACtB;AAED,MAAM,WAAW,SAAS;IAEtB,UAAU,EAAE,mBAAmB,EAAE,CAAA;IACjC,SAAS,EAAE,MAAM,CAAA;CACpB"}

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

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

package/build/core/strategies/reorder/genetic/Chromosome.d.ts

@@ -0,0 +1,39 @@
+import type { MoveCandidate } from '../../../move/apply_move.js';
+import type { ReorderContext } from '../ReorderStrategy.js';
+import type { StabilizerContainer } from '../../../validation/contract/stabilizer_domain_schema.js';
+export interface ChromosomeGene {
+    item_id: string;
+    candidate: MoveCandidate;
+}
+export interface GeneticOrganism {
+    genes: ChromosomeGene[];
+    fitness: number;
+}
+/**
+ * Builds initial population from random valid gene assignments.
+ * @param context - Reorder context.
+ * @param population_size - Population count.
+ * @returns Initial organisms.
+ */
+export declare function build_initial_population(context: ReorderContext, population_size: number): GeneticOrganism[];
+/**
+ * @param left - First organism.
+ * @param right - Second organism.
+ * @returns Child organism via uniform crossover.
+ */
+export declare function crossover_organisms(left: GeneticOrganism, right: GeneticOrganism): GeneticOrganism;
+/**
+ * Mutates one gene in-place when mutation triggers.
+ * @param organism - Organism to mutate.
+ * @param context - Reorder context.
+ * @param mutation_rate - Probability per gene.
+ */
+export declare function mutate_organism(organism: GeneticOrganism, context: ReorderContext, mutation_rate: number): void;
+/**
+ * Materializes organism genes onto container layout.
+ * @param baseline - Baseline containers.
+ * @param organism - Organism with genes.
+ * @returns New container layout.
+ */
+export declare function materialize_organism(baseline: StabilizerContainer[], organism: GeneticOrganism): StabilizerContainer[];
+//# sourceMappingURL=Chromosome.d.ts.map

package/build/core/strategies/reorder/genetic/Chromosome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Chromosome.d.ts","sourceRoot":"","sources":["../../../../../src/core/strategies/reorder/genetic/Chromosome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0DAA0D,CAAA;AAEnG,MAAM,WAAW,cAAc;IAE3B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,aAAa,CAAA;CAC3B;AAED,MAAM,WAAW,eAAe;IAE5B,KAAK,EAAE,cAAc,EAAE,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,OAAO,EAAE,cAAc,EACvB,eAAe,EAAE,MAAM,GACxB,eAAe,EAAE,CAQnB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,eAAe,CAMlG;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC3B,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,cAAc,EACvB,aAAa,EAAE,MAAM,GACtB,IAAI,CAeN;AAsBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,QAAQ,EAAE,eAAe,GAC1B,mBAAmB,EAAE,CAgBvB"}

package/build/core/strategies/reorder/genetic/Chromosome.js

@@ -0,0 +1,84 @@
+/**
+ * Builds initial population from random valid gene assignments.
+ * @param context - Reorder context.
+ * @param population_size - Population count.
+ * @returns Initial organisms.
+ */
+export function build_initial_population(context, population_size) {
+    const organisms = [];
+    for (let index = 0; index < population_size; index++) {
+        organisms.push(build_random_organism(context));
+    }
+    return organisms;
+}
+/**
+ * @param left - First organism.
+ * @param right - Second organism.
+ * @returns Child organism via uniform crossover.
+ */
+export function crossover_organisms(left, right) {
+    const genes = left.genes.map((gene, index) => Math.random() < 0.5 ? gene : right.genes[index] ?? gene);
+    return { genes, fitness: Number.NEGATIVE_INFINITY };
+}
+/**
+ * Mutates one gene in-place when mutation triggers.
+ * @param organism - Organism to mutate.
+ * @param context - Reorder context.
+ * @param mutation_rate - Probability per gene.
+ */
+export function mutate_organism(organism, context, mutation_rate) {
+    if (organism.genes.length === 0) {
+        return;
+    }
+    const gene_index = Math.floor(Math.random() * organism.genes.length);
+    if (Math.random() > mutation_rate) {
+        return;
+    }
+    const replacement = build_random_organism(context);
+    organism.genes[gene_index] = replacement.genes[gene_index] ?? organism.genes[gene_index];
+}
+function build_random_organism(context) {
+    const genes = [];
+    for (const loose of context.loose_items) {
+        genes.push({ item_id: loose.item_id, candidate: build_identity_candidate(loose) });
+    }
+    return { genes, fitness: Number.NEGATIVE_INFINITY };
+}
+function build_identity_candidate(loose) {
+    return {
+        item_id: loose.item_id,
+        source_container_index: loose.container_index,
+        target_container_index: loose.container_index,
+        new_position: { x: loose.item.x, y: loose.item.y, z: loose.item.z }
+    };
+}
+/**
+ * Materializes organism genes onto container layout.
+ * @param baseline - Baseline containers.
+ * @param organism - Organism with genes.
+ * @returns New container layout.
+ */
+export function materialize_organism(baseline, organism) {
+    const working = structuredClone(baseline);
+    for (const gene of organism.genes) {
+        const source_index = working.findIndex(container => container.items.some(item => item.item_id === gene.item_id));
+        if (source_index < 0) {
+            continue;
+        }
+        gene.candidate.source_container_index = source_index;
+        apply_gene(working, gene.candidate);
+    }
+    return working;
+}
+function apply_gene(containers, candidate) {
+    const source = containers[candidate.source_container_index];
+    const item_index = source.items.findIndex(item => item.item_id === candidate.item_id);
+    if (item_index < 0) {
+        return;
+    }
+    const [item] = source.items.splice(item_index, 1);
+    item.x = candidate.new_position.x;
+    item.y = candidate.new_position.y;
+    item.z = candidate.new_position.z;
+    containers[candidate.target_container_index].items.push(item);
+}

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

@@ -0,0 +1,12 @@
+import type { ReorderContext } from './ReorderStrategy.js';
+import type { StabilizerContainer } from '../../validation/contract/stabilizer_domain_schema.js';
+import type { StateEvaluationContext } from '../../evaluation/evaluation_context.js';
+/**
+ * Attempts one greedy improvement on the worst loose item.
+ * @param context - Reorder context.
+ * @param working - Working layout.
+ * @param eval_context - Evaluation context.
+ * @returns True when layout improved.
+ */
+export declare function improve_worst_loose(context: ReorderContext, working: StabilizerContainer[], eval_context: StateEvaluationContext): boolean;
+//# sourceMappingURL=greedy_improvement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"greedy_improvement.d.ts","sourceRoot":"","sources":["../../../../src/core/strategies/reorder/greedy_improvement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAA;AAEhG,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAA;AAepF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,mBAAmB,EAAE,EAC9B,YAAY,EAAE,sBAAsB,GACrC,OAAO,CAiBT"}

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

@@ -0,0 +1,63 @@
+import { generate_candidates } from '../../candidates/candidate_generator.js';
+import { candidate_context_for_loose } from '../../candidates/build_candidate_context.js';
+import { apply_move, clone_containers } from '../../move/apply_move.js';
+import { evaluate_trial_layout } from '../../evaluation/state_evaluator.js';
+/**
+ * Attempts one greedy improvement on the worst loose item.
+ * @param context - Reorder context.
+ * @param working - Working layout.
+ * @param eval_context - Evaluation context.
+ * @returns True when layout improved.
+ */
+export function improve_worst_loose(context, working, eval_context) {
+    const current_eval = evaluate_trial_layout(working, eval_context);
+    const worst = find_worst_loose(context, working, current_eval.stability.item_scores);
+    if (!worst) {
+        return false;
+    }
+    worst.container_index = find_container_index(working, worst.item_id);
+    return try_candidate_moves({
+        reorder: context,
+        working,
+        evaluation: eval_context,
+        loose: worst,
+        baseline_objective: current_eval.objective
+    });
+}
+function try_candidate_moves(move_context) {
+    const candidates = generate_candidates(candidate_context_for_loose(move_context.reorder, move_context.working, move_context.loose));
+    for (const candidate of candidates) {
+        if (apply_improving_candidate(move_context, candidate)) {
+            return true;
+        }
+    }
+    return false;
+}
+function apply_improving_candidate(move_context, candidate) {
+    const trial = clone_containers(move_context.working);
+    apply_move(trial, candidate);
+    const trial_eval = evaluate_trial_layout(trial, move_context.evaluation);
+    if (!trial_eval.all_gates_pass || trial_eval.objective <= move_context.baseline_objective) {
+        return false;
+    }
+    apply_move(move_context.working, candidate);
+    move_context.loose.container_index = candidate.target_container_index;
+    return true;
+}
+function find_worst_loose(context, containers, item_scores) {
+    let worst;
+    let worst_score = Number.POSITIVE_INFINITY;
+    for (const loose of context.loose_items) {
+        const item_index = containers[loose.container_index].items
+            .findIndex(item => item.item_id === loose.item_id);
+        const score = item_scores[loose.container_index]?.[item_index] ?? 0;
+        if (score < worst_score) {
+            worst_score = score;
+            worst = loose;
+        }
+    }
+    return worst;
+}
+function find_container_index(containers, item_id) {
+    return containers.findIndex(container => container.items.some(item => item.item_id === item_id));
+}

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/build/core/validation/contract/cargo_movement_wire_field_map.d.ts

@@ -0,0 +1,37 @@
+export declare const ITEM_WIRE_TO_CONTRACT: {
+    readonly _id: "item_id";
+    readonly groupId: "group_id";
+    readonly w: "width";
+    readonly h: "height";
+    readonly d: "depth";
+};
+/**
+ * Cargo-movement wire keys feeding each contract item field, in precedence
+ * order. Items are read-only for the stabilizer apart from their position, so
+ * these keys are read rather than renamed: the original wire record is
+ * retained in `attributes` and is what gets emitted back.
+ */
+export declare const ITEM_CONTRACT_WIRE_KEYS: Readonly<{
+    item_id: string[];
+    group_id: string[];
+    waypoint_id: string[];
+    width: string[];
+    height: string[];
+    depth: string[];
+    weight: string[];
+}>;
+/** Item fields the stabilizer mutates, and therefore must emit itself. */
+export declare const ITEM_POSITION_KEYS: string[];
+export declare const CONTAINER_WIRE_TO_CONTRACT: {
+    readonly sequencia: "sequence";
+    readonly largura: "width";
+    readonly altura: "height";
+    readonly comprimento: "length";
+};
+export declare const ENV_WIRE_TO_CONTRACT: {
+    readonly eixos: "axles";
+};
+export declare const CONTRACT_TO_ITEM_WIRE: Record<string, string>;
+export declare const CONTRACT_TO_CONTAINER_WIRE: Record<string, string>;
+export declare const CONTRACT_TO_ENV_WIRE: Record<string, string>;
+//# sourceMappingURL=cargo_movement_wire_field_map.d.ts.map

package/build/core/validation/contract/cargo_movement_wire_field_map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cargo_movement_wire_field_map.d.ts","sourceRoot":"","sources":["../../../../src/core/validation/contract/cargo_movement_wire_field_map.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB;;;;;;CAMxB,CAAA;AAEV;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;EAQlC,CAAA;AAEF,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,UAAkB,CAAA;AAEjD,eAAO,MAAM,0BAA0B;;;;;CAK7B,CAAA;AAEV,eAAO,MAAM,oBAAoB;;CAEvB,CAAA;AAEV,eAAO,MAAM,qBAAqB,wBAAoC,CAAA;AACtE,eAAO,MAAM,0BAA0B,wBAAyC,CAAA;AAChF,eAAO,MAAM,oBAAoB,wBAAmC,CAAA"}

package/build/core/validation/contract/cargo_movement_wire_field_map.js

@@ -0,0 +1,43 @@
+export const ITEM_WIRE_TO_CONTRACT = {
+    _id: 'item_id',
+    groupId: 'group_id',
+    w: 'width',
+    h: 'height',
+    d: 'depth'
+};
+/**
+ * Cargo-movement wire keys feeding each contract item field, in precedence
+ * order. Items are read-only for the stabilizer apart from their position, so
+ * these keys are read rather than renamed: the original wire record is
+ * retained in `attributes` and is what gets emitted back.
+ */
+export const ITEM_CONTRACT_WIRE_KEYS = Object.freeze({
+    item_id: ['item_id', '_id'],
+    group_id: ['groupId', 'group_id'],
+    waypoint_id: ['waypoint_id'],
+    width: ['w', 'width'],
+    height: ['h', 'height'],
+    depth: ['d', 'depth'],
+    weight: ['wg', 'peso', 'weight']
+});
+/** Item fields the stabilizer mutates, and therefore must emit itself. */
+export const ITEM_POSITION_KEYS = ['x', 'y', 'z'];
+export const CONTAINER_WIRE_TO_CONTRACT = {
+    sequencia: 'sequence',
+    largura: 'width',
+    altura: 'height',
+    comprimento: 'length'
+};
+export const ENV_WIRE_TO_CONTRACT = {
+    eixos: 'axles'
+};
+export const CONTRACT_TO_ITEM_WIRE = invert_map(ITEM_WIRE_TO_CONTRACT);
+export const CONTRACT_TO_CONTAINER_WIRE = invert_map(CONTAINER_WIRE_TO_CONTRACT);
+export const CONTRACT_TO_ENV_WIRE = invert_map(ENV_WIRE_TO_CONTRACT);
+function invert_map(source) {
+    const inverted = {};
+    for (const [wire_key, contract_key] of Object.entries(source)) {
+        inverted[contract_key] = wire_key;
+    }
+    return inverted;
+}

package/build/core/validation/contract/cargo_movement_wire_mapper.d.ts

@@ -0,0 +1,14 @@
+import type { StabilizerCargoState } from './stabilizer_domain_schema.js';
+/**
+ * Maps a cargo-movement wire payload to the English contract shape.
+ * @param input_data - Unknown CM wire payload.
+ * @returns Object ready for strict contract parsing.
+ */
+export declare function map_wire_input_to_contract(input_data: unknown): unknown;
+/**
+ * Maps an English contract cargo state back to cargo-movement wire shape.
+ * @param cargo_state - English contract cargo state.
+ * @returns CM wire cargo state.
+ */
+export declare function map_contract_to_wire_output(cargo_state: StabilizerCargoState): unknown;
+//# sourceMappingURL=cargo_movement_wire_mapper.d.ts.map

package/build/core/validation/contract/cargo_movement_wire_mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cargo_movement_wire_mapper.d.ts","sourceRoot":"","sources":["../../../../src/core/validation/contract/cargo_movement_wire_mapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAOzE;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,OAAO,GAAG,OAAO,CAsBvE;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,oBAAoB,GAAG,OAAO,CAGtF"}

package/build/core/validation/contract/cargo_movement_wire_mapper.js

@@ -0,0 +1,34 @@
+import { map_cargo_state_to_wire } from './map_contract_to_wire_shape.js';
+import { map_cargo_state_to_contract } from './map_wire_input_to_contract_shape.js';
+import { is_record } from './wire_mapper_record_utils.js';
+const INPUT_ENVELOPE_KEYS = new Set(['id', 'company', 'cargo_state', 'config', 'original_input']);
+/**
+ * Maps a cargo-movement wire payload to the English contract shape.
+ * @param input_data - Unknown CM wire payload.
+ * @returns Object ready for strict contract parsing.
+ */
+export function map_wire_input_to_contract(input_data) {
+    if (!is_record(input_data)) {
+        return input_data;
+    }
+    const mapped = {};
+    for (const [key, value] of Object.entries(input_data)) {
+        if (!INPUT_ENVELOPE_KEYS.has(key)) {
+            continue;
+        }
+        if (key === 'cargo_state') {
+            mapped.cargo_state = map_cargo_state_to_contract(value);
+            continue;
+        }
+        mapped[key] = value;
+    }
+    return mapped;
+}
+/**
+ * Maps an English contract cargo state back to cargo-movement wire shape.
+ * @param cargo_state - English contract cargo state.
+ * @returns CM wire cargo state.
+ */
+export function map_contract_to_wire_output(cargo_state) {
+    return map_cargo_state_to_wire(cargo_state);
+}

package/build/core/validation/contract/format_zod_error.d.ts

@@ -0,0 +1,8 @@
+import type { ZodError } from 'zod';
+/**
+ * Formats Zod validation issues into a single human-readable string.
+ * @param error - Zod validation error.
+ * @returns Semicolon-separated path messages.
+ */
+export declare function format_zod_error(error: ZodError): string;
+//# sourceMappingURL=format_zod_error.d.ts.map

package/build/core/validation/contract/format_zod_error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format_zod_error.d.ts","sourceRoot":"","sources":["../../../../src/core/validation/contract/format_zod_error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAA;AAEnC;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAOxD"}

package/build/core/validation/contract/format_zod_error.js

@@ -0,0 +1,11 @@
+/**
+ * Formats Zod validation issues into a single human-readable string.
+ * @param error - Zod validation error.
+ * @returns Semicolon-separated path messages.
+ */
+export function format_zod_error(error) {
+    return error.issues.map(issue => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        return `${path}: ${issue.message}`;
+    }).join('; ');
+}

package/build/core/validation/contract/index.d.ts

@@ -0,0 +1,9 @@
+export { format_zod_error } from './format_zod_error.js';
+export { ITEM_WIRE_TO_CONTRACT, CONTAINER_WIRE_TO_CONTRACT, ENV_WIRE_TO_CONTRACT, CONTRACT_TO_ITEM_WIRE, CONTRACT_TO_CONTAINER_WIRE, CONTRACT_TO_ENV_WIRE } from './cargo_movement_wire_field_map.js';
+export { map_wire_input_to_contract, map_contract_to_wire_output } from './cargo_movement_wire_mapper.js';
+export { stabilizer_item_schema, stabilizer_container_schema, stabilizer_env_schema, stabilizer_cargo_state_schema, validate_primary_env_waypoints, type StabilizerItem, type StabilizerContainer, type StabilizerEnv, type StabilizerCargoState } from './stabilizer_domain_schema.js';
+export { stabilizer_input_schema, type StabilizerInput } from './stabilizer_input_schema.js';
+export { stabilizer_response_schema, stabilizer_success_response_schema, stabilizer_error_response_schema, type StabilizerResponse, type StabilizerSuccessResponse, type StabilizerErrorResponse } from './stabilizer_output_schema.js';
+export { parse_stabilizer_input, safe_parse_stabilizer_input } from './parse_stabilizer_input.js';
+export { parse_stabilizer_output, safe_parse_stabilizer_output } from './parse_stabilizer_output.js';
+//# sourceMappingURL=index.d.ts.map

package/build/core/validation/contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/validation/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EACH,qBAAqB,EACrB,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,EAC1B,oBAAoB,EACvB,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EACH,0BAA0B,EAC1B,2BAA2B,EAC9B,MAAM,iCAAiC,CAAA;AACxC,OAAO,EACH,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,6BAA6B,EAC7B,8BAA8B,EAC9B,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC5B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EAAE,uBAAuB,EAAE,KAAK,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAC5F,OAAO,EACH,0BAA0B,EAC1B,kCAAkC,EAClC,gCAAgC,EAChC,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC/B,MAAM,+BAA+B,CAAA;AACtC,OAAO,EACH,sBAAsB,EACtB,2BAA2B,EAC9B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACH,uBAAuB,EACvB,4BAA4B,EAC/B,MAAM,8BAA8B,CAAA"}

package/build/core/validation/contract/index.js

@@ -0,0 +1,8 @@
+export { format_zod_error } from './format_zod_error.js';
+export { ITEM_WIRE_TO_CONTRACT, CONTAINER_WIRE_TO_CONTRACT, ENV_WIRE_TO_CONTRACT, CONTRACT_TO_ITEM_WIRE, CONTRACT_TO_CONTAINER_WIRE, CONTRACT_TO_ENV_WIRE } from './cargo_movement_wire_field_map.js';
+export { map_wire_input_to_contract, map_contract_to_wire_output } from './cargo_movement_wire_mapper.js';
+export { stabilizer_item_schema, stabilizer_container_schema, stabilizer_env_schema, stabilizer_cargo_state_schema, validate_primary_env_waypoints } from './stabilizer_domain_schema.js';
+export { stabilizer_input_schema } from './stabilizer_input_schema.js';
+export { stabilizer_response_schema, stabilizer_success_response_schema, stabilizer_error_response_schema } from './stabilizer_output_schema.js';
+export { parse_stabilizer_input, safe_parse_stabilizer_input } from './parse_stabilizer_input.js';
+export { parse_stabilizer_output, safe_parse_stabilizer_output } from './parse_stabilizer_output.js';

package/build/core/validation/contract/map_contract_to_wire_shape.d.ts

@@ -0,0 +1,3 @@
+import type { StabilizerCargoState } from './stabilizer_domain_schema.js';
+export declare function map_cargo_state_to_wire(cargo_state: StabilizerCargoState): unknown;
+//# sourceMappingURL=map_contract_to_wire_shape.d.ts.map

package/build/core/validation/contract/map_contract_to_wire_shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map_contract_to_wire_shape.d.ts","sourceRoot":"","sources":["../../../../src/core/validation/contract/map_contract_to_wire_shape.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAGzE,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,oBAAoB,GAAG,OAAO,CAUlF"}