@hatiolab/things-scene 10.0.0-beta.11 → 10.0.0-beta.111

package/dist-types/transfer/storage-rack-capability.d.ts

@@ -0,0 +1,144 @@
+import type { Pose6DOF } from '../math/index.js';
+/**
+ * Rack slot 의 3D 주소. 일반적인 columned rack 의 (Y 층, X 가로 칸, Z 깊이) — 단
+ * 모든 rack 이 3 차원 grid 인 것은 아니다 (예: 1D linear bin shelf, 2D 평면 grid).
+ * 구현자가 unused 차원을 0 으로 두면 됨. opaque 한 key string (`level.bay.depth`)
+ * 으로 직렬화 / Map 키 사용.
+ */
+export interface StorageSlotAddress {
+    /** 층 (Y 축). 0 = 바닥 층. */
+    readonly level: number;
+    /** 가로 칸 (X 축, aisle 방향). 0 = aisle 시작. */
+    readonly bay: number;
+    /** 깊이 (Z 축, aisle 에서 안쪽). 0 = aisle 면 (가장 가까운 slot). */
+    readonly depth: number;
+}
+/**
+ * Slot 의 *현재 상태* — read-only. carrier 가 들어있으면 occupant 노출, 비어있으면
+ * null. capability 외부 (WMS, monitor, simulation viewer) 가 generic 활용.
+ */
+export interface StorageSlotState {
+    readonly address: StorageSlotAddress;
+    /**
+     * Crane fork 가 도달할 *world pose* — slot 의 입출고 자세. position = slot 의
+     * 들어가는 입구 (= depth=0 면) 의 중심, rotation = fork 가 들어갈 자세 (보통
+     * aisle 방향 ±Z).
+     */
+    readonly pose: Pose6DOF;
+    /** Carrying 중인 박스/팰릿. null = empty. */
+    readonly occupant: unknown | null;
+    /**
+     * Slot 의 물리 제약. 선택. 구현자가 size / weight 제약을 노출하면 source 가
+     * pre-flight 매칭 가능.
+     */
+    readonly capacity?: {
+        readonly maxWeight?: number;
+        readonly maxBounds?: {
+            width: number;
+            height: number;
+            depth: number;
+        };
+    };
+    /**
+     * Application 도메인 metadata. SKU, lot, expiry, owner 등. 구현자 자유. WMS 가
+     * `findSlotsWithSKU` 같은 query 결과의 부가 정보로 사용 가능.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Put (= 저장) 또는 Pick (= 출고) reservation. source (crane) 가 자기 movement
+ * 시작 전 capability 에게 받음. commit 후 slot.occupant 가 변경됨.
+ *
+ * `direction` 으로 의도 분리 — same address 라도 put vs pick 의 pose / 제약이
+ * 다를 수 있음 (예: AutoStore digging — pick 시 위의 박스들 먼저 옮겨야 함).
+ */
+export interface StorageReservation {
+    readonly address: StorageSlotAddress;
+    readonly pose: Pose6DOF;
+    readonly direction: 'put' | 'pick';
+    /** Capability 가 자기 식별 용 opaque token. source 는 의미 모름. */
+    readonly token: symbol;
+}
+/**
+ * Slot search 기준. 모든 필드 optional — 비우면 *아무* free slot 반환.
+ */
+export interface SlotSearchCriteria {
+    /** SKU / barcode / type 매칭 — 같은 SKU 의 인접 슬롯 우선 (consolidation). */
+    readonly sku?: string;
+    /** 특정 address 인근 (Manhattan distance) 선호 — crane 이동 거리 최소화. */
+    readonly near?: StorageSlotAddress;
+    /** Carrier 크기 / 무게 제약. capacity 와 매칭. */
+    readonly requires?: {
+        readonly minWeight?: number;
+        readonly minBounds?: {
+            width: number;
+            height: number;
+            depth: number;
+        };
+    };
+}
+/**
+ * StorageRack capability contract.
+ *
+ * 구현자 (rack, AS/RS, AutoStore 등) 가 자기 sim 의 detail (선반 geometry, occupant
+ * map, SKU index, 다중 shuttle 큐잉) 모두 내부 구현으로 캡슐화. source (crane,
+ * shuttle, forklift) 는 이 interface 만 사용.
+ */
+export interface StorageRack {
+    /**
+     * 모든 slot 의 현재 상태. address key (`${level}.${bay}.${depth}`) → state.
+     * Read-only. 향후 *write* 확장 (sim state restore 등) plan.
+     */
+    readonly slots: ReadonlyMap<string, StorageSlotState>;
+    /**
+     * Address 로 직접 조회. 없으면 null (= 존재하지 않는 address, 또는 dispose 된 슬롯).
+     */
+    slotAt(address: StorageSlotAddress): StorageSlotState | null;
+    /**
+     * Putaway 용 free slot 검색. 정책 (LIFO/FIFO, optimal location, ABC 분류 등) 은
+     * 구현자 내부 — source 는 결과 address 만 받음. null = 빈 slot 없음.
+     */
+    findFreeSlot(criteria?: SlotSearchCriteria): StorageSlotAddress | null;
+    /**
+     * 특정 SKU 가 저장된 slot 들 반환. retrieval order 정책 (FIFO 등) 적용된 순서.
+     * 빈 배열 = 해당 SKU 없음.
+     */
+    findSlotsWithSKU(sku: string): readonly StorageSlotAddress[];
+    /**
+     * Putaway reservation — source 가 carrier 를 *어떤 address* 에 놓을지 commit
+     * 가능한 약속. null = 그 address 가 currently 사용 불가 (이미 점유 / 제약 미충족).
+     *
+     * Side-effect: capability 가 slot 을 *예약 마크* (다른 reservation 차단). 단
+     * occupant 는 commit 시점에 변경.
+     */
+    reservePut(address: StorageSlotAddress, item: unknown): StorageReservation | null;
+    /**
+     * Retrieval reservation — source 가 특정 address 의 박스를 *꺼낼* 약속.
+     * `expected` (optional) 로 occupant 확인 (예: WMS 의 SKU 가 실제 박스와 일치 검증).
+     * null = 그 address 가 비어있음 / 예상 박스 다름 / digging 필요 시그널.
+     */
+    reservePick(address: StorageSlotAddress, expected?: unknown): StorageReservation | null;
+    /**
+     * Reservation 확정 — slot.occupant 가 갱신. put 이면 item 이 occupant 로 들어가고,
+     * pick 이면 occupant 가 빠지고 occupant 가 source 에게 ownership 이전.
+     *
+     * idempotent — 같은 token 으로 중복 호출 시 noop (구현자 자유).
+     */
+    commitReservation(reservation: StorageReservation, item: unknown): void;
+    /**
+     * Reservation 취소 — 마크된 slot 해제. commit 후 호출 시 noop (idempotent).
+     * source 가 movement 도중 abort 했을 때 호출.
+     */
+    releaseReservation(reservation: StorageReservation): void;
+}
+/**
+ * Duck typing — target 이 StorageRack 노출 했는지 check. capability registry 없이
+ * runtime 매칭. 새 rack type 추가 시 *이 함수 외 다른 코드 변경 없음*.
+ */
+export declare function isStorageRack(target: unknown): target is StorageRack;
+/**
+ * Address ↔ string key 변환 — Map 키 / 직렬화 / 로그 출력 표준.
+ */
+export declare function addressKey(address: StorageSlotAddress): string;
+export declare function parseAddressKey(key: string): StorageSlotAddress | null;
+//# sourceMappingURL=storage-rack-capability.d.ts.map

package/dist-types/transfer/storage-rack-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-rack-capability.d.ts","sourceRoot":"","sources":["../../src/transfer/storage-rack-capability.ts"],"names":[],"mappings":"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"}

package/dist-types/transfer/tracer.d.ts

@@ -0,0 +1,35 @@
+import type { Transfer, TransferTraceEvent } from './transfer.js';
+/**
+ * tracer.log 의 호출자가 채우는 정보. atSimMs 는 자동.
+ * component 인자는 *componentId/componentType 추출* 위해. 직접 안 채워도 됨.
+ */
+export interface TraceLogInput {
+    role: 'source' | 'target' | 'carrier' | 'transfer';
+    contract: string;
+    component?: any;
+    componentId?: string;
+    componentType?: string;
+    args?: any;
+    result?: any;
+    error?: string;
+}
+export declare const transferTracer: {
+    /** Transfer 시작 시 호출 — 이후 log 호출은 *그 Transfer 의 trace 에 push*. */
+    beginContext(transfer: Transfer): void;
+    /** Transfer 완료/거부 시 호출 — standalone mode 로 복귀. */
+    endContext(): void;
+    /** 현재 active transfer (있다면). 디버깅용. */
+    current(): Transfer | null;
+    /**
+     * Contract 호출 시점 트레이스. ContainerCapacity 의 각 method 안에서 호출.
+     * active Transfer 가 있으면 그 trace 에, 없으면 standalone stream 에 push.
+     */
+    log(input: TraceLogInput): void;
+    /** Standalone trace events (Transfer 우회 호출의 누적). */
+    standaloneEvents(): readonly TransferTraceEvent[];
+    /** Standalone listener 등록. */
+    onStandalone(listener: (event: TransferTraceEvent) => void): () => void;
+    /** standalone stream 초기화. */
+    clearStandalone(): void;
+};
+//# sourceMappingURL=tracer.d.ts.map

package/dist-types/transfer/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../../src/transfer/tracer.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAiBjE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAA;IAClD,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,GAAG,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,IAAI,CAAC,EAAE,GAAG,CAAA;IACV,MAAM,CAAC,EAAE,GAAG,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,eAAO,MAAM,cAAc;IACzB,iEAAiE;2BAC1C,QAAQ,GAAG,IAAI;IAItC,kDAAkD;kBACpC,IAAI;IAIlB,sCAAsC;eAC3B,QAAQ,GAAG,IAAI;IAI1B;;;OAGG;eACQ,aAAa,GAAG,IAAI;IAwB/B,oDAAoD;wBAChC,SAAS,kBAAkB,EAAE;IAIjD,8BAA8B;2BACP,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKvE,6BAA6B;uBACV,IAAI;CAGxB,CAAA"}

package/dist-types/transfer/transfer.d.ts

@@ -0,0 +1,224 @@
+import type { Transferable, TransferOptions } from './types.js';
+export type TransferPhase = 'pending' | 'planning' | 'physical' | 'handoff' | 'committed' | 'rolled-back';
+export interface TransferTimeline {
+    initiatedAt: number;
+    planStartAt?: number;
+    planEndAt?: number;
+    physicalStartAt?: number;
+    physicalEndAt?: number;
+    handoffAt?: number;
+    committedAt?: number;
+}
+/**
+ * Transfer 의 negotiation / interaction 세부 trace. 각 contract method 호출 시점에
+ * Transfer.execute 가 기록 — 어떤 컴포넌트의 어떤 contract 가 호출되었고 결과가
+ * 무엇이었는지 시각화.
+ *
+ *   role       : 'source' | 'target' | 'carrier' | 'transfer'
+ *   contract   : 호출한 contract 이름 (e.g. 'canAccept', 'findSlot', 'accept', 'physical')
+ *   componentId: 호출 대상 컴포넌트의 id
+ *   componentType: 컴포넌트의 type
+ *   atSimMs    : sim time 기준 호출 시점
+ *   args       : 인자의 *serializable summary* (carrier id, slot id 등)
+ *   result     : 반환값의 *serializable summary* (ok / reason / slotId 등)
+ *   error      : throw 시 메시지
+ */
+export interface TransferTraceEvent {
+    role: 'source' | 'target' | 'carrier' | 'transfer';
+    contract: string;
+    componentId?: string;
+    componentType?: string;
+    atSimMs: number;
+    args?: any;
+    result?: any;
+    error?: string;
+}
+export interface TransferReceipt {
+    transferId: string;
+    source: any;
+    target: any;
+    carrier: any;
+    /** Phase G7 — 직렬화 용. live refs 가 GC 되어도 보존되는 식별자. */
+    sourceId?: string;
+    targetId?: string;
+    carrierId?: string;
+    phase: TransferPhase;
+    timeline: TransferTimeline;
+    slotId?: string;
+    rejectReason?: string;
+    /** Phase G10 — negotiation / interaction trace events. */
+    traceEvents?: TransferTraceEvent[];
+    /**
+     * Phase G11 — open-ended metadata. physical phase 가 *target-specific* 정보를
+     * 기록 (예: sorter 의 carrierId, cross-belt-line 의 carrier index). panel 의
+     * 컬럼 등 진단 시각화에서 사용.
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * TransferReceipt 의 직렬화 형태 — live ref 제외, ID 만. JSON.stringify 안전.
+ * Phase G7 의 snapshot/replay 용.
+ */
+export interface TransferReceiptJSON {
+    transferId: string;
+    sourceId?: string;
+    targetId?: string;
+    carrierId?: string;
+    phase: TransferPhase;
+    timeline: TransferTimeline;
+    slotId?: string;
+    rejectReason?: string;
+}
+/**
+ * Receipt 의 plain JSON 변환. live ref 제외, undefined 필드 omit (JSON
+ * round-trip 결정성 보장).
+ */
+export declare function receiptToJSON(receipt: TransferReceipt): TransferReceiptJSON;
+/**
+ * Source 가 physical 단계에서 사용하는 운반 함수. logical-only source
+ * (Conveyor.dispatch 등) 는 noop 으로 즉시 resolve.
+ *
+ * 호출 시점: Transfer 의 physical phase 진입.
+ * 반환: physical 운반 완료 (carrier 가 target.deliveryPose 에 도달) 시 resolve.
+ */
+export type PhysicalRunner = () => Promise<void>;
+export interface TransferLogStats {
+    total: number;
+    byPhase: Record<string, number>;
+    committed: number;
+    rolledBack: number;
+    rejectionRate: number;
+    avgTransferDurationMs: number;
+}
+export interface TransferInit {
+    source: any;
+    target: Transferable;
+    carrier: any;
+    options?: TransferOptions;
+    /** physical 운반자 (RobotArm, AGV 등). 미지정 시 즉시 통과. */
+    physical?: PhysicalRunner;
+}
+/**
+ * Transfer — 한 carrier 의 source → target 이동 사건.
+ *
+ * 사용:
+ *   const t = new Transfer({ source, target, carrier, options })
+ *   const receipt = await t.execute()
+ *
+ * 또는 Transferable.dispatch 가 내부적으로:
+ *   const t = new Transfer({ source: this, target, carrier, options })
+ *   await t.execute()
+ */
+export declare class Transfer {
+    readonly id: string;
+    readonly source: any;
+    readonly target: Transferable;
+    readonly carrier: any;
+    readonly options: TransferOptions;
+    readonly physical: PhysicalRunner | null;
+    private _phase;
+    private _timeline;
+    private _slot;
+    private _rejectReason?;
+    private _traceEvents;
+    /**
+     * Phase G11 — target-specific metadata. physical phase 가 *sorter carrier
+     * index* 등 contract 외 진단 정보 기록. receipt 의 meta 로 시각화.
+     */
+    readonly meta: Record<string, unknown>;
+    constructor(init: TransferInit);
+    /**
+     * Transfer trace 에 contract 호출 이벤트 push. Transfer.execute 가 명시 contract
+     * 호출 시 직접 사용 + ContainerCapacity.receive 등 *내부 contract* 도 *current
+     * transfer* 의 trace 에 push 가능 (currentTransfer module-level singleton).
+     */
+    pushTrace(event: Omit<TransferTraceEvent, 'atSimMs'> & {
+        atSimMs?: number;
+    }): void;
+    get phase(): TransferPhase;
+    get timeline(): Readonly<TransferTimeline>;
+    /**
+     * 5-phase 실행. 각 phase 진입 시 timeline 갱신, 완료 시 receipt 반환.
+     *
+     * Negotiate / Plan 단계에서 거부 → rolled-back receipt.
+     * Physical 단계에서 throw → rolled-back receipt.
+     * Handoff 이후 throw 는 일관성 깨질 수 있으므로 그대로 propagate.
+     */
+    execute(): Promise<TransferReceipt>;
+    /**
+     * Sync 흐름 (= _tickLiveItems 매 frame iteration 안에서 dispatch) 전용 변형.
+     * physical / handoff 가 sync function 일 때만 동작 — async 면 *fire-and-forget*
+     * 으로 백그라운드 실행 (receipt 는 sync committed 표시).
+     *
+     * Async transfer 가 매 frame 동기 iteration 안에서 *sync 결과 필요* (= 박스 처리
+     * 끝 신호) 한 케이스. _tryDispatchToSorter / _ejectComponent 의 sync 흐름과 호환.
+     */
+    executeSync(): TransferReceipt;
+    private _executeImpl;
+    /**
+     * physical / planning 도중 외부 취소. handoff 이후엔 호출 금지 (이미 commit 됨).
+     * 현재 구현은 phase 만 표시하고 carrier 의 상태는 건드리지 않음 — physical
+     * 운반자가 자체 cancel 책임.
+     */
+    rollback(): void;
+    private _buildReceipt;
+}
+/**
+ * 모든 Transfer 의 receipt 를 기록하는 singleton. observability 의 기반.
+ * Phase G7 — JSON snapshot/load 지원으로 외부 도구 (Chrome extension 등) 에서
+ * 라이브 또는 저장된 로그를 동일하게 시각화할 수 있다.
+ */
+declare class TransferLogImpl {
+    private _entries;
+    private _maxEntries;
+    private _listeners;
+    append(receipt: TransferReceipt): void;
+    /** 모든 receipt 반환 (read-only 사본). */
+    entries(): readonly TransferReceipt[];
+    /** carrier 별 transfer 이력. live ref 매칭 우선, fallback 으로 carrierId. */
+    forCarrier(carrier: any): readonly TransferReceipt[];
+    /** carrierId 로 직접 조회 (snapshot 복원 후 등 live ref 가 없을 때). */
+    forCarrierId(carrierId: string): readonly TransferReceipt[];
+    /** sourceId 로 조회 — 특정 vehicle / source 의 transfer 이력. */
+    forSourceId(sourceId: string): readonly TransferReceipt[];
+    /** targetId 로 조회 — 특정 holder 의 receive 이력. */
+    forTargetId(targetId: string): readonly TransferReceipt[];
+    /** phase 별 필터 (e.g. 'rolled-back' 만 — 실패 진단). */
+    forPhase(phase: TransferPhase): readonly TransferReceipt[];
+    /**
+     * sim-time 범위로 필터. transfer 의 initiatedAt 이 [startSimMs, endSimMs] 안에 있는지.
+     * 'overlap' 모드 — initiatedAt..committedAt 윈도우가 query 윈도우와 겹치면 포함.
+     */
+    inTimeRange(startSimMs: number, endSimMs: number, mode?: 'init' | 'overlap'): readonly TransferReceipt[];
+    /** rejectReason 별 그룹화 — 실패 패턴 진단. */
+    groupByRejectReason(): Map<string, readonly TransferReceipt[]>;
+    /** 통계 — 전체 / phase 별 / 거부율 / 평균 transfer 시간 등. */
+    stats(): TransferLogStats;
+    /** 새 receipt 마다 호출되는 listener 등록. */
+    subscribe(listener: (receipt: TransferReceipt) => void): () => void;
+    clear(): void;
+    setMaxEntries(n: number): void;
+    /**
+     * 모든 receipt 를 JSON 안전한 plain object 배열로. live ref 제외, ID 만 포함.
+     * JSON.stringify(transferLog.toJSON()) 안전.
+     */
+    toJSON(): TransferReceiptJSON[];
+    /**
+     * JSON 배열에서 entries 복원 (기존 entries 대체). 외부 viewer (extension) 가
+     * 저장된 로그를 로드해서 시각화할 때 사용.
+     *
+     * 복원된 receipt 는 source/target/carrier 의 live ref 가 undefined — ID 만으로
+     * 추적 (forCarrierId, sourceId, targetId 등). listener 에는 알림 안 함 (load
+     * 는 silent).
+     */
+    fromJSON(json: TransferReceiptJSON[]): void;
+    /**
+     * 저장된 로그를 listener 에게 순서대로 다시 발화 — extension 이 세션 시작 시
+     * 기존 entries 도 받고 싶을 때. listener 가 새 receipt 와 replayed receipt 를
+     * 구분 못 하므로 호출자가 의도적으로 사용.
+     */
+    replayTo(listener: (receipt: TransferReceipt) => void): void;
+}
+export declare const transferLog: TransferLogImpl;
+export {};
+//# sourceMappingURL=transfer.d.ts.map

package/dist-types/transfer/transfer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.d.ts","sourceRoot":"","sources":["../../src/transfer/transfer.ts"],"names":[],"mappings":"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"}