@hatiolab/things-scene 10.0.0-beta.14 → 10.0.0-beta.140

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transfer/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,IAAI,EACJ,KAAK,EACL,OAAO,EACP,eAAe,EACf,SAAS,EACT,OAAO,EACP,cAAc,EACd,eAAe,EACf,YAAY,EACZ,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,IAAI,EACJ,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,EACP,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,UAAU,EACV,SAAS,EAET,QAAQ,EACR,cAAc,EACd,WAAW,EACX,eAAe,EACf,QAAQ,EAER,WAAW,EACX,gBAAgB,EAChB,WAAW,EACZ,MAAM,YAAY,CAAA;AAOnB,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAGnF,OAAO,EACL,WAAW,EACX,0BAA0B,EAC1B,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAE1F,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAIzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAE5D,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAI9C,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AACpE,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,kBAAkB,EACnB,MAAM,eAAe,CAAA;AAGtB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAGhD,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACV,MAAM,8BAA8B,CAAA;AAIrC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,QAAQ,EACR,aAAa,EACb,aAAa,EACb,kBAAkB,EACnB,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EACV,YAAY,EACZ,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,eAAe,EACf,SAAS,EACT,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,SAAS,EACT,QAAQ,EACR,cAAc,EACd,OAAO,EACP,OAAO,EACP,oBAAoB,EACrB,MAAM,wBAAwB,CAAA;AAG/B,cAAc,0BAA0B,CAAA;AACxC,cAAc,8BAA8B,CAAA;AAI5C,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,kCAAkC,CAAA"}

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

@@ -0,0 +1,75 @@
+import type { PickupFrame, PickupRequester, Vec3, QuatLike, PoseSerialized } from './types.js';
+/**
+ * Y 축 (3D vertical) 회전을 quaternion 으로. Three.js 없이 직접 계산 (cross-package
+ * 호환성).
+ *
+ *   q = (0, sin(θ/2), 0, cos(θ/2))
+ */
+export declare function quatFromYaw(yawRad: number): QuatLike;
+export interface RectangularFootprintOptions {
+    /** carrier 의 world pose — entry 들이 이 frame 기준으로 회전/병진된다. */
+    carrierWorld: PoseSerialized;
+    /** carrier 의 가로 (X 방향). */
+    width: number;
+    /** carrier 의 세로 (Z 방향). */
+    depth: number;
+    /** entry(grab)가 carrier 의 어느 높이에 있는가 (carrier-local Y). 도구가 닿는 지점. */
+    entryHeight: number;
+    /**
+     * *운반 중* carrier 가 도구에 실릴 때 도구 attach point 에 오는 하중면의 carrier-local Y
+     * (선택). fork 는 상판 아래면, deck 는 바닥. 미지정 시 mount 없음 → 도구 default(얹기).
+     */
+    mountLocalY?: number;
+    /** approach 가 engage 에서 얼마나 떨어진 거리. */
+    approachDistance: number;
+    /** 어느 면에 entry 를 둘지. 'east'+'west' = 2-way, 4 개 다 = 4-way. */
+    sides: ReadonlyArray<'east' | 'west' | 'north' | 'south'>;
+    /** entry 의 toolType. 모두 동일하면 string, 면별 다르면 map. */
+    toolType: string | Partial<Record<'east' | 'west' | 'north' | 'south', string>>;
+    /** entry 의 tolerance. */
+    tolerance?: PickupFrame['tolerance'];
+    /** entry 의 priority. */
+    priority?: number;
+}
+/**
+ * 직사각형 carrier 의 N-면 진입 entry 들을 한꺼번에 생성.
+ *
+ * 각 entry 의 engage 는 carrier 의 해당 면 중심 (carrier-local), approach 는
+ * 그 외부 approachDistance 만큼 떨어진 점. 도구는 carrier 쪽을 향한 채 (yaw)
+ * 다가오는 자세.
+ */
+export declare function rectangularFootprintFrames(options: RectangularFootprintOptions): PickupFrame[];
+export interface TopApproachOptions {
+    carrierWorld: PoseSerialized;
+    /** carrier 의 top 표면 Y (carrier-local). */
+    topY: number;
+    /** approach 가 top 에서 얼마나 위에 있는가. */
+    approachDistance: number;
+    toolType: string;
+    /**
+     * 운반 중 도구 attach 에 오는 하중면 carrier-local Y (선택). 위에서 집는 도구는 보통
+     * top 표면(=topY), 밑으로 들어가 얹는 deck 는 바닥. 미지정 시 mount 없음(도구 default).
+     */
+    mountLocalY?: number;
+    tolerance?: PickupFrame['tolerance'];
+    priority?: number;
+    id?: string;
+}
+/**
+ * 위쪽 한 점 진입 (예: vacuum gripper 로 box 집기, 자석으로 철판 들기).
+ *
+ * engage 는 carrier 의 top 표면 중심, approach 는 그 위 approachDistance.
+ * 도구는 carrier 위에서 수직 하강 — yaw 보존 (도구가 회전하지 않음).
+ */
+export declare function topApproachFrame(options: TopApproachOptions): PickupFrame;
+/**
+ * Pickable.pickupFramesFor 의 기본 구현. 도구 type 일치하는 entry 만 통과.
+ * tool footprint 까지 검사하고 싶으면 carrier 가 자체 override.
+ */
+export declare function filterByToolType(frames: PickupFrame[], requester: PickupRequester): PickupFrame[];
+/**
+ * 두 entry 중 source 위치에 더 가까운 것을 고르는 helper. distance 는 approach
+ * pose 위치 기준. priority 가 다르면 priority 우선.
+ */
+export declare function chooseNearestPickupFrame(frames: PickupFrame[], fromWorldPosition: Vec3): PickupFrame | null;
+//# sourceMappingURL=pickup-helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pickup-helpers.d.ts","sourceRoot":"","sources":["../../src/transfer/pickup-helpers.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAI9F;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAQpD;AA2CD,MAAM,WAAW,2BAA2B;IAC1C,4DAA4D;IAC5D,YAAY,EAAE,cAAc,CAAA;IAC5B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,CAAA;IACxB,8DAA8D;IAC9D,KAAK,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,CAAA;IACzD,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/E,yBAAyB;IACzB,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAA;IACpC,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAYD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,WAAW,EAAE,CAyD9F;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,cAAc,CAAA;IAC5B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,oCAAoC;IACpC,gBAAgB,EAAE,MAAM,CAAA;IACxB,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAA;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAuBzE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EAAE,EACrB,SAAS,EAAE,eAAe,GACzB,WAAW,EAAE,CAEf;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,WAAW,EAAE,EACrB,iBAAiB,EAAE,IAAI,GACtB,WAAW,GAAG,IAAI,CAkBpB"}

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

@@ -0,0 +1,45 @@
+export interface SimulationClock {
+    /**
+     * Simulated time elapsed since clock creation (ms).
+     * Advances only when speed > 0 and the clock is running.
+     */
+    readonly now: number;
+    /**
+     * Time scale factor.
+     *   1.0 = real-time
+     *   2.0 = double speed
+     *   0   = paused (tick() returns 0, now stays fixed)
+     * Setting speed resumes a paused clock.
+     */
+    speed: number;
+    readonly isPaused: boolean;
+    pause(): void;
+    resume(): void;
+    /**
+     * Called from a requestAnimationFrame loop with the real wall-clock delta.
+     * Returns the scaled simulation delta that components should use for physics.
+     *
+     * If paused (speed === 0), returns 0 and does not advance `now`.
+     * Clamps realDeltaMs to 200 ms to prevent spiral-of-death on tab resume.
+     */
+    tick(realDeltaMs: number): number;
+    /**
+     * Advance the clock by exactly `dt` simulation milliseconds, bypassing speed.
+     * Intended for unit tests and deterministic replay — do NOT call from RAF.
+     */
+    step(dt: number): void;
+    /** Register a listener called after each tick / step with the scaled delta. */
+    onTick(listener: (dt: number) => void): () => void;
+}
+/**
+ * The scene-wide SimulationClock instance.
+ *
+ * ConveyanceContainer, Mover and all time-dependent mixins call:
+ *   const dt = globalSimClock.tick(realDeltaMs)
+ *
+ * Tests use:
+ *   globalSimClock.step(100) // advance 100 ms deterministically
+ *   globalSimClock.speed = 5 // run at 5× for the next tick
+ */
+export declare const globalSimClock: SimulationClock;
+//# sourceMappingURL=simulation-clock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"simulation-clock.d.ts","sourceRoot":"","sources":["../../src/transfer/simulation-clock.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAE1B,KAAK,IAAI,IAAI,CAAA;IACb,MAAM,IAAI,IAAI,CAAA;IAEd;;;;;;OAMG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAA;IAEjC;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IAEtB,+EAA+E;IAC/E,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CACnD;AAyDD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,EAAE,eAAwC,CAAA"}

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 호출 시점 트레이스. FlowNode 의 각 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-helpers.d.ts

@@ -0,0 +1,18 @@
+export declare function _carrierSummary(carrier: any): {
+    id: any;
+    type: any;
+};
+/**
+ * Phase PS P3a — holder-local quaternion → state rotation 필드 매핑.
+ * (rotationX, -rotation, rotationY) 컨벤션 — RealObject.rotation getter 의 역.
+ * receive 의 contract 경로 / legacy 경로가 공유하는 단일 매핑 지점.
+ */
+export declare function applySeatingRotation(update: Record<string, number>, q: {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}): void;
+/** Key used to store the current slot assignment on a child component. */
+export declare const TRANSFER_SLOT_KEY = "_transferSlotId";
+//# sourceMappingURL=transfer-helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transfer-helpers.d.ts","sourceRoot":"","sources":["../../src/transfer/transfer-helpers.ts"],"names":[],"mappings":"AASA,wBAAgB,eAAe,CAAC,OAAO,EAAE,GAAG;;;EAK3C;AAKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,CAAC,EAAE;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,IAAI,CAUN;AAED,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,oBAAoB,CAAA"}

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

@@ -0,0 +1,257 @@
+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;
+    /** Phase 4c — 라이프사이클 예약(reserve→commit). null = 예약 미사용(capability-only/비-라이프사이클 target). */
+    private _reservation;
+    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
+     * 호출 시 직접 사용 + FlowNode.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>;
+    /** rolled-back receipt 생성 (this._rejectReason 은 호출자가 먼저 설정). */
+    private _rollback;
+    /**
+     * planning(canAccept verdict → slot 결정) + reserve. 조기 거부 시 rolled-back
+     * receipt 를, 계속 진행이면 null 을 반환. this._slot / this._reservation 설정.
+     *
+     * 협상 분기는 "메서드 존재" 추측이 아니라 홀더가 선언한 slot 모델 유무(canAccept 의
+     * verdict)로 나뉜다. no-slots-defined = slot 식이 아님 → capability-only(handoff 의
+     * holder.receive 가 자체 게이트 책임). canReceive fallback 은 canAccept 미구현 최소 mock 용.
+     */
+    private _planAndReserve;
+    /** physical 실패 공통 처리 — 예약 롤백 + rolled-back receipt. */
+    private _physicalFailed;
+    /** handoff 실패 공통 처리 — rolled-back receipt 등록 후 throw(호출자 전파). */
+    private _handoffFailed;
+    /**
+     * handoff commit 분기 — 예약이 있으면 commit(원자 확정) 후 true. 예약 없으면 false
+     * (호출자가 receive fallback 담당). commit throw → 예약 롤백 + _handoffFailed(throw).
+     */
+    private _commitReserved;
+    /** committed receipt 생성. */
+    private _finishCommitted;
+    private _runPhysicalSync;
+    private _runPhysicalAsync;
+    private _runReceiveSync;
+    private _runReceiveAsync;
+    /**
+     * 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 등) 에서
+ * 라이브 또는 저장된 로그를 동일하게 시각화할 수 있다.
+ */
+/**
+ * TransferLogImpl — Step 1 정공 (2026-06-20):
+ *
+ * Raw receipt 1000 보관 폐기 → aggregated O(1) maintain. 본체 runtime 은 raw 사용 0
+ * (모든 reader 는 diagnostics — extension/devtools RPC). 본체가 extension buffer 역할
+ * 하던 안티패턴 제거.
+ *
+ * raw 가 필요한 도구 (carrier 별 timeline 등) 는 `subscribe` 패턴으로 extension 측
+ * 자체 누적 (Step 7).
+ */
+declare class TransferLogImpl {
+    private _flows;
+    private _targetCount;
+    private _byPhase;
+    private _byRejectReason;
+    private _total;
+    private _committedDurationSum;
+    private _committedCount;
+    private _listeners;
+    append(receipt: TransferReceipt): void;
+    /** "src>tgt" → committed transfer count. inspector.topologyStats 활용. */
+    flows(): ReadonlyMap<string, number>;
+    /** targetId → 도착 count. distribution 계산 source. */
+    targetCounts(): ReadonlyMap<string, number>;
+    /** 통계 — aggregated 기반 O(1). */
+    stats(): TransferLogStats;
+    /** rejectReason 별 count — aggregated O(1). */
+    rejectReasonCounts(): ReadonlyMap<string, number>;
+    /** 새 receipt 마다 호출되는 listener 등록. extension 측 raw 누적 path. */
+    subscribe(listener: (receipt: TransferReceipt) => void): () => void;
+    clear(): void;
+    /** @deprecated raw entries 보관 폐기. extension 측 subscribe 패턴 사용. */
+    entries(): readonly TransferReceipt[];
+    /** @deprecated */
+    forCarrier(_carrier: any): readonly TransferReceipt[];
+    /** @deprecated */
+    forCarrierId(_carrierId: string): readonly TransferReceipt[];
+    /** @deprecated */
+    forSourceId(_sourceId: string): readonly TransferReceipt[];
+    /** @deprecated */
+    forTargetId(_targetId: string): readonly TransferReceipt[];
+    /** @deprecated */
+    forPhase(_phase: TransferPhase): readonly TransferReceipt[];
+    /** @deprecated */
+    inTimeRange(_startSimMs: number, _endSimMs: number, _mode?: 'init' | 'overlap'): readonly TransferReceipt[];
+    /** @deprecated raw entries 폐기. rejectReasonCounts() 사용. */
+    groupByRejectReason(): Map<string, readonly TransferReceipt[]>;
+    /** @deprecated raw 보관 폐기 — toJSON 빈 array. */
+    toJSON(): TransferReceiptJSON[];
+    /** @deprecated raw 보관 폐기 — fromJSON noop. */
+    fromJSON(_json: TransferReceiptJSON[]): void;
+    /** @deprecated raw 보관 폐기 — replayTo noop. */
+    replayTo(_listener: (receipt: TransferReceipt) => void): void;
+    /** @deprecated raw 보관 폐기 — setMaxEntries noop. */
+    setMaxEntries(_n: number): 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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"}