@things-factory/headless-twin 10.0.9 → 10.0.11

package/dist-server/service/reference/template-registry.d.ts

@@ -1,10 +1,18 @@
+import type { DomainSystem } from '@operato/twin-kernel';
 import type { ReferenceMaster } from './reference-master.js';
 /** 사용자 노출 파라미터(노브) 정의 — 클라이언트가 이 스키마로 폼을 렌더한다. */
 export interface KnobDef {
     key: string;
     /** 'geo' = 위경도 지점(지도에서 클릭 선택). 값은 { lat, lon }. 사용자가 좌표를 몰라도 지도로 지정. */
     label: string;
-    type: 'number' | 'text' | 'select' | 'geo';
+    /**
+     * 'siteEquipment' = **이 현장에 이미 있는 설비들**(`{id, kind}`). 값이 비어 있으면 만들 때 한 번
+     * 해석해서 채우고, 채운 결과를 노브 값으로 **남긴다**(`origin.params`). 그래야 나중에 다시 지어도
+     * 같은 트윈이 나온다 — 그때그때 현장을 다시 읽으면 사이에 설비가 늘고 준 만큼 다른 트윈이 된다.
+     *
+     * 종류를 함께 싣는 이유: 무엇을 받아들일지는 **템플릿이 종류로 판단**한다(이름으로 짐작하지 않는다).
+     */
+    type: 'number' | 'text' | 'select' | 'geo' | 'siteEquipment';
     default: any;
     min?: number;
     max?: number;
@@ -64,11 +72,18 @@ export interface TemplateDetail {
         /** 완성 라우트 이름(공정 라우트 참조). */
         route?: string;
     };
-    /** 표준 정합 매핑(개념 ↔ EPCIS/ISA-95). */
+    /**
+     * 표준 정합 매핑 — 개념이 **어느 표준의 무엇에 대응하나.**
+     *
+     * 표준 칸이 EPCIS·ISA-95 둘로 굳어 있었다. 에너지 템플릿은 그 둘이 앵커가 아니라 적을 자리가 없었다 —
+     * 커널의 `StandardClass` 도 같은 이유로 열었다(`iso50001`·`iec61850`). 대응할 이름이 없으면 **비운다**.
+     */
     standardsMap?: {
         concept: string;
         epcis?: string;
         isa95?: string;
+        iso50001?: string;
+        iec61850?: string;
     }[];
     /** "이 템플릿이 맞나?" 판단 도움 항목. */
     fits?: string[];
@@ -76,7 +91,8 @@ export interface TemplateDetail {
 export interface TwinTemplate {
     id: string;
     label: string;
-    system: 'wms' | 'yms' | 'mes';
+    /** 커널 카탈로그가 정본 — 종류가 늘면 여기 손댈 것이 없다(`DomainSystem`). */
+    system: DomainSystem;
     description?: string;
     /** 상세 설명(선택) — 설명 페이지/패널이 렌더. */
     detail?: TemplateDetail;

package/dist-server/service/reference/template-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"template-registry.js","sourceRoot":"","sources":["../../../server/service/reference/template-registry.ts"],"names":[],"mappings":";;AA6DA,4CAEC;AACD,sCAEC;AACD,kCAEC;AATD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAA;AACjD,SAAgB,gBAAgB,CAAC,GAAiB;IAChD,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;AAC5B,CAAC;AACD,SAAgB,aAAa;IAC3B,OAAO,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAA;AAChC,CAAC;AACD,SAAgB,WAAW,CAAC,EAAU;IACpC,OAAO,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AAC1B,CAAC","sourcesContent":["/*\n * 트윈 템플릿(아키타입) 레지스트리 — 파라미터화된 합성 레퍼런스 마스터 빌더.\n * 레퍼런스(reference-registry)가 \"고정 마스터\"라면, 템플릿은 \"노브로 파라미터화된 마스터 빌더\".\n * 둘 다 같은 인제스트 경로(ingestMaster)로 흐른다 — 원천이 고정이냐 합성이냐만 다르다(board-authoring §10).\n * 앱(operato-twin)이 bootstrap 에서 자기 아키타입을 registerTemplate 한다. 표현(map/image/board) 무관.\n */\nimport type { ReferenceMaster } from './reference-master.js'\n\n/** 사용자 노출 파라미터(노브) 정의 — 클라이언트가 이 스키마로 폼을 렌더한다. */\nexport interface KnobDef {\n  key: string\n  /** 'geo' = 위경도 지점(지도에서 클릭 선택). 값은 { lat, lon }. 사용자가 좌표를 몰라도 지도로 지정. */\n  label: string\n  type: 'number' | 'text' | 'select' | 'geo'\n  default: any\n  min?: number\n  max?: number\n  options?: { value: string; label: string }[]\n  help?: string\n}\n\n/**\n * 템플릿 상세(설명 페이지용, 선택) — \"이 템플릿이 무엇을 모델링하나\"를 구조적으로 보여줘 확신을 준다.\n * 순수 표시용 데이터(빌드 로직과 무관). 클라이언트가 이 스키마로 상세 뷰를 렌더한다.\n */\nexport interface TemplateDetail {\n  /** 한 줄 요약(누구를 위한/무엇). */\n  summary?: string\n  standards?: string[]\n  /** 밸류체인 국면(반입·보관·변환·반출 등). */\n  phases?: { key: string; label: string; system?: string; note?: string }[]\n  /** 공정 라우트(오퍼레이션 시퀀스). */\n  route?: { op: string; label?: string; resource?: string; intent?: string; bizStep?: string }[]\n  locationTypes?: { key: string; label?: string; standardClass?: string; capabilities?: string[] }[]\n  resourceTypes?: { key: string; label?: string; standardClass?: string; capabilities?: string[] }[]\n  /** BOM/레시피 요약. */\n  recipe?: {\n    inputs: { material: string; qty: number; key?: string }[]\n    outputs: { material: string; qty: number; key?: string }[]\n    /** 완성 라우트 이름(공정 라우트 참조). */\n    route?: string\n  }\n  /** 표준 정합 매핑(개념 ↔ EPCIS/ISA-95). */\n  standardsMap?: { concept: string; epcis?: string; isa95?: string }[]\n  /** \"이 템플릿이 맞나?\" 판단 도움 항목. */\n  fits?: string[]\n}\n\nexport interface TwinTemplate {\n  id: string\n  label: string\n  system: 'wms' | 'yms' | 'mes'\n  description?: string\n  /** 상세 설명(선택) — 설명 페이지/패널이 렌더. */\n  detail?: TemplateDetail\n  knobs: KnobDef[]\n  /** 노브 값 → 합성 마스터(+옵션 시나리오). scenario 는 runtime.scenario.load 로 전달되는 불투명 값. */\n  build(params: Record<string, any>): { master: ReferenceMaster; scenario?: any }\n}\n\nconst templates = new Map<string, TwinTemplate>()\nexport function registerTemplate(tpl: TwinTemplate): void {\n  templates.set(tpl.id, tpl)\n}\nexport function listTemplates(): TwinTemplate[] {\n  return [...templates.values()]\n}\nexport function getTemplate(id: string): TwinTemplate | undefined {\n  return templates.get(id)\n}\n"]}
+{"version":3,"file":"template-registry.js","sourceRoot":"","sources":["../../../server/service/reference/template-registry.ts"],"names":[],"mappings":";;AA4EA,4CAEC;AACD,sCAEC;AACD,kCAEC;AATD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAA;AACjD,SAAgB,gBAAgB,CAAC,GAAiB;IAChD,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;AAC5B,CAAC;AACD,SAAgB,aAAa;IAC3B,OAAO,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAA;AAChC,CAAC;AACD,SAAgB,WAAW,CAAC,EAAU;IACpC,OAAO,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AAC1B,CAAC","sourcesContent":["/*\n * 트윈 템플릿(아키타입) 레지스트리 — 파라미터화된 합성 레퍼런스 마스터 빌더.\n * 레퍼런스(reference-registry)가 \"고정 마스터\"라면, 템플릿은 \"노브로 파라미터화된 마스터 빌더\".\n * 둘 다 같은 인제스트 경로(ingestMaster)로 흐른다 — 원천이 고정이냐 합성이냐만 다르다(board-authoring §10).\n * 앱(operato-twin)이 bootstrap 에서 자기 아키타입을 registerTemplate 한다. 표현(map/image/model) 무관.\n */\nimport type { DomainSystem } from '@operato/twin-kernel'\n\nimport type { ReferenceMaster } from './reference-master.js'\n\n/** 사용자 노출 파라미터(노브) 정의 — 클라이언트가 이 스키마로 폼을 렌더한다. */\nexport interface KnobDef {\n  key: string\n  /** 'geo' = 위경도 지점(지도에서 클릭 선택). 값은 { lat, lon }. 사용자가 좌표를 몰라도 지도로 지정. */\n  label: string\n  /**\n   * 'siteEquipment' = **이 현장에 이미 있는 설비들**(`{id, kind}`). 값이 비어 있으면 만들 때 한 번\n   * 해석해서 채우고, 채운 결과를 노브 값으로 **남긴다**(`origin.params`). 그래야 나중에 다시 지어도\n   * 같은 트윈이 나온다 — 그때그때 현장을 다시 읽으면 사이에 설비가 늘고 준 만큼 다른 트윈이 된다.\n   *\n   * 종류를 함께 싣는 이유: 무엇을 받아들일지는 **템플릿이 종류로 판단**한다(이름으로 짐작하지 않는다).\n   */\n  type: 'number' | 'text' | 'select' | 'geo' | 'siteEquipment'\n  default: any\n  min?: number\n  max?: number\n  options?: { value: string; label: string }[]\n  help?: string\n}\n\n/**\n * 템플릿 상세(설명 페이지용, 선택) — \"이 템플릿이 무엇을 모델링하나\"를 구조적으로 보여줘 확신을 준다.\n * 순수 표시용 데이터(빌드 로직과 무관). 클라이언트가 이 스키마로 상세 뷰를 렌더한다.\n */\nexport interface TemplateDetail {\n  /** 한 줄 요약(누구를 위한/무엇). */\n  summary?: string\n  standards?: string[]\n  /** 밸류체인 국면(반입·보관·변환·반출 등). */\n  phases?: { key: string; label: string; system?: string; note?: string }[]\n  /** 공정 라우트(오퍼레이션 시퀀스). */\n  route?: { op: string; label?: string; resource?: string; intent?: string; bizStep?: string }[]\n  locationTypes?: { key: string; label?: string; standardClass?: string; capabilities?: string[] }[]\n  resourceTypes?: { key: string; label?: string; standardClass?: string; capabilities?: string[] }[]\n  /** BOM/레시피 요약. */\n  recipe?: {\n    inputs: { material: string; qty: number; key?: string }[]\n    outputs: { material: string; qty: number; key?: string }[]\n    /** 완성 라우트 이름(공정 라우트 참조). */\n    route?: string\n  }\n  /**\n   * 표준 정합 매핑 — 개념이 **어느 표준의 무엇에 대응하나.**\n   *\n   * 표준 칸이 EPCIS·ISA-95 둘로 굳어 있었다. 에너지 템플릿은 그 둘이 앵커가 아니라 적을 자리가 없었다 —\n   * 커널의 `StandardClass` 도 같은 이유로 열었다(`iso50001`·`iec61850`). 대응할 이름이 없으면 **비운다**.\n   */\n  standardsMap?: { concept: string; epcis?: string; isa95?: string; iso50001?: string; iec61850?: string }[]\n  /** \"이 템플릿이 맞나?\" 판단 도움 항목. */\n  fits?: string[]\n}\n\nexport interface TwinTemplate {\n  id: string\n  label: string\n  /** 커널 카탈로그가 정본 — 종류가 늘면 여기 손댈 것이 없다(`DomainSystem`). */\n  system: DomainSystem\n  description?: string\n  /** 상세 설명(선택) — 설명 페이지/패널이 렌더. */\n  detail?: TemplateDetail\n  knobs: KnobDef[]\n  /** 노브 값 → 합성 마스터(+옵션 시나리오). scenario 는 runtime.scenario.load 로 전달되는 불투명 값. */\n  build(params: Record<string, any>): { master: ReferenceMaster; scenario?: any }\n}\n\nconst templates = new Map<string, TwinTemplate>()\nexport function registerTemplate(tpl: TwinTemplate): void {\n  templates.set(tpl.id, tpl)\n}\nexport function listTemplates(): TwinTemplate[] {\n  return [...templates.values()]\n}\nexport function getTemplate(id: string): TwinTemplate | undefined {\n  return templates.get(id)\n}\n"]}

package/dist-server/service/twin-audit/command-audit.d.ts

@@ -0,0 +1,37 @@
+export type CommandOrigin = 'user' | 'ai' | 'automation' | 'unknown';
+export type CommandAuditInput = {
+    /** 클라이언트가 실어 보낸 커맨드(신뢰하지 않는 부분을 포함한 원본). */
+    command: any;
+    /** 커널 판정. */
+    ack: {
+        accepted?: boolean;
+        errorCode?: string;
+        error?: string;
+    };
+    /** 세션이 아는 사용자 — **서버만 채운다.** */
+    actor?: {
+        id?: string;
+        email?: string;
+        name?: string;
+    };
+    /** 서버 시각. 호출부가 주입해 테스트가 시간을 고정할 수 있게 한다. */
+    at: Date;
+};
+/** `TwinAuditEvent` 에 그대로 넣을 수 있는 모양(엔티티를 몰라도 되게 순수하게 둔다). */
+export type CommandAuditRow = {
+    eventTime: Date;
+    commandId?: string;
+    commandType?: string;
+    origin: CommandOrigin;
+    reason?: string;
+    actorId?: string;
+    actorEmail?: string;
+    actorName?: string;
+    accepted: boolean;
+    errorCode?: string;
+    args?: any;
+    argsTruncated: boolean;
+};
+/** 신뢰할 수 있는 출처 표기로 정규화 — 모르는 값은 지어내지 않고 'unknown' 으로 둔다. */
+export declare function normalizeOrigin(v: unknown): CommandOrigin;
+export declare function buildCommandAudit(input: CommandAuditInput): CommandAuditRow;

package/dist-server/service/twin-audit/command-audit.js

@@ -0,0 +1,53 @@
+"use strict";
+/*
+ * 커맨드 감사 기록 만들기 (순수) — **누가 무엇을 허락했고, 그래서 어떻게 됐나.**
+ *
+ * 승인 게이트가 앞을 막고, 이 기록이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를 증명할 수 있다.
+ *
+ * 무엇을 믿는가가 이 기록의 전부다:
+ *  · **신원·시각은 서버가 준다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 아무것도
+ *    증명하지 못한다. 세션이 아는 사용자와 서버 시각만 쓴다.
+ *  · **의도는 클라이언트가 준다** — 출처(origin)·근거(reason). 서버가 알 수 없는 정보이고,
+ *    위조되더라도 신원 증명을 훼손하지 않는다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeOrigin = normalizeOrigin;
+exports.buildCommandAudit = buildCommandAudit;
+/** 신뢰할 수 있는 출처 표기로 정규화 — 모르는 값은 지어내지 않고 'unknown' 으로 둔다. */
+function normalizeOrigin(v) {
+    return v === 'user' || v === 'ai' || v === 'automation' ? v : 'unknown';
+}
+/** args 직렬화 상한(문자). 넘으면 자르되 잘랐다고 표시한다. */
+const ARGS_MAX = 4000;
+function buildCommandAudit(input) {
+    const { command, ack, actor, at } = input;
+    const argsText = safeJson(command?.args);
+    const truncated = argsText !== null && argsText.length > ARGS_MAX;
+    return {
+        eventTime: at,
+        commandId: str(command?.commandId),
+        commandType: str(command?.type),
+        origin: normalizeOrigin(command?.origin),
+        reason: str(command?.reason),
+        /* 신원 — 세션 값만. 커맨드에 실려 온 신원 주장은 쳐다보지 않는다. */
+        actorId: str(actor?.id),
+        actorEmail: str(actor?.email),
+        actorName: str(actor?.name),
+        /* 결과 — 승인했는데 커널이 거절한 것도 감사 대상이다(무엇을 시도했는지가 남아야 한다). */
+        accepted: !!ack?.accepted,
+        errorCode: str(ack?.errorCode),
+        /* 인자는 원형 그대로. 너무 크면 잘린 문자열로 두되 잘랐다고 말한다. */
+        args: truncated ? argsText.slice(0, ARGS_MAX) : command?.args ?? undefined,
+        argsTruncated: truncated
+    };
+}
+const str = (v) => (typeof v === 'string' && v ? v : undefined);
+function safeJson(v) {
+    try {
+        return v === undefined ? null : JSON.stringify(v);
+    }
+    catch {
+        return null; /* 순환 참조 등 — 못 재면 자르지 않는다(원본을 그대로 둔다) */
+    }
+}
+//# sourceMappingURL=command-audit.js.map

package/dist-server/service/twin-audit/command-audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-audit.js","sourceRoot":"","sources":["../../../server/service/twin-audit/command-audit.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAgCH,0CAEC;AAKD,8CAqBC;AA7BD,4DAA4D;AAC5D,SAAgB,eAAe,CAAC,CAAU;IACxC,OAAO,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AACzE,CAAC;AAED,0CAA0C;AAC1C,MAAM,QAAQ,GAAG,IAAI,CAAA;AAErB,SAAgB,iBAAiB,CAAC,KAAwB;IACxD,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,KAAK,CAAA;IACzC,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IACxC,MAAM,SAAS,GAAG,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAA;IACjE,OAAO;QACL,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC;QAClC,WAAW,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC;QAC/B,MAAM,EAAE,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC;QACxC,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC;QAC5B,4CAA4C;QAC5C,OAAO,EAAE,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC;QACvB,UAAU,EAAE,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC;QAC7B,SAAS,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC;QAC3B,uDAAuD;QACvD,QAAQ,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ;QACzB,SAAS,EAAE,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC;QAC9B,4CAA4C;QAC5C,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,QAAS,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,SAAS;QAC3E,aAAa,EAAE,SAAS;KACzB,CAAA;AACH,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,CAAU,EAAsB,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAE5F,SAAS,QAAQ,CAAC,CAAU;IAC1B,IAAI,CAAC;QACH,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA,CAAC,wCAAwC;IACtD,CAAC;AACH,CAAC","sourcesContent":["/*\n * 커맨드 감사 기록 만들기 (순수) — **누가 무엇을 허락했고, 그래서 어떻게 됐나.**\n *\n * 승인 게이트가 앞을 막고, 이 기록이 뒤를 설명한다. 둘 다 있어야 \"사람 손을 거쳤다\" 를 증명할 수 있다.\n *\n * 무엇을 믿는가가 이 기록의 전부다:\n *  · **신원·시각은 서버가 준다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 아무것도\n *    증명하지 못한다. 세션이 아는 사용자와 서버 시각만 쓴다.\n *  · **의도는 클라이언트가 준다** — 출처(origin)·근거(reason). 서버가 알 수 없는 정보이고,\n *    위조되더라도 신원 증명을 훼손하지 않는다.\n */\n\nexport type CommandOrigin = 'user' | 'ai' | 'automation' | 'unknown'\n\nexport type CommandAuditInput = {\n  /** 클라이언트가 실어 보낸 커맨드(신뢰하지 않는 부분을 포함한 원본). */\n  command: any\n  /** 커널 판정. */\n  ack: { accepted?: boolean; errorCode?: string; error?: string }\n  /** 세션이 아는 사용자 — **서버만 채운다.** */\n  actor?: { id?: string; email?: string; name?: string }\n  /** 서버 시각. 호출부가 주입해 테스트가 시간을 고정할 수 있게 한다. */\n  at: Date\n}\n\n/** `TwinAuditEvent` 에 그대로 넣을 수 있는 모양(엔티티를 몰라도 되게 순수하게 둔다). */\nexport type CommandAuditRow = {\n  eventTime: Date\n  commandId?: string\n  commandType?: string\n  origin: CommandOrigin\n  reason?: string\n  actorId?: string\n  actorEmail?: string\n  actorName?: string\n  accepted: boolean\n  errorCode?: string\n  args?: any\n  argsTruncated: boolean\n}\n\n/** 신뢰할 수 있는 출처 표기로 정규화 — 모르는 값은 지어내지 않고 'unknown' 으로 둔다. */\nexport function normalizeOrigin(v: unknown): CommandOrigin {\n  return v === 'user' || v === 'ai' || v === 'automation' ? v : 'unknown'\n}\n\n/** args 직렬화 상한(문자). 넘으면 자르되 잘랐다고 표시한다. */\nconst ARGS_MAX = 4000\n\nexport function buildCommandAudit(input: CommandAuditInput): CommandAuditRow {\n  const { command, ack, actor, at } = input\n  const argsText = safeJson(command?.args)\n  const truncated = argsText !== null && argsText.length > ARGS_MAX\n  return {\n    eventTime: at,\n    commandId: str(command?.commandId),\n    commandType: str(command?.type),\n    origin: normalizeOrigin(command?.origin),\n    reason: str(command?.reason),\n    /* 신원 — 세션 값만. 커맨드에 실려 온 신원 주장은 쳐다보지 않는다. */\n    actorId: str(actor?.id),\n    actorEmail: str(actor?.email),\n    actorName: str(actor?.name),\n    /* 결과 — 승인했는데 커널이 거절한 것도 감사 대상이다(무엇을 시도했는지가 남아야 한다). */\n    accepted: !!ack?.accepted,\n    errorCode: str(ack?.errorCode),\n    /* 인자는 원형 그대로. 너무 크면 잘린 문자열로 두되 잘랐다고 말한다. */\n    args: truncated ? argsText!.slice(0, ARGS_MAX) : command?.args ?? undefined,\n    argsTruncated: truncated\n  }\n}\n\nconst str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined)\n\nfunction safeJson(v: unknown): string | null {\n  try {\n    return v === undefined ? null : JSON.stringify(v)\n  } catch {\n    return null /* 순환 참조 등 — 못 재면 자르지 않는다(원본을 그대로 둔다) */\n  }\n}\n"]}

package/dist-server/service/twin-audit/index.d.ts

@@ -0,0 +1,4 @@
+import { TwinAuditEvent } from './twin-audit-event.js';
+import { TwinAuditQuery } from './twin-audit-query.js';
+export declare const entities: (typeof TwinAuditEvent)[];
+export declare const resolvers: (typeof TwinAuditQuery)[];

package/dist-server/service/twin-audit/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvers = exports.entities = void 0;
+const twin_audit_event_js_1 = require("./twin-audit-event.js");
+const twin_audit_query_js_1 = require("./twin-audit-query.js");
+exports.entities = [twin_audit_event_js_1.TwinAuditEvent];
+exports.resolvers = [twin_audit_query_js_1.TwinAuditQuery];
+//# sourceMappingURL=index.js.map

package/dist-server/service/twin-audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../server/service/twin-audit/index.ts"],"names":[],"mappings":";;;AAAA,+DAAsD;AACtD,+DAAsD;AAEzC,QAAA,QAAQ,GAAG,CAAC,oCAAc,CAAC,CAAA;AAC3B,QAAA,SAAS,GAAG,CAAC,oCAAc,CAAC,CAAA","sourcesContent":["import { TwinAuditEvent } from './twin-audit-event.js'\nimport { TwinAuditQuery } from './twin-audit-query.js'\n\nexport const entities = [TwinAuditEvent]\nexport const resolvers = [TwinAuditQuery]\n"]}

package/dist-server/service/twin-audit/twin-audit-event.d.ts

@@ -0,0 +1,24 @@
+import { Domain } from '@things-factory/shell';
+export declare class TwinAuditEvent {
+    readonly id: string;
+    domain?: Domain;
+    domainId?: string;
+    instanceId: string;
+    eventTime: Date;
+    commandId?: string;
+    commandType?: string;
+    origin?: string;
+    reason?: string;
+    actorId?: string;
+    actorEmail?: string;
+    actorName?: string;
+    accepted: boolean;
+    errorCode?: string;
+    /**
+     * 명령 인자 — **원형 그대로.** 무엇에 대한 명령이었는지가 감사의 핵심이라 요약하지 않는다.
+     * 지나치게 크면 자르되 `argsTruncated` 로 잘랐다는 사실을 남긴다(조용히 버리지 않는다).
+     */
+    args?: any;
+    argsTruncated: boolean;
+    createdAt?: Date;
+}

package/dist-server/service/twin-audit/twin-audit-event.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinAuditEvent = void 0;
+const tslib_1 = require("tslib");
+const typeorm_1 = require("typeorm");
+const type_graphql_1 = require("type-graphql");
+const shell_1 = require("@things-factory/shell");
+const env_1 = require("@things-factory/env");
+/*
+ * 긴 글의 컬럼 타입은 **드라이버마다 이름이 다르다** — 이 레포의 정본 관행대로 여기서 고른다
+ * (board-service 의 `Board.model` 과 같은 방식). `text` 를 그대로 적었더니 Oracle 이 모르는 이름이었다.
+ */
+const DATABASE_TYPE = env_1.config.get('ormconfig', {}).type;
+/*
+ * TwinAuditEvent — **사람이 무엇을 허락했는가.**
+ *
+ * ── 왜 저널(TwinEvent)이 아닌가 ───────────────────────────────────────────────
+ * 처음에는 저널에 함께 넣었다. "감사는 원장에서 하니까" 라는 이유였는데, 그건 **화면의 편의**였고
+ * 저장 구조를 정할 근거가 못 됐다. 넣자마자 예외가 넷 생겼다 — 리플레이에서 빼고, 백필에서 빼고,
+ * 원장 거래 분류에서 빼고, 원장 렌더에서 갈랐다. **예외가 넷이면 설계가 "여기 아니다" 라고 말하는 것이다.**
+ *
+ * 갈라 두면 예외가 0 이고, 오히려 얻는다:
+ *  · 행위자가 **컬럼**이 된다 — "누가 승인한 것 전부" 는 감사의 기본 질문인데 payload 안에서는 못 찾았다
+ *  · revision 이 없다. 저널에서는 그 칸을 비워 "상태가 아님" 을 뜻하게 썼는데, 없음을 종류 표시로
+ *    쓰는 것이 여러 번 문제를 냈다(백필의 `bizStep IS NULL = 옛 행` 전제가 이것 때문에 깨졌다)
+ *  · bizStep 오염이 없다 — 저널의 키 추출기는 값이 없으면 이벤트 타입으로 대체하므로,
+ *    감사 행을 태우면 CBV 표준 어휘 컬럼에 `governance.command` 가 박힌다
+ *
+ * ── 무엇을 믿는가 ────────────────────────────────────────────────────────────
+ * **신원·시각은 서버가 각인한다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 그 기록은
+ * 아무것도 증명하지 못한다. 세션이 아는 사용자와 서버 시각만 신뢰한다.
+ * 클라이언트에서 받는 것은 **의도**뿐이다 — 어디서 시작됐나(origin), 왜 하나(reason).
+ */
+let TwinAuditEvent = class TwinAuditEvent {
+};
+exports.TwinAuditEvent = TwinAuditEvent;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    (0, type_graphql_1.Field)(type => type_graphql_1.ID, { description: 'Unique identifier of the audit record.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "id", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => shell_1.Domain),
+    (0, type_graphql_1.Field)(type => shell_1.Domain, { nullable: true, description: 'Owning tenant domain.' }),
+    tslib_1.__metadata("design:type", shell_1.Domain)
+], TwinAuditEvent.prototype, "domain", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((e) => e.domain),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "domainId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Twin runtime instance the command was aimed at.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "instanceId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Server time when the command was dispatched.' }),
+    tslib_1.__metadata("design:type", Date)
+], TwinAuditEvent.prototype, "eventTime", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Client-supplied command id, for correlating with kernel logs.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "commandId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Command type (e.g. order.hold, equipment.repair).' }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "commandType", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: "Where the command originated: 'user' | 'ai' | 'automation' | 'unknown'." }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "origin", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({
+        nullable: true,
+        type: DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+            ? 'longtext'
+            : DATABASE_TYPE == 'oracle'
+                ? 'clob'
+                : DATABASE_TYPE == 'mssql'
+                    ? 'nvarchar'
+                    : 'text',
+        length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
+    }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Why this action — the rationale shown on the approval card.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "reason", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Approving user id, stamped by the server from the session.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "actorId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Approving user email, stamped by the server from the session.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "actorEmail", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Approving user name, stamped by the server from the session.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "actorName", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ default: false }),
+    (0, type_graphql_1.Field)({ description: 'Whether the kernel accepted the command.' }),
+    tslib_1.__metadata("design:type", Boolean)
+], TwinAuditEvent.prototype, "accepted", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Language-neutral rejection code when the kernel refused.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinAuditEvent.prototype, "errorCode", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'simple-json', nullable: true }),
+    (0, type_graphql_1.Field)(type => shell_1.ScalarObject, { nullable: true, description: 'Command arguments as given.' }),
+    tslib_1.__metadata("design:type", Object)
+], TwinAuditEvent.prototype, "args", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ default: false }),
+    (0, type_graphql_1.Field)({ description: 'True when args were too large and stored truncated.' }),
+    tslib_1.__metadata("design:type", Boolean)
+], TwinAuditEvent.prototype, "argsTruncated", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)(),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Timestamp when the audit row was written.' }),
+    tslib_1.__metadata("design:type", Date)
+], TwinAuditEvent.prototype, "createdAt", void 0);
+exports.TwinAuditEvent = TwinAuditEvent = tslib_1.__decorate([
+    (0, typeorm_1.Entity)()
+    /* 목록 기본 정렬 — 최근 것부터. 감사는 "요즘 무슨 일이 있었나" 로 시작한다. */
+    ,
+    (0, typeorm_1.Index)('ix_twin_audit_0', (e) => [e.domain, e.instanceId, e.eventTime], { unique: false })
+    /* 행위자로 찾기 — 저널에 있을 때는 불가능했던 질문("김현장이 승인한 것 전부"). */
+    ,
+    (0, typeorm_1.Index)('ix_twin_audit_1', (e) => [e.domain, e.actorEmail, e.eventTime], { unique: false }),
+    (0, type_graphql_1.ObjectType)({ description: 'Audit record of a twin command: who approved what, and what the kernel answered.' })
+], TwinAuditEvent);
+//# sourceMappingURL=twin-audit-event.js.map

package/dist-server/service/twin-audit/twin-audit-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-audit-event.js","sourceRoot":"","sources":["../../../server/service/twin-audit/twin-audit-event.ts"],"names":[],"mappings":"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","sourcesContent":["import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn } from 'typeorm'\nimport { ObjectType, Field, ID } from 'type-graphql'\n\nimport { Domain, ScalarObject } from '@things-factory/shell'\nimport { config } from '@things-factory/env'\n\n/*\n * 긴 글의 컬럼 타입은 **드라이버마다 이름이 다르다** — 이 레포의 정본 관행대로 여기서 고른다\n * (board-service 의 `Board.model` 과 같은 방식). `text` 를 그대로 적었더니 Oracle 이 모르는 이름이었다.\n */\nconst DATABASE_TYPE = config.get('ormconfig', {}).type\n\n/*\n * TwinAuditEvent — **사람이 무엇을 허락했는가.**\n *\n * ── 왜 저널(TwinEvent)이 아닌가 ───────────────────────────────────────────────\n * 처음에는 저널에 함께 넣었다. \"감사는 원장에서 하니까\" 라는 이유였는데, 그건 **화면의 편의**였고\n * 저장 구조를 정할 근거가 못 됐다. 넣자마자 예외가 넷 생겼다 — 리플레이에서 빼고, 백필에서 빼고,\n * 원장 거래 분류에서 빼고, 원장 렌더에서 갈랐다. **예외가 넷이면 설계가 \"여기 아니다\" 라고 말하는 것이다.**\n *\n * 갈라 두면 예외가 0 이고, 오히려 얻는다:\n *  · 행위자가 **컬럼**이 된다 — \"누가 승인한 것 전부\" 는 감사의 기본 질문인데 payload 안에서는 못 찾았다\n *  · revision 이 없다. 저널에서는 그 칸을 비워 \"상태가 아님\" 을 뜻하게 썼는데, 없음을 종류 표시로\n *    쓰는 것이 여러 번 문제를 냈다(백필의 `bizStep IS NULL = 옛 행` 전제가 이것 때문에 깨졌다)\n *  · bizStep 오염이 없다 — 저널의 키 추출기는 값이 없으면 이벤트 타입으로 대체하므로,\n *    감사 행을 태우면 CBV 표준 어휘 컬럼에 `governance.command` 가 박힌다\n *\n * ── 무엇을 믿는가 ────────────────────────────────────────────────────────────\n * **신원·시각은 서버가 각인한다.** 클라이언트가 말한 신원을 그대로 적으면 위조가 자유로워 그 기록은\n * 아무것도 증명하지 못한다. 세션이 아는 사용자와 서버 시각만 신뢰한다.\n * 클라이언트에서 받는 것은 **의도**뿐이다 — 어디서 시작됐나(origin), 왜 하나(reason).\n */\n@Entity()\n/* 목록 기본 정렬 — 최근 것부터. 감사는 \"요즘 무슨 일이 있었나\" 로 시작한다. */\n@Index('ix_twin_audit_0', (e: TwinAuditEvent) => [e.domain, e.instanceId, e.eventTime], { unique: false })\n/* 행위자로 찾기 — 저널에 있을 때는 불가능했던 질문(\"김현장이 승인한 것 전부\"). */\n@Index('ix_twin_audit_1', (e: TwinAuditEvent) => [e.domain, e.actorEmail, e.eventTime], { unique: false })\n@ObjectType({ description: 'Audit record of a twin command: who approved what, and what the kernel answered.' })\nexport class TwinAuditEvent {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => ID, { description: 'Unique identifier of the audit record.' })\n  readonly id: string\n\n  @ManyToOne(type => Domain)\n  @Field(type => Domain, { nullable: true, description: 'Owning tenant domain.' })\n  domain?: Domain\n\n  @RelationId((e: TwinAuditEvent) => e.domain)\n  domainId?: string\n\n  @Column()\n  @Field({ description: 'Twin runtime instance the command was aimed at.' })\n  instanceId: string\n\n  /*\n   * 서버 시각. 클라이언트 시계를 믿지 않는다 — 기록의 시간축이 단말 설정에 좌우되면 안 된다.\n   *\n   * **타입 이름은 적지 않는다** (2026-08-19 Postgres 부팅 실패로 고침).\n   * `datetime` 은 sqlite·MySQL 의 이름이고 Postgres 는 `timestamp` 만 안다 — 거꾸로 `timestamp` 는\n   * sqlite 가 모른다. **다섯 드라이버에 다 통하는 이름이 없다.** 그래서 이름 고르는 일을 TypeORM 에\n   * 맡긴다(`emitDecoratorMetadata` 가 켜져 있어 `Date` 에서 드라이버별 타입을 고른다).\n   */\n  @Column()\n  @Field({ description: 'Server time when the command was dispatched.' })\n  eventTime: Date\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Client-supplied command id, for correlating with kernel logs.' })\n  commandId?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Command type (e.g. order.hold, equipment.repair).' })\n  commandType?: string\n\n  /* 'user' | 'ai' | 'automation' | 'unknown'. 모르면 unknown 이지 사람이 한 것으로 치지 않는다. */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: \"Where the command originated: 'user' | 'ai' | 'automation' | 'unknown'.\" })\n  origin?: string\n\n  /*\n   * 승인 사유 — 사람이 쓰는 글이라 길이를 미리 자르지 않는다.\n   *\n   * 이름을 드라이버별로 고른다(2026-08-19): `text` 는 Oracle 이 모르고(그쪽은 `clob`), MySQL 계열은\n   * 긴 글에 `longtext` 를, MSSQL 은 `nvarchar(MAX)` 를 쓴다. 다중 DB 를 지키는 이 레포의 관행이 그렇다.\n   */\n  @Column({\n    nullable: true,\n    type:\n      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'\n        ? 'longtext'\n        : DATABASE_TYPE == 'oracle'\n          ? 'clob'\n          : DATABASE_TYPE == 'mssql'\n            ? 'nvarchar'\n            : 'text',\n    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined\n  })\n  @Field({ nullable: true, description: 'Why this action — the rationale shown on the approval card.' })\n  reason?: string\n\n  /* ── 신원: 세션에서만 온다 ── */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Approving user id, stamped by the server from the session.' })\n  actorId?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Approving user email, stamped by the server from the session.' })\n  actorEmail?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Approving user name, stamped by the server from the session.' })\n  actorName?: string\n\n  /* ── 결과: 거절도 남긴다 ── */\n  @Column({ default: false })\n  @Field({ description: 'Whether the kernel accepted the command.' })\n  accepted: boolean\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Language-neutral rejection code when the kernel refused.' })\n  errorCode?: string\n\n  /**\n   * 명령 인자 — **원형 그대로.** 무엇에 대한 명령이었는지가 감사의 핵심이라 요약하지 않는다.\n   * 지나치게 크면 자르되 `argsTruncated` 로 잘랐다는 사실을 남긴다(조용히 버리지 않는다).\n   */\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, { nullable: true, description: 'Command arguments as given.' })\n  args?: any\n\n  @Column({ default: false })\n  @Field({ description: 'True when args were too large and stored truncated.' })\n  argsTruncated: boolean\n\n  @CreateDateColumn()\n  @Field({ nullable: true, description: 'Timestamp when the audit row was written.' })\n  createdAt?: Date\n}\n"]}

package/dist-server/service/twin-audit/twin-audit-query.d.ts

@@ -0,0 +1,4 @@
+import { ListParam } from '@things-factory/shell';
+export declare class TwinAuditQuery {
+    twinAuditList(params: ListParam, context: ResolverContext): Promise<any>;
+}

package/dist-server/service/twin-audit/twin-audit-query.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinAuditQuery = void 0;
+const tslib_1 = require("tslib");
+const type_graphql_1 = require("type-graphql");
+const shell_1 = require("@things-factory/shell");
+const twin_audit_event_js_1 = require("./twin-audit-event.js");
+/*
+ * 승인 기록 조회 — **감사의 기본 질문에 답한다.**
+ *
+ *   "요즘 무슨 조치가 나갔나"        → 최근순 목록
+ *   "김현장이 승인한 것 전부"        → 행위자 검색(인덱스 있음)
+ *   "AI 가 제안한 것만"              → origin 필터
+ *   "거절된 시도"                    → accepted 필터
+ *
+ * 저널에 섞여 있을 때는 이 중 어느 것도 못 했다 — 행위자가 payload JSON 안이라 인덱스를 걸 수 없었다.
+ */
+/** 시각 필터 값을 날짜로 — 못 읽는 값은 그대로 둔다(지어내지 않는다). */
+function toDateValue(v) {
+    const one = (x) => {
+        if (x instanceof Date)
+            return x;
+        const t = typeof x === 'string' ? Date.parse(x) : NaN;
+        return Number.isNaN(t) ? x : new Date(t);
+    };
+    return Array.isArray(v) ? v.map(one) : one(v);
+}
+let TwinAuditQuery = class TwinAuditQuery {
+    /* 조회 게이트는 달지 않는다 — 이 저장소의 규약이고(mutation-gate 검사가 정본을 지킨다),
+       도메인 필터가 테넌트 경계를 이미 지킨다. 테넌트를 넘어 읽는 계기판만 OPS_GATE 를 쓴다. */
+    async twinAuditList(params, context) {
+        const domainId = context.state.domain?.id;
+        if (!domainId)
+            return { items: [], total: 0 };
+        const effective = {
+            ...(params ?? {}),
+            /* 기본 정렬 — 최근 것부터. 감사는 "요즘" 에서 시작한다. */
+            sortings: params?.sortings?.length ? params.sortings : [{ name: 'eventTime', desc: true }],
+            /* 시각 필터는 날짜로 옮겨서 넘긴다 — 문자열 그대로면 조용히 0건이 된다(저널과 같은 이유). */
+            filters: (params?.filters ?? []).map(f => (f.name === 'eventTime' ? { ...f, value: toDateValue(f.value) } : f))
+        };
+        const qb = (0, shell_1.getQueryBuilderFromListParams)({
+            repository: (0, shell_1.getRepository)(twin_audit_event_js_1.TwinAuditEvent),
+            params: effective,
+            domain: context.state.domain,
+            alias: 'a',
+            /*
+             * `searchables` 는 전부 **실컬럼**이다 — 프레임워크 질의 빌더는 여기 없는 컬럼의 LIKE 를
+             * 경고 후 무시한다(인덱스 없는 전체 스캔 방지). 행위자로 찾는 것이 이 테이블을 구분한 이유다.
+             */
+            searchables: ['actorEmail', 'actorName', 'commandType', 'origin', 'errorCode', 'reason'],
+            sortables: ['eventTime', 'commandType', 'actorEmail', 'origin', 'accepted'],
+            /* 감사 목록은 사람이 읽는 속도로 본다 — 크게 퍼 오는 것이 이득이 아니다. */
+            defaultLimit: 50,
+            maxLimit: 200
+        });
+        const [items, total] = await qb.getManyAndCount();
+        return { items, total };
+    }
+};
+exports.TwinAuditQuery = TwinAuditQuery;
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        nullable: true,
+        description: 'List twin command audit records (who approved what, and what the kernel answered) with the standard list contract, plus the total match count.'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Args)(type => shell_1.ListParam)),
+    tslib_1.__param(1, (0, type_graphql_1.Ctx)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [shell_1.ListParam, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinAuditQuery.prototype, "twinAuditList", null);
+exports.TwinAuditQuery = TwinAuditQuery = tslib_1.__decorate([
+    (0, type_graphql_1.Resolver)()
+], TwinAuditQuery);
+//# sourceMappingURL=twin-audit-query.js.map

package/dist-server/service/twin-audit/twin-audit-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-audit-query.js","sourceRoot":"","sources":["../../../server/service/twin-audit/twin-audit-query.ts"],"names":[],"mappings":"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","sourcesContent":["import { Args, Ctx, Query, Resolver } from 'type-graphql'\n\nimport { ListParam, getQueryBuilderFromListParams, getRepository, ScalarObject } from '@things-factory/shell'\n\nimport { TwinAuditEvent } from './twin-audit-event.js'\n\n/*\n * 승인 기록 조회 — **감사의 기본 질문에 답한다.**\n *\n *   \"요즘 무슨 조치가 나갔나\"        → 최근순 목록\n *   \"김현장이 승인한 것 전부\"        → 행위자 검색(인덱스 있음)\n *   \"AI 가 제안한 것만\"              → origin 필터\n *   \"거절된 시도\"                    → accepted 필터\n *\n * 저널에 섞여 있을 때는 이 중 어느 것도 못 했다 — 행위자가 payload JSON 안이라 인덱스를 걸 수 없었다.\n */\n/** 시각 필터 값을 날짜로 — 못 읽는 값은 그대로 둔다(지어내지 않는다). */\nfunction toDateValue(v: any): any {\n  const one = (x: any) => {\n    if (x instanceof Date) return x\n    const t = typeof x === 'string' ? Date.parse(x) : NaN\n    return Number.isNaN(t) ? x : new Date(t)\n  }\n  return Array.isArray(v) ? v.map(one) : one(v)\n}\n\n@Resolver()\nexport class TwinAuditQuery {\n  /* 조회 게이트는 달지 않는다 — 이 저장소의 규약이고(mutation-gate 검사가 정본을 지킨다),\n     도메인 필터가 테넌트 경계를 이미 지킨다. 테넌트를 넘어 읽는 계기판만 OPS_GATE 를 쓴다. */\n  @Query(returns => ScalarObject, {\n    nullable: true,\n    description:\n      'List twin command audit records (who approved what, and what the kernel answered) with the standard list contract, plus the total match count.'\n  })\n  async twinAuditList(\n    /* 표준 목록 계약은 `@Args` 로 펼쳐 받는다 — `@Arg` 로 받으면 type-graphql 이 입력 타입을\n       결정하지 못해 **스키마 조립 자체가 실패**한다(서버가 아예 안 뜬다). */\n    @Args(type => ListParam) params: ListParam,\n    @Ctx() context: ResolverContext\n  ): Promise<any> {\n    const domainId = context.state.domain?.id\n    if (!domainId) return { items: [], total: 0 }\n\n    const effective: ListParam = {\n      ...(params ?? ({} as ListParam)),\n      /* 기본 정렬 — 최근 것부터. 감사는 \"요즘\" 에서 시작한다. */\n      sortings: params?.sortings?.length ? params.sortings : [{ name: 'eventTime', desc: true }],\n      /* 시각 필터는 날짜로 옮겨서 넘긴다 — 문자열 그대로면 조용히 0건이 된다(저널과 같은 이유). */\n      filters: (params?.filters ?? []).map(f => (f.name === 'eventTime' ? { ...f, value: toDateValue(f.value) } : f))\n    }\n\n    const qb = getQueryBuilderFromListParams({\n      repository: getRepository(TwinAuditEvent),\n      params: effective,\n      domain: context.state.domain,\n      alias: 'a',\n      /*\n       * `searchables` 는 전부 **실컬럼**이다 — 프레임워크 질의 빌더는 여기 없는 컬럼의 LIKE 를\n       * 경고 후 무시한다(인덱스 없는 전체 스캔 방지). 행위자로 찾는 것이 이 테이블을 구분한 이유다.\n       */\n      searchables: ['actorEmail', 'actorName', 'commandType', 'origin', 'errorCode', 'reason'],\n      sortables: ['eventTime', 'commandType', 'actorEmail', 'origin', 'accepted'],\n      /* 감사 목록은 사람이 읽는 속도로 본다 — 크게 퍼 오는 것이 이득이 아니다. */\n      defaultLimit: 50,\n      maxLimit: 200\n    })\n\n    const [items, total] = await qb.getManyAndCount()\n    return { items, total }\n  }\n}\n"]}

package/dist-server/service/twin-control/twin-control-mutation.js

@@ -5,7 +5,10 @@ const tslib_1 = require("tslib");
 const type_graphql_1 = require("type-graphql");
 const twin_kernel_1 = require("@operato/twin-kernel");
 const shell_1 = require("@things-factory/shell");
+const shell_2 = require("@things-factory/shell");
 const index_js_1 = require("../../engine/index.js");
+const twin_audit_event_js_1 = require("../twin-audit/twin-audit-event.js");
+const command_audit_js_1 = require("../twin-audit/command-audit.js");
 /*
  * 트윈 Command·Scenario 채널 — 상향 mutation.
  * Command: runtime.dispatch(행위). Scenario: runtime.scenario.load/start/pause/setSpeed(예측 자극).
@@ -25,11 +28,28 @@ let TwinControlMutation = class TwinControlMutation {
          * 시뮬에만 있어서 미러 트윈에서는 이 한 줄이 TypeError 로 터졌다(깔끔한 거절이 아니라 실패).
          * 권위(모드) × 성격(주석/액추에이션) 판정은 한 곳에만 둔다.
          */
+        /* 원본을 그대로 감사에 넘긴다 — 무엇이 들어왔는지가 기록의 대상이다(정규화는 감사 모듈이 한다). */
+        const cmdWithOrigin = command;
         const ack = await index_js_1.TwinEngine.dispatchCommand(domainId, instanceId, command);
-        /* 라이브 구조 변이(resource.add)는 저장 board 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
+        /* 라이브 구조 변이(resource.add)는 저장 model 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
         if (ack?.accepted && command?.type === 'resource.add') {
             await index_js_1.TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => console.error('twin syncBoardEquipment fail', err));
         }
+        /*
+         * 감사 기록 — 승인 게이트가 앞을 막고, 이 줄이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를
+         * 증명할 수 있다. 커널이 거절한 것도 남긴다 — 무엇을 시도했는지가 감사의 절반이다.
+         *
+         * 기록이 실패해도 커맨드 결과는 그대로 돌려준다. 감사가 본업을 막으면 안 되지만, 실패를 삼키지도
+         * 않는다(로그에 남긴다) — 조용히 안 남으면 나중에 "기록이 없다" 와 "일이 없었다" 를 구분 못 한다.
+         */
+        try {
+            const audit = (0, command_audit_js_1.buildCommandAudit)({ command: cmdWithOrigin, ack, actor: context.state.user, at: new Date() });
+            const repo = (0, shell_2.getRepository)(twin_audit_event_js_1.TwinAuditEvent);
+            await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }));
+        }
+        catch (err) {
+            console.error(`[twin-control] command audit not recorded for "${instanceId}"`, err);
+        }
         /* 거절 사유는 **언어 중립 코드**로 함께 돌려준다 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */
         return { accepted: !!ack?.accepted, error: ack?.error, errorCode: ack?.errorCode, errorParams: ack?.errorParams };
     }

package/dist-server/service/twin-control/twin-control-mutation.js.map

@@ -1 +1 @@
-{"version":3,"file":"twin-control-mutation.js","sourceRoot":"","sources":["../../../server/service/twin-control/twin-control-mutation.ts"],"names":[],"mappings":"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","sourcesContent":["import { Arg, Ctx, Mutation, Resolver, Directive} from 'type-graphql'\n\nimport { validateScenario } from '@operato/twin-kernel'\n\nimport { ScalarObject } from '@things-factory/shell'\n\nimport { TwinEngine } from '../../engine/index.js'\n\n/*\n * 트윈 Command·Scenario 채널 — 상향 mutation.\n * Command: runtime.dispatch(행위). Scenario: runtime.scenario.load/start/pause/setSpeed(예측 자극).\n * (State 하향은 twin-state subscription. tick 은 워커.)\n *\n * 인가: data 구독 리졸버와 대칭으로, 대상 인스턴스가 **호출자 도메인 소속**인지 검증한다(cross-tenant 커맨드 주입 차단).\n * command 채널은 sim 상태를 변이하므로 도메인 스코프가 필수.\n */\n@Resolver()\nexport class TwinControlMutation {\n  /** Command 채널 — 오더 hold/resume/release 등. 커널 dispatch 로 위임, ack{accepted,error} 반환. */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => ScalarObject, { description: 'dispatch a twin command (order.hold/resume/release …). Returns {accepted, error?}.' })\n  async dispatchTwinCommand(\n    @Arg('instanceId') instanceId: string,\n    @Arg('command', type => ScalarObject) command: any,\n    @Ctx() context: ResolverContext\n  ): Promise<{ accepted: boolean; error?: string; errorCode?: string; errorParams?: Record<string, string | number> }> {\n    const domainId = context.state.domain?.id\n    if (!domainId) return { accepted: false, error: 'no-domain', errorCode: 'no-domain' }\n    /*\n     * 라우팅은 엔진이 한다 — 예전에는 여기서 `inst.runtime.dispatch` 를 곧바로 불렀고, `runtime` 이\n     * 시뮬에만 있어서 미러 트윈에서는 이 한 줄이 TypeError 로 터졌다(깔끔한 거절이 아니라 실패).\n     * 권위(모드) × 성격(주석/액추에이션) 판정은 한 곳에만 둔다.\n     */\n    const ack = await TwinEngine.dispatchCommand(domainId, instanceId, command)\n    /* 라이브 구조 변이(resource.add)는 저장 board 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */\n    if (ack?.accepted && command?.type === 'resource.add') {\n      await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => console.error('twin syncBoardEquipment fail', err))\n    }\n    /* 거절 사유는 **언어 중립 코드**로 함께 돌려준다 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */\n    return { accepted: !!ack?.accepted, error: ack?.error, errorCode: ack?.errorCode, errorParams: ack?.errorParams }\n  }\n\n  /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause/setSpeed). */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => Boolean, { description: 'control twin scenario (load|start|pause|setSpeed)' })\n  async controlTwinScenario(\n    @Arg('instanceId') instanceId: string,\n    @Arg('action') action: string,\n    @Ctx() context: ResolverContext,\n    @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any\n  ): Promise<boolean> {\n    const domainId = context.state.domain?.id\n    /* 테넌트 격리 — 레지스트리를 직접 색인하지 않는다(키에 도메인이 들어 있다). */\n    if (!TwinEngine.owns(domainId, instanceId)) return false\n    const runtime = TwinEngine.runtime(domainId, instanceId)\n    /*\n     * 자극 주입 가드 — mirror 트윈(외부 실물이 진실)은 커널 시나리오 엔진이 없다(startLive=projector, runtime 없음).\n     * what-if 를 여기에 주입하면 현실을 오염시키므로 거부한다(sim-experiment/sim-world 만 자극 가능). silent throw 방지.\n     */\n    if (!runtime?.scenario) return false\n    /*\n     * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour`\n     * 를 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다).\n     * 규칙은 커널이 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.\n     */\n    if (action === 'load') {\n      const v = validateScenario(scenario)\n      if (v.ok === false) {\n        /* 사유를 로그로 남긴다 — 이 뮤테이션의 반환은 Boolean 계약이라 사유를 실어 보낼 자리가 없다. */\n        console.warn(`[twin] scenario rejected for \"${instanceId}\": ${v.errorCode} ${JSON.stringify(v.errorParams ?? {})}`)\n        return false\n      }\n    }\n    if (action === 'load' && scenario) runtime.scenario.load(scenario)\n    else if (action === 'start') runtime.scenario.start()\n    else if (action === 'pause') runtime.scenario.pause()\n    else if (action === 'setSpeed' && scenario?.speed != null) runtime.scenario.setSpeed(Number(scenario.speed))\n    else return false\n    return true\n  }\n}\n"]}
+{"version":3,"file":"twin-control-mutation.js","sourceRoot":"","sources":["../../../server/service/twin-control/twin-control-mutation.ts"],"names":[],"mappings":"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","sourcesContent":["import { Arg, Ctx, Mutation, Resolver, Directive} from 'type-graphql'\n\nimport { validateScenario } from '@operato/twin-kernel'\n\nimport { ScalarObject } from '@things-factory/shell'\n\nimport { getRepository } from '@things-factory/shell'\n\nimport { TwinEngine } from '../../engine/index.js'\nimport { TwinAuditEvent } from '../twin-audit/twin-audit-event.js'\nimport { buildCommandAudit } from '../twin-audit/command-audit.js'\n\n/*\n * 트윈 Command·Scenario 채널 — 상향 mutation.\n * Command: runtime.dispatch(행위). Scenario: runtime.scenario.load/start/pause/setSpeed(예측 자극).\n * (State 하향은 twin-state subscription. tick 은 워커.)\n *\n * 인가: data 구독 리졸버와 대칭으로, 대상 인스턴스가 **호출자 도메인 소속**인지 검증한다(cross-tenant 커맨드 주입 차단).\n * command 채널은 sim 상태를 변이하므로 도메인 스코프가 필수.\n */\n@Resolver()\nexport class TwinControlMutation {\n  /** Command 채널 — 오더 hold/resume/release 등. 커널 dispatch 로 위임, ack{accepted,error} 반환. */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => ScalarObject, { description: 'dispatch a twin command (order.hold/resume/release …). Returns {accepted, error?}.' })\n  async dispatchTwinCommand(\n    @Arg('instanceId') instanceId: string,\n    @Arg('command', type => ScalarObject) command: any,\n    @Ctx() context: ResolverContext\n  ): Promise<{ accepted: boolean; error?: string; errorCode?: string; errorParams?: Record<string, string | number> }> {\n    const domainId = context.state.domain?.id\n    if (!domainId) return { accepted: false, error: 'no-domain', errorCode: 'no-domain' }\n    /*\n     * 라우팅은 엔진이 한다 — 예전에는 여기서 `inst.runtime.dispatch` 를 곧바로 불렀고, `runtime` 이\n     * 시뮬에만 있어서 미러 트윈에서는 이 한 줄이 TypeError 로 터졌다(깔끔한 거절이 아니라 실패).\n     * 권위(모드) × 성격(주석/액추에이션) 판정은 한 곳에만 둔다.\n     */\n    /* 원본을 그대로 감사에 넘긴다 — 무엇이 들어왔는지가 기록의 대상이다(정규화는 감사 모듈이 한다). */\n    const cmdWithOrigin = command\n    const ack = await TwinEngine.dispatchCommand(domainId, instanceId, command)\n    /* 라이브 구조 변이(resource.add)는 저장 model 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */\n    if (ack?.accepted && command?.type === 'resource.add') {\n      await TwinEngine.syncBoardEquipment(domainId, instanceId).catch(err => console.error('twin syncBoardEquipment fail', err))\n    }\n    /*\n     * 감사 기록 — 승인 게이트가 앞을 막고, 이 줄이 뒤를 설명한다. 둘 다 있어야 \"사람 손을 거쳤다\" 를\n     * 증명할 수 있다. 커널이 거절한 것도 남긴다 — 무엇을 시도했는지가 감사의 절반이다.\n     *\n     * 기록이 실패해도 커맨드 결과는 그대로 돌려준다. 감사가 본업을 막으면 안 되지만, 실패를 삼키지도\n     * 않는다(로그에 남긴다) — 조용히 안 남으면 나중에 \"기록이 없다\" 와 \"일이 없었다\" 를 구분 못 한다.\n     */\n    try {\n      const audit = buildCommandAudit({ command: cmdWithOrigin, ack, actor: context.state.user, at: new Date() })\n      const repo = getRepository(TwinAuditEvent)\n      await repo.save(repo.create({ domain: context.state.domain, instanceId, ...audit }))\n    } catch (err) {\n      console.error(`[twin-control] command audit not recorded for \"${instanceId}\"`, err)\n    }\n\n    /* 거절 사유는 **언어 중립 코드**로 함께 돌려준다 — 화면이 `twin.cmderr.<code>` 로 사람 말을 만든다. */\n    return { accepted: !!ack?.accepted, error: ack?.error, errorCode: ack?.errorCode, errorParams: ack?.errorParams }\n  }\n\n  /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause/setSpeed). */\n  @Directive('@privilege(category: \"twin\", privilege: \"mutation\", domainOwnerGranted: true, superUserGranted: true)')\n  @Mutation(returns => Boolean, { description: 'control twin scenario (load|start|pause|setSpeed)' })\n  async controlTwinScenario(\n    @Arg('instanceId') instanceId: string,\n    @Arg('action') action: string,\n    @Ctx() context: ResolverContext,\n    @Arg('scenario', type => ScalarObject, { nullable: true }) scenario?: any\n  ): Promise<boolean> {\n    const domainId = context.state.domain?.id\n    /* 테넌트 격리 — 레지스트리를 직접 색인하지 않는다(키에 도메인이 들어 있다). */\n    if (!TwinEngine.owns(domainId, instanceId)) return false\n    const runtime = TwinEngine.runtime(domainId, instanceId)\n    /*\n     * 자극 주입 가드 — mirror 트윈(외부 실물이 진실)은 커널 시나리오 엔진이 없다(startLive=projector, runtime 없음).\n     * what-if 를 여기에 주입하면 현실을 오염시키므로 거부한다(sim-experiment/sim-world 만 자극 가능). silent throw 방지.\n     */\n    if (!runtime?.scenario) return false\n    /*\n     * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour`\n     * 를 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다).\n     * 규칙은 커널이 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.\n     */\n    if (action === 'load') {\n      const v = validateScenario(scenario)\n      if (v.ok === false) {\n        /* 사유를 로그로 남긴다 — 이 뮤테이션의 반환은 Boolean 계약이라 사유를 실어 보낼 자리가 없다. */\n        console.warn(`[twin] scenario rejected for \"${instanceId}\": ${v.errorCode} ${JSON.stringify(v.errorParams ?? {})}`)\n        return false\n      }\n    }\n    if (action === 'load' && scenario) runtime.scenario.load(scenario)\n    else if (action === 'start') runtime.scenario.start()\n    else if (action === 'pause') runtime.scenario.pause()\n    else if (action === 'setSpeed' && scenario?.speed != null) runtime.scenario.setSpeed(Number(scenario.speed))\n    else return false\n    return true\n  }\n}\n"]}

package/dist-server/service/twin-event/twin-event-keys.d.ts

@@ -28,7 +28,7 @@ export declare function locationOf(envelope: any): string | undefined;
  * 설비·무버 — 운영 델타(equipment.status·task.status)가 대상을 가리키는 축.
  *
  * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 "이 지게차가 오늘 무엇을 했나" 를
- * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 훑는 수밖에 없다.
+ * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 전수 조회하는 수밖에 없다.
  */
 export declare function equipmentIdOf(envelope: any): string | undefined;
 /** 한 이벤트에서 승격 키 전부 — 기록 경로가 이 함수 하나만 부른다. */

package/dist-server/service/twin-event/twin-event-keys.js

@@ -76,7 +76,7 @@ function locationOf(envelope) {
  * 설비·무버 — 운영 델타(equipment.status·task.status)가 대상을 가리키는 축.
  *
  * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 "이 지게차가 오늘 무엇을 했나" 를
- * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 훑는 수밖에 없다.
+ * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 전수 조회하는 수밖에 없다.
  */
 function equipmentIdOf(envelope) {
     const d = envelope?.data ?? envelope ?? {};