Current Synthetic Logistics Data and Digital Twin Brief
이 문서는 현재 구현된 synthetic logistics source-world, operational ontology compiler, ontology-grounded decision layer, 3D digital twin을 CTO 관점에서 빠르게 이해하기 위한 briefing이다. 핵심은 ontology를 먼저 상상해서 만든 것이 아니라, 실제 보수적인 물류 환경처럼 분리되고 지연되고 충돌하는 원천 데이터를 만든 뒤, 그 source-world를 traceable ontology와 bounded ContextPacket으로 compile했다는 점이다.
1. What was built
현재 build는 Colosseum Vault에서 받을 법한 물류 운영 데이터를 미리 합성하고, 그 source-world가 3D warehouse twin 위에서 어떻게 연결되는지 검증하는 R&D 데모다. 단순 랜덤 fixture가 아니라, incident timeline, deterministic causal rules, bounded randomness, source sync lag, labor/capacity constraints, movement lineage를 함께 가진다.
2. Synthetic source-world
데이터셋은 Seoul AMR fulfillment center의 outbound incident replay를 모방한다. WMS, WCS, AMR fleet, TMS, handheld scan, operator action, labor roster, resource capacity, handling-unit lineage, source sync telemetry를 분리된 source export로 둔다.
| Layer | What it represents | Why it matters |
|---|---|---|
| WMS | Orders, order lines, inventory positions | 고객 promise, SKU shortage, allocation truth를 제공하지만 실행 상태 전체를 알지는 못한다. |
| WCS / AMR | Execution tasks, AMR task events, AMR snapshots | 로봇과 작업 흐름을 보여주지만 event stream과 snapshot cadence가 서로 다를 수 있다. |
| TMS / Dock | Outbound shipment and dock appointment records | carrier early arrival과 dock slack compression을 만들어 incident peak를 유발한다. |
| Human operations | Operator exceptions and labor shift roster | 실제 recovery는 승인, break coverage, certification, staffing variance에 의해 제한된다. |
| Evidence spine | source_event_ledger.jsonl |
원천 row를 지우지 않고 source file, source record id, freshness, entity/location refs, replay order로 묶는다. |
Source exports: data/synthetic/vault-amr-fulfillment-source-world-v0.1/source_exports
3. Simulation logic
Incident는 baseline에서 시작해 inventory dispute, cold-zone route blockage, AMR capacity narrowing, AMR-17 stale availability, early carrier arrival, supervisor resequence, partial shipment closeout으로 진행된다. Randomness는 무작위 row 생성을 위한 것이 아니라 현실적인 운영 변동을 만들기 위한 bounded parameter다.
| Mechanism | Implemented behavior | Compiler relevance |
|---|---|---|
| Deterministic rules | AMR low-battery lock, dock cutoff compression, split recovery 같은 causal transition을 고정한다. | Ontology compiler가 source evidence에서 같은 operational conclusion을 복원해야 한다. |
| Planned randomness | carrier arrival variance, scan upload lag, stale snapshot window, recovery yield를 seed 기반으로 기록한다. | 재현 가능한 synthetic benchmark가 되며, 새 schema를 넣어도 같은 사건 구조를 비교할 수 있다. |
| Dirty source behavior | late rows, stale snapshots, duplicate retries, partial sync, missing/inferred lineage가 존재한다. | AI-ready data layer가 provenance, confidence, freshness를 다뤄야 하는 이유를 만든다. |
4. Digital twin environment
앱은 React Three Fiber 기반 3D warehouse twin이다. 첫 화면은 landing page가 아니라 운영자가 바로 사건을 탐색하는 control-room surface로 구성되어 있다.
3D scene
warehouse envelope, racks, dock yard, trucks, AMR robots, chargers, route network, pack/stage zones, cargo field를 렌더링한다.
Incident inspector
source freshness, lineage, capacity stress, causal replay, evidence chain, decision trace, intervention options를 event별로 보여준다.
Source explorer
WMS/WCS/AMR/TMS/scan/operator/labor/capacity/lineage/sync/ledger source tab을 제공하고, row inspect 시 twin anchor가 표시된다.
Evidence overlays
source freshness beacon, selected source record marker, capacity marker, lineage marker를 3D 공간에 배치한다.
Ontology graph view
선택한 event의 ContextPacket에서 source, operational entity, risk, decision, action node와 typed edge를 bounded graph로 보여준다.
Decision automation layer
deterministic facts, graph expansion, selected action, expected KPI delta, approval gate, LLM explanation endpoint를 같은 inspector 안에 연결한다.
5. Ontology compiler bridge
이 build는 source-world를 operational-logistics-ontology-v0.1로 compile한다.
full ontology artifact는 연구/검증용으로 보존하고, UI는 event별 작은 projection을 읽어 graph view와 decision automation panel을 렌더링한다.
| Artifact | Role | Why it matters |
|---|---|---|
scripts/compile-operational-ontology.mjs |
source exports를 node, edge, risk, decision, action, ContextPacket으로 변환한다. | ontology를 수작업 fixture가 아니라 재현 가능한 compiler output으로 만든다. |
operational-ontology.json |
1,525 nodes와 5,047 typed edges를 가진 full source-grounded graph. | provenance, retrieval descriptions, deterministic fields, twin anchors를 보존한다. |
decision-contexts.json |
8개 event별 bounded ContextPacket과 deterministic decision logic. | LLM이 전체 graph 대신 source-grounded context만 받게 한다. |
app/api/ontology/decision |
OpenRouter openai/gpt-5.4-mini 기반 explanation endpoint. |
모델은 deterministic facts를 재계산하지 않고, evidence-bounded explanation만 생성한다. |
CTX-T05. Carrier early arrival, APT-007 / SHIP-007, DOCK-03 capacity pressure, WCS blocked premium work, source freshness asymmetry, lineage gaps, resequence recommendation을 한 ContextPacket으로 묶는다.
6. Validation evidence
현재 build는 데이터 생성, 검증, TypeScript build, 런타임 렌더링을 통과했다. validator는 단순 row count가 아니라 referential integrity, source freshness asymmetry, labor constraints, capacity math, lineage dirty states, source-event ledger replayability, app fixture embedding을 검사한다.
| Gate | Status | Evidence |
|---|---|---|
| Data validation | Passed | npm run validate:data -> 124 checks passed |
| Application build | Passed | npm run lint and npm run build |
| Ontology validation | Passed | npm run build:ontology -> 85 ontology checks passed |
| LLM endpoint | Passed | POST /api/ontology/decision returned a source-bounded Korean decision explanation for T05 |
| Runtime behavior | Passed | 3D canvas, ontology graph view, ontology decision panel, docs route, desktop/mobile rendering verified with Playwright |
7. How to read it
- Open the app and select
T05 Carrier arrives early. This is the incident peak. - Scan source freshness, capacity stress, lineage, causal replay, evidence chain, ontology graph view, ontology decision automation, and decision trace in the right rail.
- Open the
Event ledgersource tab and inspect rows. Confirm each row has source file, source record id, freshness, and twin anchor. - Use
Ontology graph viewto see how source rows compile into nodes and typed edges. UseGenerate LLM explanationto see the model consume the bounded ContextPacket.
Runtime app: http://localhost:3001
Main fixture: src/data/generated/twin-scenario.json
Ontology projection: src/data/generated/ontology-decision-demo.json