Repository navigation
Expand file tree
/
Copy pathexecution.d.ts
More file actions
62 lines (46 loc) · 3.63 KB
/
Copy pathexecution.d.ts
File metadata and controls
62 lines (46 loc) · 3.63 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
// Types for `@packvium/engine/execution.js` — the execution-plan adapter.
//
// The split between `facts` and `presentation` is part of the contract rather than a
// convention, so it is spelt out here: `facts` is copied from the validated result and is
// what a downstream system may rely on; every `presentation.summary` names the fields it
// was built from in `cites`. A consumer that reads only `facts` loses nothing.
import type { PackingRequest, PackingResult, ResultFact } from './index.js';
export const FORMAT: 'packvium-execution-plan/v1';
export const UNNAMED_AXIS: string;
export class ExecutionPlanError extends Error {}
export interface PositionTicks{x:number;y:number;z:number}
/** How a step names a placement. Ticks are the exact integer coordinate, never a rendering. */
/** `placement_id` (1.10) is copied from the result placement when it carries one; `placementReference` alone never sets it. */
export interface PlacementReference{container_index:number;item_type:string;orientation:string;position_ticks:PositionTicks;placement_id?:string}
/** `sequence` is present only when a loading order was supplied; it is never derived. */
export interface ExecutionStep{sequence?:number;placement:PlacementReference}
export interface Presentation{summary:string;cites:string[]}
export interface ContainerFacts{container_type:string|null;placement_count:number;volume_utilization:string|null}
/** `order` is `'unavailable'` unless `loadingOrders` supplied one for this container. */
export interface PlanContainer{container_index:number;facts:ContainerFacts;order:'loading'|'unavailable';steps:ExecutionStep[]}
export interface UnplacedFacts{item_type:string|null;reason:string|null;proof_level:string|null;details:string[]}
export interface PlanUnplaced{facts:UnplacedFacts;presentation:Presentation}
/** `null` when the two scores are equal on every axis. */
export interface ScoreDifference{index:number;winner:number;alternative:number}
export interface AlternativeFacts{alternative_index:number;score:number[];status:string|null;first_difference:ScoreDifference|null}
export interface PlanAlternative{facts:AlternativeFacts;presentation:Presentation}
export interface PlanFacts{status:string;score:number[];feasibility:ResultFact|null;optimality:ResultFact|null;container_count:number}
export interface ExecutionPlan{format:string;objective:string|null;facts:PlanFacts;containers:PlanContainer[];alternatives:PlanAlternative[];unplaced:PlanUnplaced[]}
/** Throws `ExecutionPlanError` if the placement lacks `item_type`, `orientation` or a tick on any axis. */
export function placementReference(containerIndex:number,placement:unknown):PlacementReference;
/**
* Derive the plan for one already validated result. Calls no solver and no validator.
*
* `loadingOrders` maps a container index to a permutation of that container's placement
* indices; omit it and each container reports `order: 'unavailable'` with every placement
* still listed. An order that is not a permutation throws `ExecutionPlanError`.
*/
export function buildExecutionPlan(request:PackingRequest,result:PackingResult,options?:{loadingOrders?:Record<number,number[]>}):ExecutionPlan;
/** What `canonicalPlanJson` throws. The class is internal, so match on `code`, not `instanceof`. */
export interface CanonicalJsonError extends Error{code:'number_out_of_range'|'invalid_string'|'invalid_value'}
/**
* The one byte-comparable spelling: RFC 8785, keys sorted by UTF-16 code units, arrays left in
* place. Throws a `CanonicalJsonError` for a number beyond 2^53 - 1 or not finite, a lone
* surrogate, or a value JSON cannot spell.
*/
export function canonicalPlanJson(plan:ExecutionPlan):string;