@operato/twin-kernel 0.0.1

package/dist/epcis.d.ts

@@ -0,0 +1,125 @@
+/** EPCIS 2.0 JSON-LD 컨텍스트 — 이벤트를 자기기술적 EPCIS 오브젝트로 만든다. */
+export declare const EPCIS_CONTEXT = "https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld";
+/** 커널 시계는 UTC(BASE_EPOCH) 기준 → 고정 오프셋. */
+export declare const UTC_OFFSET = "+00:00";
+export declare const DISP: {
+    readonly in_progress: "urn:epcglobal:cbv:disp:in_progress";
+    readonly sellable: "urn:epcglobal:cbv:disp:sellable_accessible";
+    readonly reserved: "urn:epcglobal:cbv:disp:reserved";
+    readonly in_transit: "urn:epcglobal:cbv:disp:in_transit";
+    readonly non_sellable: "urn:epcglobal:cbv:disp:non_sellable_other";
+};
+export type EpcisEventType = 'ObjectEvent' | 'AggregationEvent' | 'TransactionEvent' | 'TransformationEvent';
+export type EpcisAction = 'ADD' | 'OBSERVE' | 'DELETE';
+export interface QuantityElement {
+    epcClass: string;
+    quantity: number;
+    uom?: string;
+}
+export interface BizTransactionElement {
+    type: string;
+    bizTransaction: string;
+}
+export interface LocationRef {
+    id: string;
+}
+/** EPCIS 2.0 공통 헤더(모든 이벤트). action 은 여기 없음 — TransformationEvent 는 action 이 없다. */
+interface EpcisHeader {
+    '@context': string;
+    type: EpcisEventType;
+    eventTime: string;
+    eventTimeZoneOffset: string;
+    bizStep: string;
+    disposition?: string;
+    readPoint?: LocationRef;
+    bizLocation?: LocationRef;
+    bizTransactionList?: BizTransactionElement[];
+}
+/** action 을 갖는 이벤트(Object/Aggregation/Transaction). */
+interface EpcisActionEvent extends EpcisHeader {
+    action: EpcisAction;
+}
+export interface EpcisObjectEvent extends EpcisActionEvent {
+    type: 'ObjectEvent';
+    epcList: string[];
+    quantityList?: QuantityElement[];
+}
+export interface EpcisAggregationEvent extends EpcisActionEvent {
+    type: 'AggregationEvent';
+    parentID: string;
+    childEPCs?: string[];
+    childQuantityList?: QuantityElement[];
+}
+export interface EpcisTransactionEvent extends EpcisActionEvent {
+    type: 'TransactionEvent';
+    bizTransactionList: BizTransactionElement[];
+    parentID?: string;
+    epcList?: string[];
+    quantityList?: QuantityElement[];
+}
+/** 변환(제조): 입력 소비 → 출력 생산. action 없음(EPCIS 2.0). */
+export interface EpcisTransformationEvent extends EpcisHeader {
+    type: 'TransformationEvent';
+    inputEPCList?: string[];
+    inputQuantityList?: QuantityElement[];
+    outputEPCList?: string[];
+    outputQuantityList?: QuantityElement[];
+    transformationID?: string;
+}
+export type EpcisEvent = EpcisObjectEvent | EpcisAggregationEvent | EpcisTransactionEvent | EpcisTransformationEvent;
+/** SSCC (물류단위: 팔레트/화물/트레일러) — 결정적 카운터 기반. */
+export declare function ssccUri(companyPrefix: string, serial: number): string;
+/** 비직렬 수량용 SGTIN 패턴(epcClass) — quantityList 에 사용. */
+export declare function sgtinClass(companyPrefix: string, itemRef: string): string;
+/** 거래문서 식별자 = GDTI (PO/SO/WO/어포인트먼트 등). */
+export declare function gdtiUri(companyPrefix: string, docType: string, serial: number): string;
+export declare function objectEvent(p: {
+    eventTime: string;
+    action: EpcisAction;
+    bizStep: string;
+    disposition?: string;
+    epcList: string[];
+    quantityList?: QuantityElement[];
+    readPoint?: string;
+    bizLocation?: string;
+    bizTransactionList?: BizTransactionElement[];
+}): EpcisObjectEvent;
+export declare function aggregationEvent(p: {
+    eventTime: string;
+    action: EpcisAction;
+    bizStep: string;
+    disposition?: string;
+    parentID: string;
+    childEPCs?: string[];
+    childQuantityList?: QuantityElement[];
+    readPoint?: string;
+    bizLocation?: string;
+}): EpcisAggregationEvent;
+export declare function transactionEvent(p: {
+    eventTime: string;
+    action: EpcisAction;
+    bizStep: string;
+    disposition?: string;
+    bizTransactionList: BizTransactionElement[];
+    parentID?: string;
+    epcList?: string[];
+    quantityList?: QuantityElement[];
+    readPoint?: string;
+    bizLocation?: string;
+}): EpcisTransactionEvent;
+/** 변환(제조) — 입력 EPC/수량 소비 → 출력 EPC/수량 생산. action 없음. */
+export declare function transformationEvent(p: {
+    eventTime: string;
+    bizStep: string;
+    disposition?: string;
+    inputEPCList?: string[];
+    inputQuantityList?: QuantityElement[];
+    outputEPCList?: string[];
+    outputQuantityList?: QuantityElement[];
+    transformationID?: string;
+    readPoint?: string;
+    bizLocation?: string;
+    bizTransactionList?: BizTransactionElement[];
+}): EpcisTransformationEvent;
+export declare function validateEpcisEvent(e: EpcisEvent): string[];
+export {};

package/dist/epcis.js

@@ -0,0 +1,172 @@
+/*
+ * EPCIS — GS1 EPCIS 2.0 이벤트 machinery (도메인-중립). WMS/YMS/MES 모두 이 표준 위에서 방출한다.
+ * 타입 + 빌더(Object/Aggregation/Transaction/Transformation) + 무의존 구조 검증기 + GS1 URI + CBV disposition.
+ * 도메인별 어휘(bizStep/btt)는 각 프로파일(wms/yms/mes-profile)에 둔다.
+ *
+ * EPCIS 2.0 JSON 바인딩: 각 이벤트는 @context/type/eventTime/eventTimeZoneOffset 를 포함하는
+ * 자기기술적(self-describing) JSON-LD 오브젝트.
+ */
+/** EPCIS 2.0 JSON-LD 컨텍스트 — 이벤트를 자기기술적 EPCIS 오브젝트로 만든다. */
+export const EPCIS_CONTEXT = 'https://ref.gs1.org/standards/epcis/2.0.0/epcis-context.jsonld';
+/** 커널 시계는 UTC(BASE_EPOCH) 기준 → 고정 오프셋. */
+export const UTC_OFFSET = '+00:00';
+// disposition — CBV URN (GS1 표준 상태 어휘, 전 도메인 공용).
+export const DISP = {
+    in_progress: 'urn:epcglobal:cbv:disp:in_progress',
+    sellable: 'urn:epcglobal:cbv:disp:sellable_accessible',
+    reserved: 'urn:epcglobal:cbv:disp:reserved',
+    in_transit: 'urn:epcglobal:cbv:disp:in_transit',
+    non_sellable: 'urn:epcglobal:cbv:disp:non_sellable_other' // 불량/scrap
+};
+// ── GS1 EPC URI 헬퍼 (표준) ────────────────────────────────────────────────
+/** SSCC (물류단위: 팔레트/화물/트레일러) — 결정적 카운터 기반. */
+export function ssccUri(companyPrefix, serial) {
+    return `urn:epc:id:sscc:${companyPrefix}.${String(serial).padStart(10, '0')}`;
+}
+/** 비직렬 수량용 SGTIN 패턴(epcClass) — quantityList 에 사용. */
+export function sgtinClass(companyPrefix, itemRef) {
+    return `urn:epc:idpat:sgtin:${companyPrefix}.${itemRef}.*`;
+}
+/** 거래문서 식별자 = GDTI (PO/SO/WO/어포인트먼트 등). */
+export function gdtiUri(companyPrefix, docType, serial) {
+    return `urn:epc:id:gdti:${companyPrefix}.${docType}.${serial}`;
+}
+// ── 이벤트 빌더 (EPCIS 2.0 정규) ──────────────────────────────────────────
+function header(type, eventTime, bizStep) {
+    return { '@context': EPCIS_CONTEXT, type, eventTime, eventTimeZoneOffset: UTC_OFFSET, bizStep };
+}
+function common(type, eventTime, action, bizStep) {
+    return { ...header(type, eventTime, bizStep), action };
+}
+export function objectEvent(p) {
+    const e = { ...common('ObjectEvent', p.eventTime, p.action, p.bizStep), epcList: p.epcList };
+    if (p.disposition)
+        e.disposition = p.disposition;
+    if (p.quantityList)
+        e.quantityList = p.quantityList;
+    if (p.readPoint)
+        e.readPoint = { id: p.readPoint };
+    if (p.bizLocation)
+        e.bizLocation = { id: p.bizLocation };
+    if (p.bizTransactionList)
+        e.bizTransactionList = p.bizTransactionList;
+    return e;
+}
+export function aggregationEvent(p) {
+    const e = { ...common('AggregationEvent', p.eventTime, p.action, p.bizStep), parentID: p.parentID };
+    if (p.disposition)
+        e.disposition = p.disposition;
+    if (p.childEPCs)
+        e.childEPCs = p.childEPCs;
+    if (p.childQuantityList)
+        e.childQuantityList = p.childQuantityList;
+    if (p.readPoint)
+        e.readPoint = { id: p.readPoint };
+    if (p.bizLocation)
+        e.bizLocation = { id: p.bizLocation };
+    return e;
+}
+export function transactionEvent(p) {
+    const e = {
+        ...common('TransactionEvent', p.eventTime, p.action, p.bizStep),
+        bizTransactionList: p.bizTransactionList
+    };
+    if (p.disposition)
+        e.disposition = p.disposition;
+    if (p.parentID)
+        e.parentID = p.parentID;
+    if (p.epcList)
+        e.epcList = p.epcList;
+    if (p.quantityList)
+        e.quantityList = p.quantityList;
+    if (p.readPoint)
+        e.readPoint = { id: p.readPoint };
+    if (p.bizLocation)
+        e.bizLocation = { id: p.bizLocation };
+    return e;
+}
+/** 변환(제조) — 입력 EPC/수량 소비 → 출력 EPC/수량 생산. action 없음. */
+export function transformationEvent(p) {
+    const e = header('TransformationEvent', p.eventTime, p.bizStep);
+    if (p.disposition)
+        e.disposition = p.disposition;
+    if (p.inputEPCList)
+        e.inputEPCList = p.inputEPCList;
+    if (p.inputQuantityList)
+        e.inputQuantityList = p.inputQuantityList;
+    if (p.outputEPCList)
+        e.outputEPCList = p.outputEPCList;
+    if (p.outputQuantityList)
+        e.outputQuantityList = p.outputQuantityList;
+    if (p.transformationID)
+        e.transformationID = p.transformationID;
+    if (p.readPoint)
+        e.readPoint = { id: p.readPoint };
+    if (p.bizLocation)
+        e.bizLocation = { id: p.bizLocation };
+    if (p.bizTransactionList)
+        e.bizTransactionList = p.bizTransactionList;
+    return e;
+}
+// ── 구조 검증기 (무의존 — 커널 zero-dep 원칙) ──────────────────────────────
+// EPCIS 2.0 이벤트의 필수 필드·형태를 검증. 위반 목록을 반환(빈 배열 = 유효).
+// JSON Schema 파일 파생은 후속 — 이 함수가 제약의 SoT.
+const ISO_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+const TZ_RE = /^[+-]\d{2}:\d{2}$/;
+const ACTIONS = ['ADD', 'OBSERVE', 'DELETE'];
+export function validateEpcisEvent(e) {
+    const v = [];
+    if (e['@context'] !== EPCIS_CONTEXT)
+        v.push('@context 누락/불일치');
+    if (!['ObjectEvent', 'AggregationEvent', 'TransactionEvent', 'TransformationEvent'].includes(e.type))
+        v.push(`알 수 없는 type: ${e.type}`);
+    if (typeof e.eventTime !== 'string' || !ISO_RE.test(e.eventTime))
+        v.push('eventTime ISO8601 아님');
+    if (typeof e.eventTimeZoneOffset !== 'string' || !TZ_RE.test(e.eventTimeZoneOffset))
+        v.push('eventTimeZoneOffset 형식 오류');
+    if (typeof e.bizStep !== 'string' || !e.bizStep)
+        v.push('bizStep 누락');
+    if (e.type === 'ObjectEvent') {
+        if (!ACTIONS.includes(e.action))
+            v.push(`action 부정: ${e.action}`);
+        if (!Array.isArray(e.epcList))
+            v.push('ObjectEvent.epcList 누락');
+        else if (e.epcList.length === 0 && !e.quantityList?.length)
+            v.push('ObjectEvent: epcList/quantityList 둘 다 비어있음');
+    }
+    else if (e.type === 'AggregationEvent') {
+        if (!ACTIONS.includes(e.action))
+            v.push(`action 부정: ${e.action}`);
+        if (!e.parentID)
+            v.push('AggregationEvent.parentID 누락');
+        if (!e.childEPCs?.length && !e.childQuantityList?.length)
+            v.push('AggregationEvent: childEPCs/childQuantityList 둘 다 비어있음');
+    }
+    else if (e.type === 'TransactionEvent') {
+        if (!ACTIONS.includes(e.action))
+            v.push(`action 부정: ${e.action}`);
+        if (!Array.isArray(e.bizTransactionList) || e.bizTransactionList.length === 0)
+            v.push('TransactionEvent.bizTransactionList 누락');
+    }
+    else if (e.type === 'TransformationEvent') {
+        if (!e.inputEPCList?.length && !e.inputQuantityList?.length)
+            v.push('TransformationEvent: input 비어있음');
+        if (!e.outputEPCList?.length && !e.outputQuantityList?.length)
+            v.push('TransformationEvent: output 비어있음');
+    }
+    // 참조 무결성(경량): 모든 수량 리스트의 epcClass 는 idpat/class
+    const qtyLists = [
+        'quantityList' in e ? e.quantityList : undefined,
+        'childQuantityList' in e ? e.childQuantityList : undefined,
+        'inputQuantityList' in e ? e.inputQuantityList : undefined,
+        'outputQuantityList' in e ? e.outputQuantityList : undefined
+    ];
+    for (const list of qtyLists)
+        for (const q of list ?? []) {
+            if (!q.epcClass?.startsWith('urn:epc:idpat:') && !q.epcClass?.startsWith('urn:epc:class:'))
+                v.push(`quantity epcClass 부정: ${q.epcClass}`);
+            if (typeof q.quantity !== 'number' || q.quantity < 0)
+                v.push('quantity 부정');
+        }
+    return v;
+}

package/dist/event-journal.d.ts

@@ -0,0 +1,17 @@
+import type { BoardDef, CanonicalEnvelope } from './contract.ts';
+import { type ProjectedState } from './state-projector.ts';
+export declare class EventJournal {
+    private events;
+    /** 이벤트 1건 기록(추가 전용). runtime/kernel 의 onEvent 에 연결. */
+    append(e: CanonicalEnvelope): void;
+    get length(): number;
+    all(): readonly CanonicalEnvelope[];
+    /** 처음 revision 개(= 시점 T까지). revision 은 emit 당 1 증가하므로 slice(0,rev). */
+    until(revision: number): CanonicalEnvelope[];
+    /** revision 이후(재동기·증분 전송용). */
+    since(revision: number): CanonicalEnvelope[];
+    /** sim 시각(ISO eventTime) 이하 이벤트. */
+    untilSimTime(iso: string): CanonicalEnvelope[];
+}
+/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·무버). */
+export declare function replay(board: BoardDef, events: readonly CanonicalEnvelope[]): ProjectedState;

package/dist/event-journal.js

@@ -0,0 +1,41 @@
+/*
+ * Event Journal + Replay — 트윈의 기억(이력·시간여행).
+ *
+ * 트윈은 자기 이벤트 스트림을 남긴다(내구 로그). projector 가 "이벤트→상태"를 하므로,
+ * 저널을 "시점 T까지" 재생하면 그 시점의 상태를 재구성(time-travel) — 감사·리플레이·발산 비교의 기반.
+ * 지금은 인메모리(framework-agnostic). things-factory 에선 이 append 를 DB 이벤트 테이블로 교체(멀티DB).
+ * (이벤트-소싱: 상태는 항상 이벤트열의 함수. state-projector 가 폴딩 함수.)
+ */
+import { StateProjector } from "./state-projector.js";
+export class EventJournal {
+    events = [];
+    /** 이벤트 1건 기록(추가 전용). runtime/kernel 의 onEvent 에 연결. */
+    append(e) {
+        this.events.push(e);
+    }
+    get length() {
+        return this.events.length;
+    }
+    all() {
+        return this.events;
+    }
+    /** 처음 revision 개(= 시점 T까지). revision 은 emit 당 1 증가하므로 slice(0,rev). */
+    until(revision) {
+        return this.events.slice(0, revision);
+    }
+    /** revision 이후(재동기·증분 전송용). */
+    since(revision) {
+        return this.events.slice(revision);
+    }
+    /** sim 시각(ISO eventTime) 이하 이벤트. */
+    untilSimTime(iso) {
+        return this.events.filter(e => e.eventTime <= iso);
+    }
+}
+/** 이벤트열 → 상태 재구성(시간여행). board = 마스터(토폴로지·무버). */
+export function replay(board, events) {
+    const proj = new StateProjector(board);
+    for (const e of events)
+        proj.apply(e);
+    return proj.snapshot();
+}

package/dist/face2-adapter.d.ts

@@ -0,0 +1,42 @@
+import type { CanonicalEnvelope } from './contract.ts';
+import type { EpcisEvent } from './epcis.ts';
+/** 매핑 값: 리터럴, 또는 소스 필드 참조("$.field.path"). */
+export type MapValue = string;
+/** ObjectEvent 매핑 스펙(선언적). Agg/Txn 매핑은 확장 지점. */
+export interface ObjectEventMapping {
+    type: 'ObjectEvent';
+    action: MapValue;
+    bizStep: MapValue;
+    disposition?: MapValue;
+    epc: MapValue;
+    readPoint?: MapValue;
+    bizLocation?: MapValue;
+}
+export type EventMapping = ObjectEventMapping;
+/** 룰: 소스 레코드의 판별자(sourceType)로 매핑을 고른다. */
+export interface AdapterRule {
+    sourceType: string;
+    mapping: EventMapping;
+}
+export interface IngestOptions {
+    tenantId: string;
+    /** eventTime 소스 필드(없으면 defaultEventTime). */
+    eventTimePath?: string;
+    defaultEventTime: string;
+}
+export interface IngestResult {
+    accepted: CanonicalEnvelope[];
+    rejected: {
+        record: unknown;
+        errors: string[];
+    }[];
+}
+type Rec = Record<string, unknown>;
+/** 단일 레코드 → 정규 EPCIS 이벤트(매핑만; 검증은 ingest 에서). */
+export declare function mapRecord(record: Rec, mapping: EventMapping, eventTime: string): EpcisEvent;
+/**
+ * 레거시 레코드 배열 → 정규 EPCIS 봉투. 매핑 후 검증, 실패분은 rejected(오염 차단).
+ * 실 EPCIS-native 소스면 매핑은 거의 항등, 검증만 통과시키면 됨.
+ */
+export declare function ingest(records: Rec[], rules: AdapterRule[], opts: IngestOptions): IngestResult;
+export {};

package/dist/face2-adapter.js

@@ -0,0 +1,69 @@
+/*
+ * Face 2 — 레거시 ↔ 레퍼런스 어댑터 (anti-corruption layer, 모니터링 ingress).
+ * 설계 SoT: integration/face2-adapters.md
+ *
+ * 실 WMS 의 다양한 페이로드를 **선언적 매핑**으로 정규 EPCIS 로 변환 + **검증**.
+ * 여기서 `validateEpcisEvent` 가 실 소비처를 얻는다(검증 실패 = ACL 이 오염 차단).
+ *
+ * 매핑 엔진은 walking-skeleton 범위에서 무의존 declarative spec 사용.
+ * (jsonata/템플릿 엔진 최종 선택은 열린 결정 — face2-adapters.md. 커널 zero-dep 유지 위해 여기선 미도입.)
+ */
+import { objectEvent, validateEpcisEvent } from "./epcis.js";
+function get(obj, path) {
+    return path.split('.').reduce((o, k) => (o == null ? o : o[k]), obj);
+}
+/** 매핑 값 해석: "$.path" 는 소스 참조, 그 외는 리터럴. */
+function resolve(v, record) {
+    if (v === undefined)
+        return undefined;
+    if (v.startsWith('$.')) {
+        const r = get(record, v.slice(2));
+        return r === undefined || r === null ? undefined : String(r);
+    }
+    return v;
+}
+/** 단일 레코드 → 정규 EPCIS 이벤트(매핑만; 검증은 ingest 에서). */
+export function mapRecord(record, mapping, eventTime) {
+    const epc = resolve(mapping.epc, record);
+    return objectEvent({
+        eventTime,
+        action: (resolve(mapping.action, record) ?? ''),
+        bizStep: resolve(mapping.bizStep, record) ?? '',
+        disposition: resolve(mapping.disposition, record),
+        epcList: epc ? [epc] : [],
+        readPoint: resolve(mapping.readPoint, record),
+        bizLocation: resolve(mapping.bizLocation, record)
+    });
+}
+/**
+ * 레거시 레코드 배열 → 정규 EPCIS 봉투. 매핑 후 검증, 실패분은 rejected(오염 차단).
+ * 실 EPCIS-native 소스면 매핑은 거의 항등, 검증만 통과시키면 됨.
+ */
+export function ingest(records, rules, opts) {
+    const ruleByType = new Map(rules.map(r => [r.sourceType, r]));
+    const accepted = [];
+    const rejected = [];
+    let seq = 0;
+    for (const record of records) {
+        const rule = ruleByType.get(String(record['sourceType']));
+        if (!rule) {
+            rejected.push({ record, errors: [`매칭 룰 없음: sourceType=${record['sourceType']}`] });
+            continue;
+        }
+        const eventTime = (opts.eventTimePath ? resolve('$.' + opts.eventTimePath, record) : undefined) ?? opts.defaultEventTime;
+        const ev = mapRecord(record, rule.mapping, eventTime);
+        const errors = validateEpcisEvent(ev);
+        if (errors.length) {
+            rejected.push({ record, errors });
+            continue;
+        }
+        accepted.push({
+            eventId: `${opts.tenantId}-ingest-${++seq}`,
+            eventType: `epcis.${ev.type}`,
+            eventTime: ev.eventTime,
+            tenantId: opts.tenantId,
+            data: ev
+        });
+    }
+    return { accepted, rejected };
+}