@hatiolab/things-scene 10.0.0-beta.13 → 10.0.0-beta.131

package/dist-types/diagnostics/loading-overlay.d.ts

@@ -0,0 +1,58 @@
+import type { LoadTracker } from './load-tracker.js';
+import type { DataLagTracker } from './data-lag-tracker.js';
+export declare class LoadingOverlay {
+    private _tracker?;
+    private _lagTracker?;
+    private _container?;
+    private _targetElement?;
+    private _updateTimer?;
+    private _visible;
+    private _manualOpen;
+    /**
+     * 로딩 취소 콜백. 호스트(앱)가 "무엇이 취소인지"를 정의한다.
+     * 미지정 시 window.history.back()(뒤로가기)으로 폴백한다.
+     */
+    onCancel?: () => void;
+    private _headerEl?;
+    private _progressFillEl?;
+    private _progressTextEl?;
+    private _phaseListEl?;
+    private _phaseRenderedCount;
+    private _pendingListEl?;
+    private _lagSectionEl?;
+    private _footerRowEl?;
+    attach(targetElement: HTMLElement, tracker?: LoadTracker, lagTracker?: DataLagTracker): void;
+    toggle(): void;
+    show(): void;
+    hide(): void;
+    destroy(): void;
+    get isVisible(): boolean;
+    get isAttached(): boolean;
+    private _show;
+    private _hide;
+    private _update;
+    private _updateProgress;
+    private _updatePhaseList;
+    private _updateAssetList;
+    private _updateLagDisplay;
+    private _renderHistorySummary;
+    /**
+     * 게이지 좌표 계산 — **baseline 은 항상 트랙 중심(50%)**, 좌우 대칭 스케일로 매핑한다.
+     * (tracker 가 워밍업 중에도 러닝 평균을 baseline 으로 주므로 baseline 은 늘 [min,max] 안의 실제 값.)
+     * 반경 R = 중심에서 더 먼 극단까지 거리 = max(baseline−min, max−baseline), 최소 ±1초 floor.
+     * 먼 쪽 극단만 끝(0% / 100%)에 닿고, 가까운 쪽 극단은 안쪽에 놓인다 —
+     * 시각적 거리 = 실제 ms 편차에 정비례. cur<baseline→왼쪽(leading), cur>baseline→오른쪽(lagging).
+     */
+    private _lagGauge;
+    /** 중심(50%)→cur 채움 막대의 left/width CSS. */
+    private _lagFill;
+    private _renderLagSection;
+    private _createPendingRow;
+    private _updatePendingRow;
+    private _updateLagSection;
+    private _shortUrl;
+    /** 로딩 취소 — 오버레이를 닫고, onCancel 지정 시 그것을, 아니면 브라우저 뒤로가기. */
+    private _cancel;
+    private _buildDOM;
+}
+//# sourceMappingURL=loading-overlay.d.ts.map

package/dist-types/diagnostics/loading-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loading-overlay.d.ts","sourceRoot":"","sources":["../../src/diagnostics/loading-overlay.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAwB,MAAM,mBAAmB,CAAA;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAY,MAAM,uBAAuB,CAAA;AAiDrE,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,CAAa;IAC9B,OAAO,CAAC,WAAW,CAAC,CAAgB;IACpC,OAAO,CAAC,UAAU,CAAC,CAAgB;IACnC,OAAO,CAAC,cAAc,CAAC,CAAa;IACpC,OAAO,CAAC,YAAY,CAAC,CAAgC;IACrD,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,WAAW,CAAQ;IAE3B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IAGrB,OAAO,CAAC,SAAS,CAAC,CAAa;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAa;IACrC,OAAO,CAAC,eAAe,CAAC,CAAa;IACrC,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,OAAO,CAAC,mBAAmB,CAAI;IAC/B,OAAO,CAAC,cAAc,CAAC,CAAa;IACpC,OAAO,CAAC,aAAa,CAAC,CAAa;IACnC,OAAO,CAAC,YAAY,CAAC,CAAa;IAElC,MAAM,CAAC,aAAa,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI;IAsC5F,MAAM,IAAI,IAAI;IAUd,IAAI,IAAI,IAAI;IAKZ,IAAI,IAAI,IAAI;IAKZ,OAAO,IAAI,IAAI;IAYf,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAID,OAAO,CAAC,KAAK;IA4Bb,OAAO,CAAC,KAAK;IAYb,OAAO,CAAC,OAAO;IAkCf,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,gBAAgB;IAsDxB,OAAO,CAAC,gBAAgB;IAwCxB,OAAO,CAAC,iBAAiB;IAgBzB,OAAO,CAAC,qBAAqB;IA8B7B;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAYjB,yCAAyC;IACzC,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,iBAAiB;IAmCzB,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,iBAAiB;IA4CzB,OAAO,CAAC,SAAS;IAOjB,0DAA0D;IAC1D,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,SAAS;CA2GlB"}

package/dist-types/diagnostics/metrics.d.ts

@@ -8,6 +8,12 @@ interface ResidentData {
     }>;
 }
 declare class SceneMetrics {
+    /**
+     * Opt-in 게이트. 디폴트 OFF — Chrome 확장이 없을 때 hot path 측정 비용 0.
+     * 확장의 injected.js 가 scene 발견 시 enable() 호출.
+     * 확장 미설치 사용자는 카운터 증가 / performance.now() / FrameClock 측정 모두 건너뜀.
+     */
+    enabled: boolean;
     drawCount: number;
     drawTimeSum: number;
     drawTimeLast: number;
@@ -18,6 +24,10 @@ declare class SceneMetrics {
     private _lastSnapshotTime;
     private _frameCount;
     private _getResidents;
+    /** 측정 활성화 — 누적된 stale 카운터를 리셋하고 게이트를 켠다. */
+    enable(): void;
+    /** 측정 비활성화 — hot path 다시 0 비용. */
+    disable(): void;
     /**
      * Component/Scene/ReferenceMap에서 resident 데이터를 제공하는 함수를 등록한다.
      * things-scene/index.ts에서 모든 모듈 로드 후 1회 호출.

package/dist-types/diagnostics/metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/diagnostics/metrics.ts"],"names":[],"mappings":"AAQA,UAAU,YAAY;IACpB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,mBAAmB,EAAE,MAAM,CAAA;IAC3B,0BAA0B,EAAE,MAAM,CAAA;IAClC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED,cAAM,YAAY;IAEhB,SAAS,SAAI;IACb,WAAW,SAAI;IACf,YAAY,SAAI;IAGhB,eAAe,SAAI;IAGnB,YAAY,SAAI;IAGhB,QAAQ,SAAI;IACZ,SAAS,SAAI;IAGb,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,WAAW,CAAI;IAGvB,OAAO,CAAC,aAAa,CAAoC;IAEzD;;;OAGG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,YAAY;IAI5C;;;OAGG;IACH,UAAU,IAAI,IAAI;IAIlB;;;;OAIG;IACH,QAAQ;;;;;gBA/C6B,MAAM;kBAAQ,MAAM;;;;;;;;;;CAwF1D;AAED,eAAO,MAAM,OAAO,cAAqB,CAAA"}
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/diagnostics/metrics.ts"],"names":[],"mappings":"AAQA,UAAU,YAAY;IACpB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,mBAAmB,EAAE,MAAM,CAAA;IAC3B,0BAA0B,EAAE,MAAM,CAAA;IAClC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED,cAAM,YAAY;IAChB;;;;OAIG;IACH,OAAO,UAAQ;IAGf,SAAS,SAAI;IACb,WAAW,SAAI;IACf,YAAY,SAAI;IAGhB,eAAe,SAAI;IAGnB,YAAY,SAAI;IAGhB,QAAQ,SAAI;IACZ,SAAS,SAAI;IAGb,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,WAAW,CAAI;IAGvB,OAAO,CAAC,aAAa,CAAoC;IAEzD,4CAA4C;IAC5C,MAAM,IAAI,IAAI;IAad,kCAAkC;IAClC,OAAO,IAAI,IAAI;IAIf;;;OAGG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,YAAY;IAI5C;;;OAGG;IACH,UAAU,IAAI,IAAI;IAIlB;;;;OAIG;IACH,QAAQ;;;;;gBAzE6B,MAAM;kBAAQ,MAAM;;;;;;;;;;CAsH1D;AAED,eAAO,MAAM,OAAO,cAAqB,CAAA"}

package/dist-types/effect/shadow.d.ts

@@ -1,3 +1,5 @@
-export declare function setShadow(context: CanvasRenderingContext2D, shadow: any, component: any): void;
+import type { Component } from '../types/component';
+import type { Shadow } from '../interfaces/rendering';
+export declare function setShadow(context: CanvasRenderingContext2D, shadow: Shadow, component: Component): void;
 export declare function resetShadow(context: CanvasRenderingContext2D): void;
 //# sourceMappingURL=shadow.d.ts.map

package/dist-types/effect/shadow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../src/effect/shadow.ts"],"names":[],"mappings":"AAWA,wBAAgB,SAAS,CAAC,OAAO,EAAE,wBAAwB,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,QASvF;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,wBAAwB,QAE5D"}
+{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../src/effect/shadow.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AA6CrD,wBAAgB,SAAS,CACvB,OAAO,EAAE,wBAAwB,EACjC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,GACnB,IAAI,CAWN;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAEnE"}

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

@@ -4,5 +4,6 @@ import './shift-handler.js';
 import './zoom-handler.js';
 import './paste-handler.js';
 import './waypoint-handler.js';
+import './transition-handler.js';
 export { default as EventMap } from './event-map.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/event-map/index.ts"],"names":[],"mappings":"AAIA,OAAO,uBAAuB,CAAA;AAC9B,OAAO,mBAAmB,CAAA;AAC1B,OAAO,oBAAoB,CAAA;AAC3B,OAAO,mBAAmB,CAAA;AAC1B,OAAO,oBAAoB,CAAA;AAC3B,OAAO,uBAAuB,CAAA;AAE9B,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/event-map/index.ts"],"names":[],"mappings":"AAIA,OAAO,uBAAuB,CAAA;AAC9B,OAAO,mBAAmB,CAAA;AAC1B,OAAO,oBAAoB,CAAA;AAC3B,OAAO,mBAAmB,CAAA;AAC1B,OAAO,oBAAoB,CAAA;AAC3B,OAAO,uBAAuB,CAAA;AAC9B,OAAO,yBAAyB,CAAA;AAEhC,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAA"}

package/dist-types/event-map/transition-handler.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transition-handler.d.ts.map

package/dist-types/event-map/transition-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-handler.d.ts","sourceRoot":"","sources":["../../src/event-map/transition-handler.ts"],"names":[],"mappings":""}

package/dist-types/flow/auto-route.d.ts

@@ -0,0 +1,36 @@
+import { type SegmentTopology, type SegmentBounds, type MatchTolerance } from './segment-topology.js';
+interface SegmentLike {
+    state?: {
+        id?: string;
+    };
+    parent?: any;
+    rootModel?: any;
+    root?: any;
+    getSegmentTopology(): SegmentTopology;
+}
+/**
+ * Component tree 의 *_getSegmentTopology 를 노출하는 component_* 모두 수집.
+ * 자기 자신 제외. id 없는 컴포넌트 제외 (= downstreamRef target 으로 사용 불가).
+ *
+ * traversal 시작점 — *_self.parent_* (= model-layer 등 sibling 영역). 만약
+ * sibling 만으로 부족하면 *_rootModel 또는 root 의 재귀 descend_* 까지. things-
+ * scene 의 root 는 RootContainer 라 *_.components 가 layer 들_*만 — 우리 segment
+ * 는 model-layer 자식 이므로 sibling 또는 재귀 필요.
+ */
+export declare function collectAdjacentSegments(startRoot: any, exclude: any): Array<{
+    id: string;
+    topology: SegmentTopology;
+    bounds?: SegmentBounds;
+}>;
+/**
+ * 자기 outbound 의 *_가장 가까운 downstream segment id_*. inbound 가진 후보들
+ * 만 매칭. multi-outbound segment 의 경우 outbound[0] 만 — 분기 segment 는
+ * 자체 logic 으로 override 권장.
+ *
+ * traversal 시작점: self.parent (= 직접 sibling 영역) 우선, 부재 시 rootModel
+ * → root fallback. RootContainer 의 .components 가 layer 들이라 *_재귀 descend_*
+ * 까지 처리하는 collectAdjacentSegments 사용.
+ */
+export declare function inferDownstreamId(self: SegmentLike, tolerance?: MatchTolerance): string | null;
+export {};
+//# sourceMappingURL=auto-route.d.ts.map

package/dist-types/flow/auto-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-route.d.ts","sourceRoot":"","sources":["../../src/flow/auto-route.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAkB,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAErH,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvB,MAAM,CAAC,EAAE,GAAG,CAAA;IACZ,SAAS,CAAC,EAAE,GAAG,CAAA;IACf,IAAI,CAAC,EAAE,GAAG,CAAA;IACV,kBAAkB,IAAI,eAAe,CAAA;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,GAAG,EACd,OAAO,EAAE,GAAG,GACX,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC,CAmC1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,SAAS,CAAC,EAAE,cAAc,GACzB,MAAM,GAAG,IAAI,CAwBf"}

package/dist-types/flow/face-anchors.d.ts

@@ -0,0 +1,26 @@
+/** XZ 평면 anchor (scene world 좌표; Y=floor-level 무시). */
+export interface FaceAnchor {
+    worldPos: {
+        x: number;
+        z: number;
+    };
+    /** 진행 방향 단위 vector (carrier 속도 vector 와 일치). */
+    direction: {
+        x: number;
+        z: number;
+    };
+    /** 면 절반 길이 — segment 겹침 판정용. */
+    halfSpan?: number;
+}
+/**
+ * state(left/top/width/height/rotation) → 4면 anchor. kind='inbound' 면 inward(받는 면),
+ * 'outbound' 면 outward(내보내는 면). 회전 반영.
+ */
+export declare function rectFaceAnchors(state: {
+    left?: number;
+    top?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+}, kind: 'inbound' | 'outbound'): FaceAnchor[];
+//# sourceMappingURL=face-anchors.d.ts.map

package/dist-types/flow/face-anchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-anchors.d.ts","sourceRoot":"","sources":["../../src/flow/face-anchors.ts"],"names":[],"mappings":"AASA,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAClC,gDAAgD;IAChD,SAAS,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACnC,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1F,IAAI,EAAE,SAAS,GAAG,UAAU,GAC3B,UAAU,EAAE,CAiCd"}

package/dist-types/flow/flow-engine.d.ts

@@ -0,0 +1,122 @@
+import { sinksForDestination, componentForNode, nodeIdOf, isRoutingTarget, type BalancingPolicy, allDestinations } from './flow-graph-coordinator.js';
+import { type FlowGraph } from './flow-graph.js';
+import { type FlowGraphIssue } from './flow-graph-validator.js';
+export interface RoutingResult {
+    /** 다음 노드 id (graph node id — state.id ?? refid). */
+    targetId: string;
+    /** 다음 노드 컴포넌트 (이미 resolved). */
+    component: any;
+    /**
+     * 결정 origin — Phase 7 (graph overlay) 에서 색 구분.
+     *   - explicit: 명시 RoutingLinks edge
+     *   - inferred: capability 기반 자동 추론
+     * 현재는 구분 미확정 — Phase 7 에서 coordinator 가 metadata 부착 후 정확화.
+     */
+    origin: 'explicit' | 'inferred';
+}
+/**
+ * 분기점이 carrier 를 어느 하류로 보낼지 — 단일 진입점.
+ *
+ * @param fromComp 결정 주체 (joint / sorter / chute 등)
+ * @param carrier  결정 대상 — `carrier.state.meta.destination` 으로 목적지 매칭
+ * @param options  Phase B2 — balancing policy 명시 override. 미명시 시 host/root state 의
+ *                 balancingPolicy / routingBalancingPolicy → default 'round-robin'.
+ * @returns 다음 노드 — 미상 / 도달 불가 시 null (호출부가 fallback)
+ */
+export declare function next(fromComp: any, carrier?: any, options?: {
+    policy?: BalancingPolicy;
+}): RoutingResult | null;
+/**
+ * fromComp 의 직속 outbound[0] — chute 의 flush target 같은 단순 하류 1순위.
+ * resolveNextHop 과 다른 점: destination 매칭·tie-break 없이 *_그래프 첫 outbound_* 만.
+ */
+export declare function downstream(fromComp: any): {
+    id: string;
+    component: any;
+} | null;
+/**
+ * fromComp 에서 도달 가능한 *_RoutingTarget value_* 목록 — generator 의 destination 후보 등.
+ */
+export declare function reachableDestinations(fromComp: any): string[];
+/**
+ * startId 기반 reachableDestinations — startId 가 graph node id (= componentForNode 의 key).
+ * generator 처럼 *_자기 컴포넌트가 startId 가 아닌_* 경우 (별도 시작점) 에 사용.
+ */
+export declare function reachableDestinationsFrom(root: any, startId: string): string[];
+/** destination + 그 destination 의 sink 들의 가중치 합. */
+export interface WeightedDestination {
+    /** destination value (예: "서울"). */
+    value: string;
+    /**
+     * 가중치 합. 각 sink 의 측정:
+     *   - routingWeight() 명시 시 → 그 값 (사용자 override)
+     *   - 미명시 시 → 그 sink 의 *_incoming edge 수_* (경로 갯수 = 자연 capacity)
+     *   - incoming 0 fallback = 1
+     */
+    weight: number;
+}
+/**
+ * reachableDestinationsFrom 의 *_가중치 버전_*. item-generator 의 _pickDestination 이 가중치
+ * 비례 random pick 에 사용.
+ *
+ * # 가중치 측정의 의미 (2026-06-17 사용자 통찰)
+ *
+ * 처음 (B3) 은 sink 수 비례 (각 sink weight 1). 그러나 사용자 통찰:
+ *   "실제 생성 밸런스는 *_경로의 갯수_* 에 따라야 한다"
+ *
+ * 즉 destination 의 처리 capacity = *_그 destination 의 sink 들이 받을 수 있는 path 수_*.
+ * 사용자가 board 만들 때 경로 갯수를 의도적으로 설계 — 그 자체가 의도 표현.
+ *
+ * # 예
+ *   부산: 1 stockpile, *_3 chute_* 가 도달  →  weight 3
+ *   제주: 2 stockpile, 각 1 chute 도달        →  weight 2
+ *   → 부산 60% / 제주 40% 자연 생성
+ *
+ * # 명시 override (routingWeight) 의 역할
+ * 사용자가 `state.weight = N` 명시했다면 *_그래프 구조 무관 강제로 N_*. 드문 시나리오 —
+ * 자연 capacity 측정과 다른 비중을 부여하고 싶을 때만.
+ *
+ * # 결정론 / 비용
+ * incoming edge 수 = 그래프의 in-degree (한 번 walk). graph cache 의 root 당 1 회 측정.
+ */
+export declare function reachableDestinationsWeightedFrom(root: any, startId: string): WeightedDestination[];
+/**
+ * FlowGraph 자체 — diagnostics / overlay 용. hot path 는 next() / downstream() 사용 권장.
+ */
+export declare function graphFor(root: any): FlowGraph | null;
+/**
+ * Phase 3 — FlowGraph invariant 검증. board load / topology change 후 호출 권장.
+ * orphan / dead-end / cycle / unreachable-target 의 4 종 issue 신고.
+ *
+ *   - error 가 있으면 시뮬 시작 차단 권장 (호출부 결정)
+ *   - warning 은 사용자 안내 (UI overlay)
+ *   - 의도 cycle (LoopSorter 등) 은 capability-based loopCapableIds 로 skip
+ *
+ * @returns issues — 빈 array 면 통과
+ */
+export declare function validate(root: any): FlowGraphIssue[];
+export { componentForNode, nodeIdOf, isRoutingTarget, sinksForDestination, allDestinations };
+/**
+ * FlowEngine namespace — call site 가 `FlowEngine.next(this, carrier)` 형태로 사용.
+ * (개별 함수 export 와 동일 — 호출 스타일 옵션.)
+ */
+/**
+ * WeightedDestination[] 에서 가중치 비례 random pick. item-generator 의 _pickDestination
+ * 본문 로직 — helper 로 분리하여 단위 테스트 가능 (사용자 의문, 2026-06-17 — E2E 검증).
+ *
+ * 결정론 아님 (Math.random 사용). 통계적 분산만 보장.
+ */
+export declare function pickWeightedDestination(weighted: WeightedDestination[]): string | undefined;
+export declare const FlowEngine: {
+    next: typeof next;
+    downstream: typeof downstream;
+    reachableDestinations: typeof reachableDestinations;
+    reachableDestinationsFrom: typeof reachableDestinationsFrom;
+    reachableDestinationsWeightedFrom: typeof reachableDestinationsWeightedFrom;
+    pickWeightedDestination: typeof pickWeightedDestination;
+    graphFor: typeof graphFor;
+    validate: typeof validate;
+};
+export type { FlowGraphIssue } from './flow-graph-validator.js';
+export type { BalancingPolicy } from './flow-graph-coordinator.js';
+//# sourceMappingURL=flow-engine.d.ts.map

package/dist-types/flow/flow-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-engine.d.ts","sourceRoot":"","sources":["../../src/flow/flow-engine.ts"],"names":[],"mappings":"AA0BA,OAAO,EAEL,mBAAmB,EACnB,gBAAgB,EAChB,QAAQ,EACR,eAAe,EAEf,KAAK,eAAe,EACpB,eAAe,EAChB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChE,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAE1F,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAA;IAChB,gCAAgC;IAChC,SAAS,EAAE,GAAG,CAAA;IACd;;;;;OAKG;IACH,MAAM,EAAE,UAAU,GAAG,UAAU,CAAA;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,aAAa,GAAG,IAAI,CAO/G;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,GAAG,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,GAAG,CAAA;CAAE,GAAG,IAAI,CAS/E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,GAAG,GAAG,MAAM,EAAE,CAI7D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAa9E;AAED,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAmCnG;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,SAAS,GAAG,IAAI,CAEpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,cAAc,EAAE,CAsBpD;AAID,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,eAAe,EAAE,mBAAmB,EAAE,eAAe,EAAE,CAAA;AAE5F;;;GAGG;AACH;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,MAAM,GAAG,SAAS,CAa3F;AAED,eAAO,MAAM,UAAU;;;;;;;;;CAStB,CAAA;AAGD,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAG/D,YAAY,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA"}

package/dist-types/flow/flow-graph-coordinator.d.ts

@@ -0,0 +1,80 @@
+import { type FlowGraph, type NextHopCandidate } from './flow-graph.js';
+import { type FlowGraphIssue } from './flow-graph-validator.js';
+/** RoutingTarget capability — sink 가 자기 담당 행선지 값을 자가선언. */
+export interface RoutingTarget {
+    /** 담당 행선지 값 (매칭 전용 — findById 대상 아님). */
+    routingDestination(): string;
+    /** (optional, Phase B1) 같은 destination N sink 분산 가중치. 미구현 = 1. */
+    routingWeight?(): number;
+}
+export declare function isRoutingTarget(c: any): c is RoutingTarget;
+/**
+ * board load 시점 검출된 validate issues — UI overlay / 사용자 안내 진입점.
+ * 빈 array = 통과. error 가 있으면 호출부가 시뮬 시작 차단 권장.
+ */
+export declare function flowGraphIssues(root: any): FlowGraphIssue[];
+/** root 의 방향 그래프 (캐시). 노드 0 이면 null. */
+export declare function flowGraphFor(root: any): FlowGraph | null;
+/** 행선지 값 → 담당 sink 노드 id 들. */
+export declare function sinksForDestination(root: any, destination: string): string[];
+/** 노드 id → 컴포넌트. */
+export declare function componentForNode(root: any, id: string): any;
+/** root 전체의 행선지 값 목록 (중복 제거). generator 가 후보로 사용. */
+export declare function allDestinations(root: any): string[];
+/** 컴포넌트의 그래프 노드 id (id ?? refid). 분기점이 자기 노드 식별에. */
+export declare function nodeIdOf(c: any): string | undefined;
+/**
+ * Phase B2 — balancing 정책.
+ *   - index         : outbound index 순 첫 후보 (= legacy 동작)
+ *   - round-robin   : 같은 hops 동률 후보 사이 순환 (default)
+ *   - weight        : 동률 후보의 target sink 의 routingWeight 비례 weighted-round-robin
+ *                     (random 회피 — 결정론 보장)
+ *   - utilization   : 동률 후보의 target sink 의 점유율 (inventoryCount / capacity) 가장 낮은
+ */
+export type BalancingPolicy = 'index' | 'round-robin' | 'weight' | 'utilization';
+/** per-root balancing state — round-robin counter. root 가 새로 생기면 자동 초기화 (cache 와 동일). */
+export interface BalancingState {
+    /** hostId → counter. round-robin / weight 정책이 사용. */
+    counters: Map<string, number>;
+}
+/**
+ * Phase B2 balancing — 동률 후보 중 정책으로 선택. *_Internal helper, exported for unit test_*.
+ */
+export declare function applyPolicy(policy: BalancingPolicy, hostId: string, state: BalancingState, tied: NextHopCandidate[], components: Map<string, any>): NextHopCandidate;
+/**
+ * 분기점(joint/sorter)이 carrier 를 어느 하류로 보낼지 — 목적지 지향 next-hop.
+ * 반환 = 고른 *하류 이웃 노드 id* (= 그 OUT 의 연결 대상). 없으면 null (목적지
+ * 미상/도달 불가/그래프 없음 → 호출부가 기존 로직 fallback). 호출부는 이 id 로
+ * 자기 port/opening(targetRef/neighborId) 을 매칭 — index 정렬 불일치 회피.
+ *
+ * # 절차
+ *   1. carrier.meta.destination(행선지 값) → 그 값을 담당하는 sink 노드들
+ *      (없으면 dest 자체를 노드 id 로 — 단일 sink fallback).
+ *   2. nextHopsToAnyDetailed — 각 outbound 의 가까운 sink + hops 측정. 도달 불가
+ *      outbound 는 자연 제외.
+ *   3. canReceive=true 후보만 필터 (capacity-reactive). 전부 막힘 → 최단으로 대기.
+ *   4. *_도달 가능한 모든 outbound_* 에 balancing policy 적용 (hops 동률 제약 없음).
+ *
+ * # 왜 hops 동률 제약을 두지 않는가 (Phase B6 의 본질 결정, 2026-06-17)
+ * "효율 (최단 hops)" 과 "분산 (throughput / capacity)" 의 두 가치가 충돌하면, 시스템
+ * 이 자동 선택할 수 없다 — 사용자 의도가 어느 쪽인지 *_시스템은 모름_*. 추측은
+ * 마술적이지만 잘못됐을 때 제어 불가.
+ *
+ * 그러나 *_사용자가 같은 destination 의 N sink 를 board 에 만든 사실 자체_* 가
+ * 이미 의도의 표현이다. 효율만 원했다면 1 개만 만들었을 것 — N 개 만든 것은:
+ *   - "이 destination 의 capacity 를 N 배로" (예: chute 막힘 회피)
+ *   - "후속 처리 N 라인 동시 부하" (throughput)
+ * 어느 쪽이든 *_분산 우선_* 의 표현.
+ *
+ * 따라서 default = *_모든 도달 가능 sink 사이 분산_* (hops 무관). 효율 우선 시나리오
+ * (드물게 있다면) 는 향후 `'shortest'` 같은 opt-in 정책으로 *_명시_* 표현하면 됨.
+ *
+ * # Phase B2 — 정책 enum
+ * policy 결정 우선순위: options.policy → per-host (self.state.balancingPolicy)
+ *   → root (root.state.routingBalancingPolicy) → default 'round-robin'.
+ * 모든 정책은 *_도달 가능한 receivable 전체_* 에 적용 (= Phase B6 의 원칙).
+ */
+export declare function resolveNextHop(self: any, carrier: any, options?: {
+    policy?: BalancingPolicy;
+}): string | null;
+//# sourceMappingURL=flow-graph-coordinator.d.ts.map

package/dist-types/flow/flow-graph-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-graph-coordinator.d.ts","sourceRoot":"","sources":["../../src/flow/flow-graph-coordinator.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAyC,KAAK,SAAS,EAAsB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAElI,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAG1F,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,kBAAkB,IAAI,MAAM,CAAA;IAC5B,kEAAkE;IAClE,aAAa,CAAC,IAAI,MAAM,CAAA;CACzB;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,IAAI,aAAa,CAE1D;AA+LD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,GAAG,GAAG,cAAc,EAAE,CAE3D;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,SAAS,GAAG,IAAI,CAGxD;AAED,+BAA+B;AAC/B,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5E;AAED,oBAAoB;AACpB,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,GAAG,GAAG,CAE3D;AAED,qDAAqD;AACrD,wBAAgB,eAAe,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,EAAE,CAGnD;AAED,qDAAqD;AACrD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAEnD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,aAAa,CAAA;AAEhF,yFAAyF;AACzF,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9B;AAiCD;;GAEG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,gBAAgB,EAAE,EACxB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAC3B,gBAAgB,CAsClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAqC7G"}

package/dist-types/flow/flow-graph-validator.d.ts

@@ -0,0 +1,33 @@
+import type { FlowGraph } from './flow-graph.js';
+export type IssueSeverity = 'error' | 'warning';
+export type IssueCode = 'orphan-source' | 'dead-end' | 'cycle' | 'unreachable-target' | 'invalid-weight';
+export interface FlowGraphIssue {
+    severity: IssueSeverity;
+    code: IssueCode;
+    nodeId?: string;
+    /** cycle 의 경우 노드 체인 (정렬: 시작 = lexically min id, 결정론). */
+    cycle?: string[];
+    message: string;
+}
+export interface ValidateOptions {
+    /**
+     * 의도 cycle 자격 — 해당 노드 id 의 cycle 은 skip (예: LoopSorter / LoopConveyor).
+     * 호출자가 root walk 로 isLoop capability 식별 후 전달. validator 자체는 순수.
+     */
+    loopCapableIds?: ReadonlySet<string>;
+    /**
+     * RoutingTarget 자격 노드 id 목록 — sink (dead-end 자격 면제) 판단 + unreachable 검사.
+     * coordinator 의 destToSinks 키로 도출 가능.
+     */
+    routingTargetIds?: ReadonlySet<string>;
+    /**
+     * (Phase B1) routingWeight 추출 결과 — nodeId → weight. 미선언/default 1 인 노드는
+     * 생략 가능. validator 가 weight ≤ 0 의 invalid-weight warning 검출.
+     */
+    routingWeights?: ReadonlyMap<string, number>;
+}
+/**
+ * graph 의 invariants 검증. 같은 입력 → 같은 결과 (결정론).
+ */
+export declare function validate(graph: FlowGraph, opts?: ValidateOptions): FlowGraphIssue[];
+//# sourceMappingURL=flow-graph-validator.d.ts.map

package/dist-types/flow/flow-graph-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-graph-validator.d.ts","sourceRoot":"","sources":["../../src/flow/flow-graph-validator.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAA;AAC/C,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,oBAAoB,GAAG,gBAAgB,CAAA;AAExG,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,aAAa,CAAA;IACvB,IAAI,EAAE,SAAS,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAEpC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAEtC;;;OAGG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7C;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,GAAE,eAAoB,GAAG,cAAc,EAAE,CA8FvF"}

package/dist-types/flow/flow-graph.d.ts

@@ -0,0 +1,76 @@
+import { type SegmentTopology, type SegmentBounds, type MatchTolerance } from './segment-topology.js';
+/** 그래프 노드 입력 — collectAdjacentSegments 출력과 동일 shape. */
+export interface FlowGraphNode {
+    id: string;
+    topology: SegmentTopology;
+    bounds?: SegmentBounds;
+    /**
+     * 명시 링크 — 사용자가 *명시 id* 로 지정한 그래프 엣지. 인접(기하) 자동연결로는
+     * 못 잇는 *떨어진 타겟*(예: 슈트 → 멀리 있는 StockPile)을 연결. 인접 엣지에 *추가*
+     * (대체 아님). coordinator 가 RoutingLinks capability 에서 채운다. refid 아님(시스템
+     * auto-link 와 별개) — 사용자 명시 id.
+     */
+    links?: {
+        /** 이 노드 → target 노드 id(들). */
+        downstream?: string[];
+        /** source 노드 id(들) → 이 노드. */
+        upstream?: string[];
+    };
+}
+/** 산출된 방향 그래프. */
+export interface FlowGraph {
+    /** id → 노드. */
+    nodes: Map<string, FlowGraphNode>;
+    /** id → outbound 별 연결 대상 id (없으면 null). index = outbound 순서. */
+    out: Map<string, Array<string | null>>;
+    /** 말단(outbound 연결 0) — 목적지 후보. */
+    sinks: Set<string>;
+    /** 진입원(inbound 연결 0). */
+    sources: Set<string>;
+}
+/**
+ * 노드 목록 → 방향 그래프. 간선은 matchOutbounds(anchor 정밀 + footprint 배달)
+ * 재사용 — 컨베이어 자동연결과 *동일 판정*이라 그래프가 실제 흐름과 일치.
+ */
+export declare function buildFlowGraph(nodes: ReadonlyArray<FlowGraphNode>, tolerance?: MatchTolerance): FlowGraph;
+/**
+ * fromId 의 *각 outbound* 에서 도달 가능한 노드 집합. 반환 index = outbound 순서.
+ * 연결 없는 outbound = 빈 집합. 분기점 next-hop 선택의 1차 재료.
+ */
+export declare function reachableByOutbound(graph: FlowGraph, fromId: string): Set<string>[];
+/**
+ * fromId 에서 destId 로 가까워지는 *outbound index 목록*, **최단 hop 우선 정렬**.
+ * 동률은 index 순(결정적). 여러 개면 상위(resolver)가 capacity 등으로 tie-break.
+ * 빈 배열 = 도달 불가(이 노드에선 막힘).
+ */
+export declare function nextHops(graph: FlowGraph, fromId: string, destId: string): number[];
+/**
+ * fromId 에서 destId 로 가는 *최단 outbound index 1개* (없으면 -1). resolver 가
+ * capacity 무관할 때의 기본 선택. capacity-reactive 는 nextHops 전체를 받아 거른다.
+ */
+export declare function nextHop(graph: FlowGraph, fromId: string, destId: string): number;
+/** fromId 가 destId 에 도달 가능한가 (어느 outbound 로든). dispatcher canReach 의 망 판정. */
+export declare function canReach(graph: FlowGraph, fromId: string, destId: string): boolean;
+/** fromId 에서 도달 가능한 *말단(sink) 노드 집합*. generator 가 보낼 수 있는 목적지 후보. */
+export declare function reachableSinks(graph: FlowGraph, fromId: string): Set<string>;
+/**
+ * fromId 에서 *목적지 값을 담당하는 여러 sink 중 아무거나* 로 가까워지는 outbound
+ * index 목록 (최단 hop 우선). 논리 목적지를 담당하는 물리 sink 가 여럿일 때
+ * (= 부하분산 여지). destIds = 그 목적지를 담당하는 sink 노드 id 들.
+ */
+export declare function nextHopsToAny(graph: FlowGraph, fromId: string, destIds: Iterable<string>): number[];
+/** Outbound 후보 — Phase B2 balancing 정책에서 hops 동률 그룹 + target sink id 사용. */
+export interface NextHopCandidate {
+    /** outbound port index (FlowGraphNode.topology.outbounds 의 index, = graph.out 의 index). */
+    index: number;
+    /** 이 outbound 의 *_가까운 sink_* 까지의 최단 hop 수 (자기 포함 = 1). */
+    hops: number;
+    /** 그 hop 의 *_가까운 sink id_* (동률 시 lexical first — 결정론). */
+    target: string;
+}
+/**
+ * nextHopsToAny 의 *_상세 버전_* — index + hops + target sink id. balancing 정책이
+ * *_같은 hops 동률 그룹화_* + *_target sink 의 routingWeight 조회_* 등에 사용 (Phase B2).
+ */
+export declare function nextHopsToAnyDetailed(graph: FlowGraph, fromId: string, destIds: Iterable<string>): NextHopCandidate[];
+//# sourceMappingURL=flow-graph.d.ts.map

package/dist-types/flow/flow-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-graph.d.ts","sourceRoot":"","sources":["../../src/flow/flow-graph.ts"],"names":[],"mappings":"AAiCA,OAAO,EAAkB,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAErH,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,eAAe,CAAA;IACzB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QACN,8BAA8B;QAC9B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;QACrB,8BAA8B;QAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KACpB,CAAA;CACF;AAED,kBAAkB;AAClB,MAAM,WAAW,SAAS;IACxB,eAAe;IACf,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACjC,gEAAgE;IAChE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAA;IACtC,kCAAkC;IAClC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAClB,yBAAyB;IACzB,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CACrB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC,EAAE,cAAc,GAAG,SAAS,CAwCzG;AA6BD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CASnF;AA8BD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAanF;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGlF;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAM5E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAEnG;AAED,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IACZ,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GACxB,gBAAgB,EAAE,CAwBpB"}

package/dist-types/flow/flow-introspection.d.ts

@@ -0,0 +1,36 @@
+export interface DataScenario {
+    /** 이 시나리오의 carrier data — 경로의 모든 constraint AND merge. */
+    data: Record<string, any>;
+    /** sampling weight — default 1 (= 균등). 향후 demand-driven 등 확장. */
+    weight: number;
+    /** debug — 경로의 segment id 들. */
+    pathIds?: string[];
+    /**
+     * 경로의 *종착 sink id* (= carrier 의 최종 목적지). generator 가 carrier.meta.
+     * destination 에 주입 → 분기점이 목적지 지향 next-hop 라우팅(flow-graph.canReach)
+     * 으로 분기하게 될 토대. 미상이면 undefined (= 목적지 없는 carrier).
+     */
+    destination?: string;
+}
+interface SegmentLike {
+    state?: {
+        id?: string;
+    };
+    parent?: any;
+    rootModel?: any;
+    root?: any;
+    getSegmentTopology?: () => any;
+}
+/**
+ * 생성기 (= source) 부터 BFS — RoutingCapability 의 constraints 누적 + sink 도달
+ * 시 시나리오 추가. 결과: 가능 data 시나리오 list.
+ *
+ * @returns 데이터 시나리오 list (균등 weight). 빈 list = downstream 추론 실패.
+ */
+export declare function enumerateDataScenarios(source: SegmentLike, maxDepth?: number): DataScenario[];
+/**
+ * AND merge — 두 constraint 의 key-value 합치기. key 충돌 (= 다른 value) 시 null.
+ */
+export declare function mergeConstraints(base: Record<string, any>, add: Record<string, any>): Record<string, any> | null;
+export {};
+//# sourceMappingURL=flow-introspection.d.ts.map

package/dist-types/flow/flow-introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-introspection.d.ts","sourceRoot":"","sources":["../../src/flow/flow-introspection.ts"],"names":[],"mappings":"AAoCA,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACzB,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAA;IACd,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvB,MAAM,CAAC,EAAE,GAAG,CAAA;IACZ,SAAS,CAAC,EAAE,GAAG,CAAA;IACf,IAAI,CAAC,EAAE,GAAG,CAAA;IACV,kBAAkB,CAAC,EAAE,MAAM,GAAG,CAAA;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,WAAW,EACnB,QAAQ,SAAK,GACZ,YAAY,EAAE,CAmGhB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACvB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAO5B"}