@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -0,0 +1,125 @@
+"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");
+/*
+ * 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)({ type: 'datetime' }),
+    (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)({ type: 'text', nullable: true }),
+    (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'\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   * `datetime` 을 쓴다. `timestamp` 는 **sqlite 가 지원하지 않아** 5개 드라이버 공통이 아니다\n   * (실제로 그렇게 썼다가 DB 를 쓰는 검사 33개가 한꺼번에 터졌다).\n   */\n  @Column({ type: 'datetime' })\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  @Column({ type: 'text', nullable: true })\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":";;;;AAAA,+CAAyD;AAEzD,iDAA6G;AAE7G,+DAAsD;AAEtD;;;;;;;;;GASG;AACH,+CAA+C;AAC/C,SAAS,WAAW,CAAC,CAAM;IACzB,MAAM,GAAG,GAAG,CAAC,CAAM,EAAE,EAAE;QACrB,IAAI,CAAC,YAAY,IAAI;YAAE,OAAO,CAAC,CAAA;QAC/B,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;QACrD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAA;IAC1C,CAAC,CAAA;IACD,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAC/C,CAAC;AAGM,IAAM,cAAc,GAApB,MAAM,cAAc;IACzB;gEAC4D;IAMtD,AAAN,KAAK,CAAC,aAAa,CAGQ,MAAiB,EACnC,OAAwB;QAE/B,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAA;QACzC,IAAI,CAAC,QAAQ;YAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAA;QAE7C,MAAM,SAAS,GAAc;YAC3B,GAAG,CAAC,MAAM,IAAK,EAAgB,CAAC;YAChC,uCAAuC;YACvC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAC1F,0DAA0D;YAC1D,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAChH,CAAA;QAED,MAAM,EAAE,GAAG,IAAA,qCAA6B,EAAC;YACvC,UAAU,EAAE,IAAA,qBAAa,EAAC,oCAAc,CAAC;YACzC,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM;YAC5B,KAAK,EAAE,GAAG;YACV;;;eAGG;YACH,WAAW,EAAE,CAAC,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC;YACxF,SAAS,EAAE,CAAC,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,CAAC;YAC3E,gDAAgD;YAChD,YAAY,EAAE,EAAE;YAChB,QAAQ,EAAE,GAAG;SACd,CAAC,CAAA;QAEF,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,eAAe,EAAE,CAAA;QACjD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;IACzB,CAAC;CACF,CAAA;AA5CY,wCAAc;AAQnB;IALL,IAAA,oBAAK,EAAC,OAAO,CAAC,EAAE,CAAC,oBAAY,EAAE;QAC9B,QAAQ,EAAE,IAAI;QACd,WAAW,EACT,gJAAgJ;KACnJ,CAAC;IAIC,mBAAA,IAAA,mBAAI,EAAC,IAAI,CAAC,EAAE,CAAC,iBAAS,CAAC,CAAA;IACvB,mBAAA,IAAA,kBAAG,GAAE,CAAA;;6CAD2B,iBAAS;;mDAgC3C;yBA3CU,cAAc;IAD1B,IAAA,uBAAQ,GAAE;GACE,cAAc,CA4C1B","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.d.ts

@@ -3,6 +3,8 @@ export declare class TwinControlMutation {
     dispatchTwinCommand(instanceId: string, command: any, context: ResolverContext): Promise<{
         accepted: boolean;
         error?: string;
+        errorCode?: string;
+        errorParams?: Record<string, string | number>;
     }>;
     /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause/setSpeed). */
     controlTwinScenario(instanceId: string, action: string, context: ResolverContext, scenario?: any): Promise<boolean>;

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

@@ -3,8 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TwinControlMutation = void 0;
 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(예측 자극).
@@ -17,31 +21,64 @@ let TwinControlMutation = class TwinControlMutation {
     /** Command 채널 — 오더 hold/resume/release 등. 커널 dispatch 로 위임, ack{accepted,error} 반환. */
     async dispatchTwinCommand(instanceId, command, context) {
         const domainId = context.state.domain?.id;
-        const inst = index_js_1.TwinEngine.instances[instanceId];
-        if (!inst || inst.domainId !== domainId) {
-            return { accepted: false, error: 'instance not found in your domain' };
-        }
-        /* tenantId 를 호출자 도메인으로 각인(감사·무결성) — 클라 위조 방지. */
-        const ack = inst.runtime.dispatch({ ...command, tenantId: domainId });
-        /* 라이브 구조 변이(resource.add)는 저장 board 에도 반영 — 프로비저닝 편집기·재기동이 추가분을 잃지 않게. */
+        if (!domainId)
+            return { accepted: false, error: 'no-domain', errorCode: 'no-domain' };
+        /*
+         * 라우팅은 엔진이 한다 — 예전에는 여기서 `inst.runtime.dispatch` 를 곧바로 불렀고, `runtime` 이
+         * 시뮬에만 있어서 미러 트윈에서는 이 한 줄이 TypeError 로 터졌다(깔끔한 거절이 아니라 실패).
+         * 권위(모드) × 성격(주석/액추에이션) 판정은 한 곳에만 둔다.
+         */
+        /* 원본을 그대로 감사에 넘긴다 — 무엇이 들어왔는지가 기록의 대상이다(정규화는 감사 모듈이 한다). */
+        const cmdWithOrigin = command;
+        const ack = await index_js_1.TwinEngine.dispatchCommand(domainId, instanceId, command);
+        /* 라이브 구조 변이(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));
         }
-        return { accepted: !!ack?.accepted, error: ack?.error };
+        /*
+         * 감사 기록 — 승인 게이트가 앞을 막고, 이 줄이 뒤를 설명한다. 둘 다 있어야 "사람 손을 거쳤다" 를
+         * 증명할 수 있다. 커널이 거절한 것도 남긴다 — 무엇을 시도했는지가 감사의 절반이다.
+         *
+         * 기록이 실패해도 커맨드 결과는 그대로 돌려준다. 감사가 본업을 막으면 안 되지만, 실패를 삼키지도
+         * 않는다(로그에 남긴다) — 조용히 안 남으면 나중에 "기록이 없다" 와 "일이 없었다" 를 구분 못 한다.
+         */
+        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 };
     }
     /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause/setSpeed). */
     async controlTwinScenario(instanceId, action, context, scenario) {
         const domainId = context.state.domain?.id;
-        const inst = index_js_1.TwinEngine.instances[instanceId];
-        if (!inst || inst.domainId !== domainId)
+        /* 테넌트 격리 — 레지스트리를 직접 색인하지 않는다(키에 도메인이 들어 있다). */
+        if (!index_js_1.TwinEngine.owns(domainId, instanceId))
             return false;
-        const runtime = inst.runtime;
+        const runtime = index_js_1.TwinEngine.runtime(domainId, instanceId);
         /*
          * 자극 주입 가드 — mirror 트윈(외부 실물이 진실)은 커널 시나리오 엔진이 없다(startLive=projector, runtime 없음).
          * what-if 를 여기에 주입하면 현실을 오염시키므로 거부한다(sim-experiment/sim-world 만 자극 가능). silent throw 방지.
          */
         if (!runtime?.scenario)
             return false;
+        /*
+         * **잘못된 선언은 문 앞에서 막는다.** 예전에는 검증 없이 실었고, 다음 tick 에서 `rate.meanPerHour`
+         * 를 읽다 터져 **서버 프로세스가 내려갔다**(클라이언트가 보낸 값 하나로 앱 전체가 죽었다).
+         * 규칙은 커널이 들고 있다(계약의 주인) — 호스트가 따로 만들면 방언이 생긴다.
+         */
+        if (action === 'load') {
+            const v = (0, twin_kernel_1.validateScenario)(scenario);
+            if (v.ok === false) {
+                /* 사유를 로그로 남긴다 — 이 뮤테이션의 반환은 Boolean 계약이라 사유를 실어 보낼 자리가 없다. */
+                console.warn(`[twin] scenario rejected for "${instanceId}": ${v.errorCode} ${JSON.stringify(v.errorParams ?? {})}`);
+                return false;
+            }
+        }
         if (action === 'load' && scenario)
             runtime.scenario.load(scenario);
         else if (action === 'start')
@@ -57,6 +94,7 @@ let TwinControlMutation = class TwinControlMutation {
 };
 exports.TwinControlMutation = TwinControlMutation;
 tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
     (0, type_graphql_1.Mutation)(returns => shell_1.ScalarObject, { description: 'dispatch a twin command (order.hold/resume/release …). Returns {accepted, error?}.' }),
     tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
     tslib_1.__param(1, (0, type_graphql_1.Arg)('command', type => shell_1.ScalarObject)),
@@ -66,6 +104,7 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:returntype", Promise)
 ], TwinControlMutation.prototype, "dispatchTwinCommand", null);
 tslib_1.__decorate([
+    (0, type_graphql_1.Directive)('@privilege(category: "twin", privilege: "mutation", domainOwnerGranted: true, superUserGranted: true)'),
     (0, type_graphql_1.Mutation)(returns => Boolean, { description: 'control twin scenario (load|start|pause|setSpeed)' }),
     tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
     tslib_1.__param(1, (0, type_graphql_1.Arg)('action')),

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 } from 'type-graphql'\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  @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 }> {\n    const domainId = context.state.domain?.id\n    const inst = TwinEngine.instances[instanceId]\n    if (!inst || inst.domainId !== domainId) {\n      return { accepted: false, error: 'instance not found in your domain' }\n    }\n    /* tenantId 를 호출자 도메인으로 각인(감사·무결성) — 클라 위조 방지. */\n    const ack = inst.runtime.dispatch({ ...command, tenantId: domainId })\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    return { accepted: !!ack?.accepted, error: ack?.error }\n  }\n\n  /** Scenario 채널 — 생성기 시나리오 제어(load/start/pause/setSpeed). */\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    const inst = TwinEngine.instances[instanceId]\n    if (!inst || inst.domainId !== domainId) return false\n    const runtime = inst.runtime\n    /*\n     * 자극 주입 가드 — mirror 트윈(외부 실물이 진실)은 커널 시나리오 엔진이 없다(startLive=projector, runtime 없음).\n     * what-if 를 여기에 주입하면 현실을 오염시키므로 거부한다(sim-experiment/sim-world 만 자극 가능). silent throw 방지.\n     */\n    if (!runtime?.scenario) return false\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 ?? {};

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

@@ -1 +1 @@
-{"version":3,"file":"twin-event-keys.js","sourceRoot":"","sources":["../../../server/service/twin-event/twin-event-keys.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 저널 검색 키 추출 — **순수**. 인제스트가 기록할 때 한 번 뽑아 인덱스 가능한 실컬럼으로 승격한다.\n *\n * ── 왜 승격하는가 ───────────────────────────────────────────────────────────\n * 사용자가 저널에서 실제로 찾는 것은 \"이 팔레트의 이력\", \"이 오더가 어디까지 갔나\", \"이 도크에서\n * 무슨 일이 있었나\" 다. 그런데 그 값들은 전부 `payload`(simple-json = TEXT) **안**에 있었다.\n * things-factory 는 5개 DB 드라이버를 지원해야 해서 DB별 JSON 연산자를 쓸 수 없다 —\n * 즉 승격 없이는 **어떤 방법으로도 서버에서 그 조건으로 거를 수 없었다**. 클라이언트가 받아온\n * 몇 천 건 안에서만 찾는 시늉이 최선이었고, 저널이 커질수록 그 시늉은 거짓말에 가까워진다.\n *\n * 그래서 검색 축이 되는 값만 골라 컬럼으로 꺼낸다. payload 는 그대로 둔다(정본은 여전히 payload —\n * 이건 파생 색인이지 새로운 진실이 아니다).\n *\n * ── 왜 여기(순수 모듈)인가 ──────────────────────────────────────────────────\n * 기록 경로가 둘이다(`persistBatch` 라이브 벌크 · `persist` 심 단건). 두 곳에 각자 적으면\n * 반드시 어긋나고, 어긋난 색인은 \"없는 것처럼 보이는 이벤트\" 를 만든다 — 저널에서 가장 나쁜 결함이다.\n */\n\n/** 승격된 검색 키 — 전부 선택적. 뽑히지 않으면 **빈 문자열이 아니라 undefined**(결측≠빈값). */\nexport interface TwinEventKeys {\n  bizStep?: string\n  epc?: string\n  orderId?: string\n  locationId?: string\n  moverId?: string\n}\n\n/*\n * 컬럼 길이 상한. GS1 식별자(EPC URN·GDTI·SGLN)는 규격상 이보다 훨씬 짧다.\n * 넘치는 값이 오면 **조용히 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,\n * 그 사실이 어디에도 안 남으면 아무도 모른다.\n */\nconst MAX_KEY = 255\n\nfunction clip(v: unknown, field: string): string | undefined {\n  if (v === undefined || v === null) return undefined\n  const s = String(v)\n  if (!s) return undefined\n  if (s.length <= MAX_KEY) return s\n  console.warn(\n    `[twin-event-keys] ${field} exceeds ${MAX_KEY} chars and was clipped for indexing — ` +\n      `search on this value may be incomplete. payload keeps the full value. (${s.slice(0, 60)}…)`\n  )\n  return s.slice(0, MAX_KEY)\n}\n\n/** CBV bizStep URN 의 끝마디. 없으면 이벤트 타입에서 유추(`epcis.` 접두 제거). */\nexport function bizStepOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  const tail = String(d.bizStep ?? '').split(':').pop()\n  return tail || String(envelope?.eventType ?? '').replace('epcis.', '') || undefined\n}\n\n/**\n * 품목 식별자 — **전체 값**을 저장한다(끝마디만 저장하지 않는다).\n *\n * 표시용 축약은 화면이 하고, 색인은 원본을 갖는다. `search` 는 부분일치(contains)라\n * 전체를 저장해 두면 끝마디(\"402.2\")로도 URN 전체로도 찾힌다. 반대로 끝마디만 저장하면\n * URN 으로 찾는 경로가 사라진다.\n */\nexport function epcOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.epcList?.[0] ?? d.parentID ?? d.quantityList?.[0]?.epcClass ?? undefined\n}\n\n/** 거래 식별자(PO/SO) — EPCIS bizTransactionList 우선, 운영 델타는 `order`. */\nexport function orderOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.bizTransactionList?.[0]?.bizTransaction ?? d.order ?? undefined\n}\n\n/**\n * 위치 — EPCIS 는 읽은 지점(readPoint) 우선, 없으면 업무 위치(bizLocation).\n * 운영 델타(무버 이동 등)는 그 둘이 없고 평범한 `location` 을 쓴다 — 빠뜨리면 설비가 어디서\n * 무엇을 했는지가 위치 축에서 통째로 사라진다.\n */\nexport function locationOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.readPoint?.id ?? d.bizLocation?.id ?? d.location ?? undefined\n}\n\n/**\n * 설비·무버 — 운영 델타(equipment.status·task.status)가 대상을 가리키는 축.\n *\n * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 \"이 지게차가 오늘 무엇을 했나\" 를\n * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 훑는 수밖에 없다.\n */\nexport function equipmentIdOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.moverId ?? undefined\n}\n\n/** 한 이벤트에서 승격 키 전부 — 기록 경로가 이 함수 하나만 부른다. */\nexport function twinEventKeys(envelope: any): TwinEventKeys {\n  return {\n    bizStep: clip(bizStepOf(envelope), 'bizStep'),\n    epc: clip(epcOf(envelope), 'epc'),\n    orderId: clip(orderOf(envelope), 'orderId'),\n    locationId: clip(locationOf(envelope), 'locationId'),\n    moverId: clip(equipmentIdOf(envelope), 'moverId')\n  }\n}\n"]}
+{"version":3,"file":"twin-event-keys.js","sourceRoot":"","sources":["../../../server/service/twin-event/twin-event-keys.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 저널 검색 키 추출 — **순수**. 인제스트가 기록할 때 한 번 뽑아 인덱스 가능한 실컬럼으로 승격한다.\n *\n * ── 왜 승격하는가 ───────────────────────────────────────────────────────────\n * 사용자가 저널에서 실제로 찾는 것은 \"이 팔레트의 이력\", \"이 오더가 어디까지 갔나\", \"이 도크에서\n * 무슨 일이 있었나\" 다. 그런데 그 값들은 전부 `payload`(simple-json = TEXT) **안**에 있었다.\n * things-factory 는 5개 DB 드라이버를 지원해야 해서 DB별 JSON 연산자를 쓸 수 없다 —\n * 즉 승격 없이는 **어떤 방법으로도 서버에서 그 조건으로 거를 수 없었다**. 클라이언트가 받아온\n * 몇 천 건 안에서만 찾는 시늉이 최선이었고, 저널이 커질수록 그 시늉은 거짓말에 가까워진다.\n *\n * 그래서 검색 축이 되는 값만 골라 컬럼으로 꺼낸다. payload 는 그대로 둔다(정본은 여전히 payload —\n * 이건 파생 색인이지 새로운 진실이 아니다).\n *\n * ── 왜 여기(순수 모듈)인가 ──────────────────────────────────────────────────\n * 기록 경로가 둘이다(`persistBatch` 라이브 벌크 · `persist` 심 단건). 두 곳에 각자 적으면\n * 반드시 어긋나고, 어긋난 색인은 \"없는 것처럼 보이는 이벤트\" 를 만든다 — 저널에서 가장 나쁜 결함이다.\n */\n\n/** 승격된 검색 키 — 전부 선택적. 뽑히지 않으면 **빈 문자열이 아니라 undefined**(결측≠빈값). */\nexport interface TwinEventKeys {\n  bizStep?: string\n  epc?: string\n  orderId?: string\n  locationId?: string\n  moverId?: string\n}\n\n/*\n * 컬럼 길이 상한. GS1 식별자(EPC URN·GDTI·SGLN)는 규격상 이보다 훨씬 짧다.\n * 넘치는 값이 오면 **조용히 자르지 않고** 경고를 남긴다 — 색인이 원본과 다르면 검색 결과가 거짓이 되는데,\n * 그 사실이 어디에도 안 남으면 아무도 모른다.\n */\nconst MAX_KEY = 255\n\nfunction clip(v: unknown, field: string): string | undefined {\n  if (v === undefined || v === null) return undefined\n  const s = String(v)\n  if (!s) return undefined\n  if (s.length <= MAX_KEY) return s\n  console.warn(\n    `[twin-event-keys] ${field} exceeds ${MAX_KEY} chars and was clipped for indexing — ` +\n      `search on this value may be incomplete. payload keeps the full value. (${s.slice(0, 60)}…)`\n  )\n  return s.slice(0, MAX_KEY)\n}\n\n/** CBV bizStep URN 의 끝마디. 없으면 이벤트 타입에서 유추(`epcis.` 접두 제거). */\nexport function bizStepOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  const tail = String(d.bizStep ?? '').split(':').pop()\n  return tail || String(envelope?.eventType ?? '').replace('epcis.', '') || undefined\n}\n\n/**\n * 품목 식별자 — **전체 값**을 저장한다(끝마디만 저장하지 않는다).\n *\n * 표시용 축약은 화면이 하고, 색인은 원본을 갖는다. `search` 는 부분일치(contains)라\n * 전체를 저장해 두면 끝마디(\"402.2\")로도 URN 전체로도 찾힌다. 반대로 끝마디만 저장하면\n * URN 으로 찾는 경로가 사라진다.\n */\nexport function epcOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.epcList?.[0] ?? d.parentID ?? d.quantityList?.[0]?.epcClass ?? undefined\n}\n\n/** 거래 식별자(PO/SO) — EPCIS bizTransactionList 우선, 운영 델타는 `order`. */\nexport function orderOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.bizTransactionList?.[0]?.bizTransaction ?? d.order ?? undefined\n}\n\n/**\n * 위치 — EPCIS 는 읽은 지점(readPoint) 우선, 없으면 업무 위치(bizLocation).\n * 운영 델타(무버 이동 등)는 그 둘이 없고 평범한 `location` 을 쓴다 — 빠뜨리면 설비가 어디서\n * 무엇을 했는지가 위치 축에서 통째로 사라진다.\n */\nexport function locationOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.readPoint?.id ?? d.bizLocation?.id ?? d.location ?? undefined\n}\n\n/**\n * 설비·무버 — 운영 델타(equipment.status·task.status)가 대상을 가리키는 축.\n *\n * EPCIS 어휘가 아니라서 다른 축 어디에도 안 잡힌다. 이게 없으면 \"이 지게차가 오늘 무엇을 했나\" 를\n * 서버에서 물을 방법이 없어, 화면이 저널을 통째로 받아 전수 조회하는 수밖에 없다.\n */\nexport function equipmentIdOf(envelope: any): string | undefined {\n  const d = envelope?.data ?? envelope ?? {}\n  return d.moverId ?? undefined\n}\n\n/** 한 이벤트에서 승격 키 전부 — 기록 경로가 이 함수 하나만 부른다. */\nexport function twinEventKeys(envelope: any): TwinEventKeys {\n  return {\n    bizStep: clip(bizStepOf(envelope), 'bizStep'),\n    epc: clip(epcOf(envelope), 'epc'),\n    orderId: clip(orderOf(envelope), 'orderId'),\n    locationId: clip(locationOf(envelope), 'locationId'),\n    moverId: clip(equipmentIdOf(envelope), 'moverId')\n  }\n}\n"]}

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

@@ -3,22 +3,31 @@ export declare class TwinEvent {
     readonly id: string;
     domain?: Domain;
     domainId?: string;
-    instanceId?: string;
-    tenantId?: string;
-    eventType?: string;
+    instanceId: string;
+    eventType: string;
     revision?: number;
     /**
      * 이 사실이 **어느 공장에서** 일어났나 — `TwinStructure.rev`.
      *
      * 이것이 없던 시절에는 구조가 바뀌면 저널을 통째로 지우는 것이 유일한 길이었다(안 지우면 옛
      * 이벤트를 새 공장에 대고 접어 이력이 거짓말을 한다). 이 한 칸이 셋째 길을 연다 — 재생이
-     * 구조가 바뀌는 지점에서 갈아탄 뒤 이어 접는다.
+     * 구조가 바뀌는 지점에서 전환한 뒤 이어 접는다.
      *
      * **비어 있을 수 있다**: 컬럼이 생기기 전에 쓰인 행이다. 그 행들은 **가장 오래된 리비전**에
      * 속한다(0 을 채워 넣지 않는다 — 0 은 "모름" 이 아니라 유효한 번호처럼 보인다).
      */
     structureRev?: number;
-    eventTime?: string;
+    eventTime?: Date;
+    /**
+     * 이 사실을 일으킨 **지시** — 커널이 커맨드에서 이어 준 상관값(기본은 commandId).
+     *
+     * 이것이 감사 기록(TwinAuditEvent.commandId)과 저널을 잇는 유일한 다리다. 없으면 승인 기록은
+     * "사람이 허락했다" 까지이고, 그 뒤 공장이 실제로 어떻게 움직였는지와 이어지지 않는다.
+     *
+     * **대부분의 행은 비어 있다** — 커맨드가 아니라 시뮬 시간이 낳은 사실이기 때문이다. 그것이 정상이고,
+     * 비어 있다고 "덜 채워진 옛 행" 으로 보면 안 된다(같은 오해를 bizStep 에서 이미 한 번 했다).
+     */
+    correlationId?: string;
     bizStep?: string;
     epc?: string;
     orderId?: string;

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

@@ -25,7 +25,7 @@ const shell_1 = require("@things-factory/shell");
  *
  * bizStep·locationId·moverId 는 컬럼만 두고 인덱스는 두지 않는다 — 한 트윈 안에서 카디널리티가
  * 낮아(업무단계 몇 개, 위치 수백, 설비 수십) (domain,instanceId) 로 이미 좁혀진 뒤의 잔여 필터로
- * 충분하고, 뜨거운 표에 인덱스를 더 얹을 값어치가 없다. 저널 하나가 아주 커져서 이 축들의 조회가
+ * 충분하고, 뜨거운 표에 인덱스를 더 얹을 가치가 없다. 저널 하나가 아주 커져서 이 축들의 조회가
  * 느려지면 그때 측정을 근거로 인덱스를 추가할 일이지, 지레 얹어 쓰기를 무겁게 할 일은 아니다.
  */
 let TwinEvent = class TwinEvent {
@@ -46,18 +46,13 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:type", String)
 ], TwinEvent.prototype, "domainId", void 0);
 tslib_1.__decorate([
-    (0, typeorm_1.Column)({ nullable: true }),
-    (0, type_graphql_1.Field)({ nullable: true, description: 'Twin runtime instance id that emitted the event.' }),
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Twin runtime instance id that emitted the event.' }),
     tslib_1.__metadata("design:type", String)
 ], TwinEvent.prototype, "instanceId", void 0);
 tslib_1.__decorate([
-    (0, typeorm_1.Column)({ nullable: true }),
-    (0, type_graphql_1.Field)({ nullable: true, description: 'Kernel tenant id carried on the canonical envelope.' }),
-    tslib_1.__metadata("design:type", String)
-], TwinEvent.prototype, "tenantId", void 0);
-tslib_1.__decorate([
-    (0, typeorm_1.Column)({ nullable: true }),
-    (0, type_graphql_1.Field)({ nullable: true, description: 'Event type: epcis.* | task.status | equipment.status | order.status.' }),
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Event type: epcis.* | task.status | equipment.status | order.status.' }),
     tslib_1.__metadata("design:type", String)
 ], TwinEvent.prototype, "eventType", void 0);
 tslib_1.__decorate([
@@ -71,10 +66,44 @@ tslib_1.__decorate([
     tslib_1.__metadata("design:type", Number)
 ], TwinEvent.prototype, "structureRev", void 0);
 tslib_1.__decorate([
-    (0, typeorm_1.Column)({ nullable: true }),
-    (0, type_graphql_1.Field)({ nullable: true, description: 'Simulation event time (ISO 8601).' }),
-    tslib_1.__metadata("design:type", String)
+    (0, typeorm_1.Column)({ type: 'datetime', nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Time at which the fact happened on the twin clock.' }),
+    tslib_1.__metadata("design:type", Date
+    /*
+     * ── 승격된 검색 축 ────────────────────────────────────────────────────────
+     * payload 안에 있던 값을 인제스트 시점에 꺼내 실컬럼으로 둔다(`twin-event-keys.ts` 가 단독 소유).
+     * payload 가 여전히 정본이고 이것들은 **파생 색인**이다 — 새로운 진실이 아니라 찾을 수 있게 하는 장치.
+     * simple-json(TEXT) 안의 값은 5개 DB 드라이버 공통으로 거를 방법이 없어서(멀티DB 호환 규칙상
+     * DB별 JSON 연산자 금지) 승격 외의 선택지가 없다.
+     * 길이 상한 255 는 GS1 식별자 규격 대비 충분하며, 넘치는 값은 조용히 잘리지 않고 경고를 남긴다.
+     *
+     * ── 축을 새로 추가할 때 ──────────────────────────────────────────────────
+     * 새 승격 컬럼을 만들면 **이미 쌓인 행은 비어 있다.** 그 행들은 새 축으로 검색되지 않고,
+     * 사용자에게는 "과거가 없는 것" 으로 보인다(조용히 빠진 데이터).
+     *
+     * 예전에는 기동 훅이 매번 테이블을 살펴 채웠다. 그건 두 가지로 틀렸다 — 저널이 커질수록 부팅이
+     * 느려지고, "bizStep 이 비었으면 옛 행" 이라는 전제를 코드에 고정해 그 전제가 깨지는 순간
+     * (감사 행처럼 업무 단계가 없는 행) 매 부팅마다 헛돌았다. 그래서 걷어냈다(git: backfill-keys.ts).
+     *
+     * 채우는 일은 **마이그레이션 한 번**이 맞다(`yarn migration`). 그 컬럼에 맞는 것을 그때 쓴다 —
+     * 범용 스캐너를 되살리지 말 것. 개발 데이타라면 그냥 버리는 것도 답이다.
+     */
+    /**
+     * 이 사실을 일으킨 **지시** — 커널이 커맨드에서 이어 준 상관값(기본은 commandId).
+     *
+     * 이것이 감사 기록(TwinAuditEvent.commandId)과 저널을 잇는 유일한 다리다. 없으면 승인 기록은
+     * "사람이 허락했다" 까지이고, 그 뒤 공장이 실제로 어떻게 움직였는지와 이어지지 않는다.
+     *
+     * **대부분의 행은 비어 있다** — 커맨드가 아니라 시뮬 시간이 낳은 사실이기 때문이다. 그것이 정상이고,
+     * 비어 있다고 "덜 채워진 옛 행" 으로 보면 안 된다(같은 오해를 bizStep 에서 이미 한 번 했다).
+     */
+    )
 ], TwinEvent.prototype, "eventTime", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ length: 255, nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Id of the command that caused this fact (kernel correlation id; defaults to the commandId). Empty for facts that simulation time produced rather than a command.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinEvent.prototype, "correlationId", void 0);
 tslib_1.__decorate([
     (0, typeorm_1.Column)({ length: 255, nullable: true }),
     (0, type_graphql_1.Field)({ nullable: true, description: 'Business step (CBV bizStep tail), promoted from the payload for indexed filtering.' }),
@@ -116,7 +145,10 @@ exports.TwinEvent = TwinEvent = tslib_1.__decorate([
     (0, typeorm_1.Index)('ix_twin_event_1', (e) => [e.domain, e.instanceId, e.eventTime], { unique: false }),
     (0, typeorm_1.Index)('ix_twin_event_2', (e) => [e.domain, e.instanceId, e.eventType, e.revision], { unique: false }),
     (0, typeorm_1.Index)('ix_twin_event_3', (e) => [e.domain, e.instanceId, e.epc], { unique: false }),
-    (0, typeorm_1.Index)('ix_twin_event_4', (e) => [e.domain, e.instanceId, e.orderId], { unique: false }),
+    (0, typeorm_1.Index)('ix_twin_event_4', (e) => [e.domain, e.instanceId, e.orderId], { unique: false })
+    /* ix_5 — "이 지시가 무엇을 일으켰나". 감사 기록의 commandId 로 저널을 다시 계산하는 축. */
+    ,
+    (0, typeorm_1.Index)('ix_twin_event_5', (e) => [e.domain, e.correlationId], { unique: false }),
     (0, type_graphql_1.ObjectType)({ description: 'Append-only twin event journal record (EPCIS event or operational delta).' })
 ], TwinEvent);
 //# sourceMappingURL=twin-event.js.map