@things-factory/headless-twin 10.0.9 → 10.0.10

package/dist-server/service/twin-model/twin-equipment.d.ts

@@ -0,0 +1,64 @@
+import { Domain } from '@things-factory/shell';
+import { TwinInstance } from '../twin-instance/twin-instance.js';
+import { TwinLocation } from './twin-location.js';
+export declare class TwinEquipment {
+    readonly id: string;
+    domain?: Domain;
+    domainId?: string;
+    instance?: TwinInstance;
+    instanceRowId?: string;
+    /** 커널 계약의 `TwinModelDef.equipment[].id` 그대로. */
+    equipmentId: string;
+    /**
+     * **사람이 부르는 이름** — 프레임워크 엔티티 규약의 `name`/`description`.
+     *
+     * ── 왜 이것이 빠져 있었고, 무엇이 망가졌나 ────────────────────────────────────
+     * 투영이 마스터의 `name` 을 버리고 있었다. 그래서 행에는 id 만 남고, 화면은 이름을 만들 재료가
+     * 없어 `cut-station` 을 그대로 찍었다 — 그 결함이 목록·표·관계 그림마다 따로 나타나서 표면을
+     * 하나씩 고치게 만들었다. 표면의 문제가 아니라 **행에 이름이 없던 문제**다.
+     *
+     * 원본이 이름을 말하지 않으면 비운다(id 를 이름으로 베끼지 않는다 — 그러면 "이름이 있다" 는
+     * 거짓이 되고, 화면이 이름 없음을 알아볼 수 없게 된다).
+     */
+    name?: string;
+    description?: string;
+    /** 커널 카탈로그의 설비 종류 키(`forklift`·`welder`…). FK 아님 — 카탈로그는 커널 SSOT. */
+    kind: string;
+    /**
+     * 자원 속성 — **ISA-95 `Property`**(값·데이터형·단위·하위 속성).
+     *
+     * 모델에는 있는데 행에 자리가 없어 투영이 흘리고 있었다. 그러면 조회 화면은 "원본이 말한 값" 이라
+     * 적고도 속성을 보이지 못한다 — 이름이 같은 식으로 사라졌던 것과 같은 부류다(2026-08-11).
+     *
+     * 소비처가 실제로 읽는 사실이다: 주행 추정기가 `speed` 로 이동 시간을 만든다. 단위가 값 옆에 붙어
+     * 있어야 뜻이 서므로 **모양 그대로** 담는다(문자열 값 + `uom` + `dataType`).
+     */
+    properties?: any;
+    /**
+     * 이 설비의 적격을 검증한 **시험 명세들** — 표준 `TestSpecificationID`(`maxOccurs="unbounded"`).
+     *
+     * 참조만 담는다(대상은 `testSpecifications` 축). 속성과 **같은 부류의 결손**이었다: 모델에는 있는데
+     * 행에 자리가 없어 투영이 흘렸고, 그래서 명세 쪽에서 "누가 나를 가리키나" 를 물으면 설비가 빠졌다.
+     */
+    testSpecificationIds?: string[];
+    /**
+     * 그 시험들의 **결과** — 자격이 성립하는지는 이것이 말한다.
+     *
+     * 참조만 있으면 "무엇으로 검증한다" 까지다. 오늘 이 저장소에서 네 번 나온 결손과 같은 부류이므로
+     * 행에 자리를 함께 만든다 — 모델에는 있는데 행에 없으면 화면이 조용히 잃는다.
+     */
+    testResults?: any;
+    /**
+     * 기준 자리 — **실제 FK**. 예전에는 `homeLocation` 문자열이라 끊어진 참조를 화면이 경고했고
+     * (`brokenHomeRefs`), 다른 경로로 들어오는 데이터는 아무도 안 봤다. 이제 DB 가 막는다.
+     */
+    homeLocation?: TwinLocation;
+    homeLocationRowId?: string;
+    mtbfMs?: number;
+    mttrMs?: number;
+    gs1Id?: string;
+    sourceRef: string;
+    ingestedAt: Date;
+    createdAt?: Date;
+    updatedAt?: Date;
+}

package/dist-server/service/twin-model/twin-equipment.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinEquipment = 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 twin_instance_js_1 = require("../twin-instance/twin-instance.js");
+const twin_location_js_1 = require("./twin-location.js");
+/*
+ * TwinEquipment — 이 트윈이 반영하는 **설비**. ISA-95 `Equipment` / ISO 55000 `Asset` / EPCIS `GIAI`.
+ *
+ * 자리와 같은 규율을 따른다(`twin-location.ts` 머리말) — 이것도 **원본에서 온 캐시**이고,
+ * `sourceRef`·`ingestedAt` 이 필수이며, 쓰기 경로는 인제스트 하나다.
+ *
+ * ── 테이블 이름을 명시한다 ──────────────────────────────────────────────────
+ * `equipment` 는 영어에서 **불가산**이라 자동 복수화가 다른 표들과 규칙이 어긋난다
+ * (`twin_locations` 인데 `twin_equipment`). 조용한 비일관은 나중에 "왜 이것만 다르지" 를
+ * 만들므로 이름을 고정한다(ADR-0032-I).
+ */
+let TwinEquipment = class TwinEquipment {
+};
+exports.TwinEquipment = TwinEquipment;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryGeneratedColumn)('uuid'),
+    (0, type_graphql_1.Field)(type => type_graphql_1.ID),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.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)
+], TwinEquipment.prototype, "domain", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((e) => e.domain),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.prototype, "domainId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => twin_instance_js_1.TwinInstance, { onDelete: 'CASCADE' }),
+    (0, type_graphql_1.Field)(type => twin_instance_js_1.TwinInstance, { nullable: true, description: 'Owning twin instance.' }),
+    tslib_1.__metadata("design:type", twin_instance_js_1.TwinInstance)
+], TwinEquipment.prototype, "instance", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((e) => e.instance),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.prototype, "instanceRowId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Equipment id as declared by the source (kernel TwinModelDef.equipment[].id).' }),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.prototype, "equipmentId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Human name as declared by the source. Empty when the source does not name it (never copied from the id).' }),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.prototype, "name", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Longer description when the source provides one.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.prototype, "description", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Equipment kind key from the kernel catalog (not an FK — the catalog is the kernel SSOT).' }),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.prototype, "kind", 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: 'Resource properties as declared by the source (ISA-95 Property: value + dataType + unit of measure, optional children).' }),
+    tslib_1.__metadata("design:type", Object)
+], TwinEquipment.prototype, "properties", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'simple-json', nullable: true }),
+    (0, type_graphql_1.Field)(type => [String], { nullable: true, description: 'Test specifications that verified this equipment (ISA-95 TestSpecificationID, unbounded). References only — the specifications themselves live on the testSpecifications axis.' }),
+    tslib_1.__metadata("design:type", Array)
+], TwinEquipment.prototype, "testSpecificationIds", 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: 'Results of those tests (pass/fail with dates). Declared by the source — the twin does not produce them.' }),
+    tslib_1.__metadata("design:type", Object)
+], TwinEquipment.prototype, "testResults", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => twin_location_js_1.TwinLocation, { nullable: true, onDelete: 'SET NULL' }),
+    (0, type_graphql_1.Field)(type => twin_location_js_1.TwinLocation, { nullable: true, description: 'Home location this equipment belongs to.' }),
+    tslib_1.__metadata("design:type", twin_location_js_1.TwinLocation)
+], TwinEquipment.prototype, "homeLocation", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((e) => e.homeLocation),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.prototype, "homeLocationRowId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { nullable: true, description: 'Declared mean time between failures in ms. Absent = no failure model.' }),
+    tslib_1.__metadata("design:type", Number)
+], TwinEquipment.prototype, "mtbfMs", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { nullable: true, description: 'Declared mean time to repair in ms.' }),
+    tslib_1.__metadata("design:type", Number)
+], TwinEquipment.prototype, "mttrMs", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'GS1 identifier supplied by the source (e.g. GIAI).' }),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.prototype, "gs1Id", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)(),
+    (0, type_graphql_1.Field)({ description: 'Which reference (source system) this row came from. Required.' }),
+    tslib_1.__metadata("design:type", String)
+], TwinEquipment.prototype, "sourceRef", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'datetime' }),
+    (0, type_graphql_1.Field)({ description: 'When this row was projected from the source.' }),
+    tslib_1.__metadata("design:type", Date)
+], TwinEquipment.prototype, "ingestedAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)(),
+    (0, type_graphql_1.Field)({ nullable: true }),
+    tslib_1.__metadata("design:type", Date)
+], TwinEquipment.prototype, "createdAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.UpdateDateColumn)(),
+    (0, type_graphql_1.Field)({ nullable: true }),
+    tslib_1.__metadata("design:type", Date)
+], TwinEquipment.prototype, "updatedAt", void 0);
+exports.TwinEquipment = TwinEquipment = tslib_1.__decorate([
+    (0, typeorm_1.Entity)({ name: 'twin_equipment' }),
+    (0, typeorm_1.Index)('ix_twin_equipment_0', (e) => [e.domain, e.instance, e.equipmentId], { unique: true })
+    /* 종류로 좁혀 보기 — 공정이 `resourceType` 으로 종류를 가리키므로 잦은 질의다. */
+    ,
+    (0, typeorm_1.Index)('ix_twin_equipment_1', (e) => [e.domain, e.instance, e.kind]),
+    (0, type_graphql_1.ObjectType)({ description: 'Equipment reflected into the twin (ISA-95 Equipment / ISO 55000 Asset). Projected from the source; never authored here.' })
+], TwinEquipment);
+//# sourceMappingURL=twin-equipment.js.map

package/dist-server/service/twin-model/twin-equipment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-equipment.js","sourceRoot":"","sources":["../../../server/service/twin-model/twin-equipment.ts"],"names":[],"mappings":"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","sourcesContent":["import { CreateDateColumn, Entity, Index, Column, RelationId, ManyToOne, PrimaryGeneratedColumn, UpdateDateColumn } from 'typeorm'\nimport { ObjectType, Field, ID, Int } from 'type-graphql'\n\nimport { Domain, ScalarObject } from '@things-factory/shell'\n\nimport { TwinInstance } from '../twin-instance/twin-instance.js'\nimport { TwinLocation } from './twin-location.js'\n\n/*\n * TwinEquipment — 이 트윈이 반영하는 **설비**. ISA-95 `Equipment` / ISO 55000 `Asset` / EPCIS `GIAI`.\n *\n * 자리와 같은 규율을 따른다(`twin-location.ts` 머리말) — 이것도 **원본에서 온 캐시**이고,\n * `sourceRef`·`ingestedAt` 이 필수이며, 쓰기 경로는 인제스트 하나다.\n *\n * ── 테이블 이름을 명시한다 ──────────────────────────────────────────────────\n * `equipment` 는 영어에서 **불가산**이라 자동 복수화가 다른 표들과 규칙이 어긋난다\n * (`twin_locations` 인데 `twin_equipment`). 조용한 비일관은 나중에 \"왜 이것만 다르지\" 를\n * 만들므로 이름을 고정한다(ADR-0032-I).\n */\n@Entity({ name: 'twin_equipment' })\n@Index('ix_twin_equipment_0', (e: TwinEquipment) => [e.domain, e.instance, e.equipmentId], { unique: true })\n/* 종류로 좁혀 보기 — 공정이 `resourceType` 으로 종류를 가리키므로 잦은 질의다. */\n@Index('ix_twin_equipment_1', (e: TwinEquipment) => [e.domain, e.instance, e.kind])\n@ObjectType({ description: 'Equipment reflected into the twin (ISA-95 Equipment / ISO 55000 Asset). Projected from the source; never authored here.' })\nexport class TwinEquipment {\n  @PrimaryGeneratedColumn('uuid')\n  @Field(type => ID)\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: TwinEquipment) => e.domain)\n  domainId?: string\n\n  @ManyToOne(type => TwinInstance, { onDelete: 'CASCADE' })\n  @Field(type => TwinInstance, { nullable: true, description: 'Owning twin instance.' })\n  instance?: TwinInstance\n\n  @RelationId((e: TwinEquipment) => e.instance)\n  instanceRowId?: string\n\n  /** 커널 계약의 `TwinModelDef.equipment[].id` 그대로. */\n  @Column()\n  @Field({ description: 'Equipment id as declared by the source (kernel TwinModelDef.equipment[].id).' })\n  equipmentId: string\n\n  /**\n   * **사람이 부르는 이름** — 프레임워크 엔티티 규약의 `name`/`description`.\n   *\n   * ── 왜 이것이 빠져 있었고, 무엇이 망가졌나 ────────────────────────────────────\n   * 투영이 마스터의 `name` 을 버리고 있었다. 그래서 행에는 id 만 남고, 화면은 이름을 만들 재료가\n   * 없어 `cut-station` 을 그대로 찍었다 — 그 결함이 목록·표·관계 그림마다 따로 나타나서 표면을\n   * 하나씩 고치게 만들었다. 표면의 문제가 아니라 **행에 이름이 없던 문제**다.\n   *\n   * 원본이 이름을 말하지 않으면 비운다(id 를 이름으로 베끼지 않는다 — 그러면 \"이름이 있다\" 는\n   * 거짓이 되고, 화면이 이름 없음을 알아볼 수 없게 된다).\n   */\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Human name as declared by the source. Empty when the source does not name it (never copied from the id).' })\n  name?: string\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'Longer description when the source provides one.' })\n  description?: string\n\n  /** 커널 카탈로그의 설비 종류 키(`forklift`·`welder`…). FK 아님 — 카탈로그는 커널 SSOT. */\n  @Column()\n  @Field({ description: 'Equipment kind key from the kernel catalog (not an FK — the catalog is the kernel SSOT).' })\n  kind: string\n\n  /**\n   * 자원 속성 — **ISA-95 `Property`**(값·데이터형·단위·하위 속성).\n   *\n   * 모델에는 있는데 행에 자리가 없어 투영이 흘리고 있었다. 그러면 조회 화면은 \"원본이 말한 값\" 이라\n   * 적고도 속성을 보이지 못한다 — 이름이 같은 식으로 사라졌던 것과 같은 부류다(2026-08-11).\n   *\n   * 소비처가 실제로 읽는 사실이다: 주행 추정기가 `speed` 로 이동 시간을 만든다. 단위가 값 옆에 붙어\n   * 있어야 뜻이 서므로 **모양 그대로** 담는다(문자열 값 + `uom` + `dataType`).\n   */\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, { nullable: true, description: 'Resource properties as declared by the source (ISA-95 Property: value + dataType + unit of measure, optional children).' })\n  properties?: any\n\n  /**\n   * 이 설비의 적격을 검증한 **시험 명세들** — 표준 `TestSpecificationID`(`maxOccurs=\"unbounded\"`).\n   *\n   * 참조만 담는다(대상은 `testSpecifications` 축). 속성과 **같은 부류의 결손**이었다: 모델에는 있는데\n   * 행에 자리가 없어 투영이 흘렸고, 그래서 명세 쪽에서 \"누가 나를 가리키나\" 를 물으면 설비가 빠졌다.\n   */\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => [String], { nullable: true, description: 'Test specifications that verified this equipment (ISA-95 TestSpecificationID, unbounded). References only — the specifications themselves live on the testSpecifications axis.' })\n  testSpecificationIds?: string[]\n\n  /**\n   * 그 시험들의 **결과** — 자격이 성립하는지는 이것이 말한다.\n   *\n   * 참조만 있으면 \"무엇으로 검증한다\" 까지다. 오늘 이 저장소에서 네 번 나온 결손과 같은 부류이므로\n   * 행에 자리를 함께 만든다 — 모델에는 있는데 행에 없으면 화면이 조용히 잃는다.\n   */\n  @Column({ type: 'simple-json', nullable: true })\n  @Field(type => ScalarObject, { nullable: true, description: 'Results of those tests (pass/fail with dates). Declared by the source — the twin does not produce them.' })\n  testResults?: any\n\n  /**\n   * 기준 자리 — **실제 FK**. 예전에는 `homeLocation` 문자열이라 끊어진 참조를 화면이 경고했고\n   * (`brokenHomeRefs`), 다른 경로로 들어오는 데이터는 아무도 안 봤다. 이제 DB 가 막는다.\n   */\n  @ManyToOne(type => TwinLocation, { nullable: true, onDelete: 'SET NULL' })\n  @Field(type => TwinLocation, { nullable: true, description: 'Home location this equipment belongs to.' })\n  homeLocation?: TwinLocation\n\n  @RelationId((e: TwinEquipment) => e.homeLocation)\n  homeLocationRowId?: string\n\n  /*\n   * 고장 모델 — 원본이 선언할 때만 있다. 없으면 고장 없는 설비로 동작한다(커널 계약).\n   * **관측(가동률)은 여기 두지 않는다** — 그건 트윈이 저널에서 만든 것이라 성질이 다르고,\n   * 이 표는 원본에서 재생성 가능해야 한다(ADR-0032-D).\n   */\n  @Column({ type: 'int', nullable: true })\n  @Field(type => Int, { nullable: true, description: 'Declared mean time between failures in ms. Absent = no failure model.' })\n  mtbfMs?: number\n\n  @Column({ type: 'int', nullable: true })\n  @Field(type => Int, { nullable: true, description: 'Declared mean time to repair in ms.' })\n  mttrMs?: number\n\n  @Column({ nullable: true })\n  @Field({ nullable: true, description: 'GS1 identifier supplied by the source (e.g. GIAI).' })\n  gs1Id?: string\n\n  /* ── 캐시라는 사실을 구조로 (ADR-0032-D) ── */\n  @Column()\n  @Field({ description: 'Which reference (source system) this row came from. Required.' })\n  sourceRef: string\n\n  @Column({ type: 'datetime' })\n  @Field({ description: 'When this row was projected from the source.' })\n  ingestedAt: Date\n\n  @CreateDateColumn()\n  @Field({ nullable: true })\n  createdAt?: Date\n\n  @UpdateDateColumn()\n  @Field({ nullable: true })\n  updatedAt?: Date\n}\n"]}

package/dist-server/service/twin-model/twin-lineage-query.d.ts

@@ -0,0 +1,3 @@
+export declare class TwinLineageQuery {
+    twinItemLineage(instanceId: string, epc: string, context: ResolverContext, maxDepth?: number, window?: number): Promise<any | null>;
+}

package/dist-server/service/twin-model/twin-lineage-query.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinLineageQuery = void 0;
+const tslib_1 = require("tslib");
+const type_graphql_1 = require("type-graphql");
+const shell_1 = require("@things-factory/shell");
+const twin_instance_js_1 = require("../twin-instance/twin-instance.js");
+const twin_event_js_1 = require("../twin-event/twin-event.js");
+/*
+ * 계보 — **이 개체는 무엇에서 나왔나**, 그리고 **설계대로 만들어졌나.**
+ *
+ * ── 구성과 계보는 주어가 다르다 ────────────────────────────────────────────────
+ * 구성(BOM)의 주어는 품목 **정의**다 — "트레일러는 프레임 1개로 만든다"(선언).
+ * 계보의 주어는 품목 **개체**다 — "이 트레일러는 저 프레임 로트에서 나왔다"(관측).
+ * 둘은 같은 모양이라 겹쳐 볼 수 있고, **그 차이가 곧 진단**이다: "설계는 1개인데 이건 2개를 먹었다".
+ * 트윈이 아니면 못 하는 답이고, 이 질의가 그 답의 재료다.
+ *
+ * ── 어디서 읽나 ────────────────────────────────────────────────────────────────
+ * 계보는 상태가 아니라 **저널**에 있다(EPCIS `TransformationEvent` 의 입력·산출 목록). 상태는
+ * 지금 무엇이 있는지만 알고, 없어진 원자재가 무엇이었는지는 이벤트만 안다.
+ *
+ * ── 규모 ───────────────────────────────────────────────────────────────────────
+ * 입력 목록은 **컬럼이 아니라 봉투 안**에 있어서 인덱스로 좁힐 수 없다. 그래서 변환 이벤트만
+ * 창으로 끊어 읽고, **끊었으면 끊었다고 말한다.** 그 사실을 감추면 "이 개체는 원자재가 없다" 로
+ * 읽히고, 계보에서 그 오해는 리콜 범위를 좁게 잡는 결과로 이어진다.
+ */
+/** GS1 SGTIN 의 **품목 참조** — 개체(serial)를 떼고 품목만 남긴다(`…sgtin:0614141.077101.42` → `077101`). */
+function itemRefOf(epc) {
+    const m = /sgtin:[^.]+\.([^.]+)\./.exec(epc);
+    return m ? m[1] : null;
+}
+let TwinLineageQuery = class TwinLineageQuery {
+    async twinItemLineage(instanceId, epc, context, maxDepth, window) {
+        const domainId = context.state.domain.id;
+        const inst = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } });
+        if (!inst)
+            return null;
+        const depthCap = Math.min(Math.max(maxDepth ?? 6, 1), 12);
+        const windowCap = Math.min(Math.max(window ?? 5000, 1), 50000);
+        /*
+         * 변환 이벤트만 읽는다. **최신부터** 읽는다 — 계보를 묻는 개체는 대개 최근에 만들어진 것이고,
+         * 창을 넘겨 잘릴 때 잃는 쪽이 오래된 것이어야 덜 아프다.
+         */
+        const rows = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).find({
+            where: { domain: { id: domainId }, instanceId, eventType: 'epcis.TransformationEvent' },
+            order: { eventTime: 'DESC' },
+            take: windowCap
+        });
+        const truncated = rows.length >= windowCap;
+        /* 산출 → 그 변환. 한 개체는 한 번만 만들어지지만, 데이터가 그렇지 않을 수 있으므로 목록으로 든다. */
+        const madeBy = new Map();
+        for (const r of rows) {
+            const d = r.payload?.data ?? {};
+            const outs = d.outputEPCList ?? [];
+            const ins = d.inputEPCList ?? [];
+            const step = { inputs: ins, at: r.eventTime, tx: d.bizTransactionList?.[0]?.bizTransaction };
+            for (const o of outs) {
+                const list = madeBy.get(o) ?? [];
+                list.push(step);
+                madeBy.set(o, list);
+            }
+        }
+        /* 거슬러 올라간다 — 너비 우선, 지나온 것은 다시 파지 않는다(사이클·공유 부품). */
+        const items = [{ epc, itemRef: itemRefOf(epc), depth: 0 }];
+        const edges = [];
+        const seen = new Set([epc]);
+        let depthTruncated = false;
+        let frontier = [{ epc, depth: 0 }];
+        while (frontier.length) {
+            const next = [];
+            for (const cur of frontier) {
+                if (cur.depth >= depthCap) {
+                    depthTruncated = true;
+                    continue;
+                }
+                for (const step of madeBy.get(cur.epc) ?? []) {
+                    for (const input of step.inputs) {
+                        edges.push({ from: cur.epc, to: input, at: step.at, tx: step.tx, depth: cur.depth + 1 });
+                        if (seen.has(input))
+                            continue;
+                        seen.add(input);
+                        items.push({ epc: input, itemRef: itemRefOf(input), depth: cur.depth + 1 });
+                        next.push({ epc: input, depth: cur.depth + 1 });
+                    }
+                }
+            }
+            frontier = next;
+        }
+        /*
+         * **겹쳐 본다.** 이 개체의 품목이 어느 레시피의 산출이면, 그 레시피가 선언한 투입과 실제로
+         * 소비된 것을 자재별로 나란히 센다.
+         *
+         * 개체(EPC)와 자재 키를 잇는 것은 `productionSpec.binding`(자재 키 → GS1 품목 참조)이다.
+         * 바인딩이 없으면 **비교하지 않는다** — 짐작으로 이으면 "설계와 다르다" 는 거짓 진단이 나오고,
+         * 그건 아무 말도 안 하는 것보다 나쁘다.
+         */
+        const spec = inst.model?.productionSpec;
+        const binding = spec?.binding ?? {};
+        const refToMaterial = new Map(Object.entries(binding).map(([mat, ref]) => [String(ref), mat]));
+        const materialOf = (e) => {
+            const ref = itemRefOf(e);
+            return ref ? refToMaterial.get(ref) ?? null : null;
+        };
+        const myMaterial = materialOf(epc);
+        const recipes = spec?.definition?.recipes ?? [];
+        const recipe = myMaterial ? recipes.find((r) => (r.outputs ?? []).some((o) => o.material === myMaterial)) : undefined;
+        let conformance = null;
+        if (!Object.keys(binding).length) {
+            conformance = { comparable: false, reason: 'no-binding' };
+        }
+        else if (!myMaterial) {
+            conformance = { comparable: false, reason: 'item-not-bound' };
+        }
+        else if (!recipe) {
+            conformance = { comparable: false, reason: 'no-recipe-for-material' };
+        }
+        else {
+            /*
+             * 관측: **바인딩된 자재까지 내려가 센다** — 중간 산물(WIP)은 통과한다.
+             *
+             * 다단 라인에서 완제품의 직접 투입은 원자재가 아니라 **WIP** 다: 원자재는 첫 공정에서
+             * 소비되고 완제품은 마지막 공정에서 나온다. 그래서 직접 투입만 세면 레시피가 선언한 자재와
+             * **영원히 안 맞는다**(검사가 이것을 잡았다).
+             *
+             * WIP 은 라우트의 내부 산물이고 선언된 자재가 아니다 — 레시피는 자재로 말하므로 비교도
+             * 자재로 해야 한다. 바인딩에 있으면 거기서 멈추고, 없으면 그 위로 계속 따라간다.
+             *
+             * 다만 **다른 완제품까지 넘어가지 않는다**: 바인딩된 것을 만나면 멈추므로, 하위조립도
+             * 자재로 선언돼 있으면 그 자리에서 세어진다(그 아래는 그 자재 자신의 레시피가 볼 일이다).
+             */
+            const observed = new Map();
+            let unbound = 0;
+            const parentsOf = (e) => edges.filter(x => x.from === e).map(x => x.to);
+            const walked = new Set([epc]);
+            let layer = parentsOf(epc);
+            while (layer.length) {
+                const deeper = [];
+                for (const e of layer) {
+                    if (walked.has(e))
+                        continue;
+                    walked.add(e);
+                    const mat = materialOf(e);
+                    if (mat) {
+                        observed.set(mat, (observed.get(mat) ?? 0) + 1);
+                        continue;
+                    }
+                    const up = parentsOf(e);
+                    /* 바인딩에도 없고 더 올라갈 곳도 없다 — 정말 모르는 투입이다(수만 낸다). */
+                    if (!up.length) {
+                        unbound++;
+                        continue;
+                    }
+                    deeper.push(...up);
+                }
+                layer = deeper;
+            }
+            const declared = new Map((recipe.inputs ?? []).map((i) => [i.material, i.qty ?? null]));
+            const keys = [...new Set([...declared.keys(), ...observed.keys()])];
+            conformance = {
+                comparable: true,
+                material: myMaterial,
+                recipe: recipe.key,
+                /* 자재마다 선언·관측을 나란히. 어느 한쪽에만 있는 것도 사실이다(빠뜨리지 않는다). */
+                lines: keys.map(m => ({
+                    material: m,
+                    declared: declared.has(m) ? declared.get(m) : null,
+                    observed: observed.get(m) ?? 0,
+                    matches: declared.get(m) === (observed.get(m) ?? 0)
+                })),
+                /* 바인딩에 없는 투입 — 설계에 없는 것이 들어갔을 수도, 바인딩이 덜 선언됐을 수도 있다.
+                   어느 쪽인지 우리는 모르므로 **수만 낸다.** */
+                unboundInputs: unbound
+            };
+        }
+        return {
+            instanceId,
+            epc,
+            itemRef: itemRefOf(epc),
+            material: myMaterial,
+            items,
+            edges,
+            conformance,
+            /* 무엇을 근거로 답했나 — 창을 넘겨 끊겼으면 계보가 실제보다 얕게 보인다. */
+            basis: { source: 'journal', transformationsRead: rows.length, truncated, depthTruncated, depthCap, windowCap }
+        };
+    }
+};
+exports.TwinLineageQuery = TwinLineageQuery;
+tslib_1.__decorate([
+    (0, type_graphql_1.Query)(returns => shell_1.ScalarObject, {
+        nullable: true,
+        description: 'Where one item came from (observed) laid next to what its type declares (BOM). Walks TransformationEvent input/output lists in the journal; reports the window it read and whether it was truncated. The declared|observed difference is the diagnosis: "the recipe says one frame, this one consumed two".'
+    }),
+    tslib_1.__param(0, (0, type_graphql_1.Arg)('instanceId')),
+    tslib_1.__param(1, (0, type_graphql_1.Arg)('epc')),
+    tslib_1.__param(2, (0, type_graphql_1.Ctx)()),
+    tslib_1.__param(3, (0, type_graphql_1.Arg)('maxDepth', type => type_graphql_1.Int, { nullable: true })),
+    tslib_1.__param(4, (0, type_graphql_1.Arg)('window', type => type_graphql_1.Int, { nullable: true })),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, String, Object, Number, Number]),
+    tslib_1.__metadata("design:returntype", Promise)
+], TwinLineageQuery.prototype, "twinItemLineage", null);
+exports.TwinLineageQuery = TwinLineageQuery = tslib_1.__decorate([
+    (0, type_graphql_1.Resolver)()
+], TwinLineageQuery);
+//# sourceMappingURL=twin-lineage-query.js.map

package/dist-server/service/twin-model/twin-lineage-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twin-lineage-query.js","sourceRoot":"","sources":["../../../server/service/twin-model/twin-lineage-query.ts"],"names":[],"mappings":"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","sourcesContent":["import { Arg, Ctx, Int, Query, Resolver } from 'type-graphql'\n\nimport { ScalarObject, getRepository } from '@things-factory/shell'\n\nimport { TwinInstance } from '../twin-instance/twin-instance.js'\nimport { TwinEvent } from '../twin-event/twin-event.js'\n\n/*\n * 계보 — **이 개체는 무엇에서 나왔나**, 그리고 **설계대로 만들어졌나.**\n *\n * ── 구성과 계보는 주어가 다르다 ────────────────────────────────────────────────\n * 구성(BOM)의 주어는 품목 **정의**다 — \"트레일러는 프레임 1개로 만든다\"(선언).\n * 계보의 주어는 품목 **개체**다 — \"이 트레일러는 저 프레임 로트에서 나왔다\"(관측).\n * 둘은 같은 모양이라 겹쳐 볼 수 있고, **그 차이가 곧 진단**이다: \"설계는 1개인데 이건 2개를 먹었다\".\n * 트윈이 아니면 못 하는 답이고, 이 질의가 그 답의 재료다.\n *\n * ── 어디서 읽나 ────────────────────────────────────────────────────────────────\n * 계보는 상태가 아니라 **저널**에 있다(EPCIS `TransformationEvent` 의 입력·산출 목록). 상태는\n * 지금 무엇이 있는지만 알고, 없어진 원자재가 무엇이었는지는 이벤트만 안다.\n *\n * ── 규모 ───────────────────────────────────────────────────────────────────────\n * 입력 목록은 **컬럼이 아니라 봉투 안**에 있어서 인덱스로 좁힐 수 없다. 그래서 변환 이벤트만\n * 창으로 끊어 읽고, **끊었으면 끊었다고 말한다.** 그 사실을 감추면 \"이 개체는 원자재가 없다\" 로\n * 읽히고, 계보에서 그 오해는 리콜 범위를 좁게 잡는 결과로 이어진다.\n */\n\n/** GS1 SGTIN 의 **품목 참조** — 개체(serial)를 떼고 품목만 남긴다(`…sgtin:0614141.077101.42` → `077101`). */\nfunction itemRefOf(epc: string): string | null {\n  const m = /sgtin:[^.]+\\.([^.]+)\\./.exec(epc)\n  return m ? m[1] : null\n}\n\n@Resolver()\nexport class TwinLineageQuery {\n  @Query(returns => ScalarObject, {\n    nullable: true,\n    description:\n      'Where one item came from (observed) laid next to what its type declares (BOM). Walks TransformationEvent input/output lists in the journal; reports the window it read and whether it was truncated. The declared|observed difference is the diagnosis: \"the recipe says one frame, this one consumed two\".'\n  })\n  async twinItemLineage(\n    @Arg('instanceId') instanceId: string,\n    @Arg('epc') epc: string,\n    @Ctx() context: ResolverContext,\n    @Arg('maxDepth', type => Int, { nullable: true }) maxDepth?: number,\n    @Arg('window', type => Int, { nullable: true }) window?: number\n  ): Promise<any | null> {\n    const domainId = context.state.domain.id\n    const inst = await getRepository(TwinInstance).findOne({ where: { domain: { id: domainId }, instanceId } })\n    if (!inst) return null\n\n    const depthCap = Math.min(Math.max(maxDepth ?? 6, 1), 12)\n    const windowCap = Math.min(Math.max(window ?? 5000, 1), 50000)\n\n    /*\n     * 변환 이벤트만 읽는다. **최신부터** 읽는다 — 계보를 묻는 개체는 대개 최근에 만들어진 것이고,\n     * 창을 넘겨 잘릴 때 잃는 쪽이 오래된 것이어야 덜 아프다.\n     */\n    const rows: any[] = await getRepository(TwinEvent).find({\n      where: { domain: { id: domainId } as any, instanceId, eventType: 'epcis.TransformationEvent' } as any,\n      order: { eventTime: 'DESC' } as any,\n      take: windowCap\n    })\n    const truncated = rows.length >= windowCap\n\n    /* 산출 → 그 변환. 한 개체는 한 번만 만들어지지만, 데이터가 그렇지 않을 수 있으므로 목록으로 든다. */\n    const madeBy = new Map<string, { inputs: string[]; at?: string; tx?: string }[]>()\n    for (const r of rows) {\n      const d = r.payload?.data ?? {}\n      const outs: string[] = d.outputEPCList ?? []\n      const ins: string[] = d.inputEPCList ?? []\n      const step = { inputs: ins, at: r.eventTime, tx: d.bizTransactionList?.[0]?.bizTransaction }\n      for (const o of outs) {\n        const list = madeBy.get(o) ?? []\n        list.push(step)\n        madeBy.set(o, list)\n      }\n    }\n\n    /* 거슬러 올라간다 — 너비 우선, 지나온 것은 다시 파지 않는다(사이클·공유 부품). */\n    const items: any[] = [{ epc, itemRef: itemRefOf(epc), depth: 0 }]\n    const edges: any[] = []\n    const seen = new Set<string>([epc])\n    let depthTruncated = false\n    let frontier = [{ epc, depth: 0 }]\n    while (frontier.length) {\n      const next: typeof frontier = []\n      for (const cur of frontier) {\n        if (cur.depth >= depthCap) { depthTruncated = true; continue }\n        for (const step of madeBy.get(cur.epc) ?? []) {\n          for (const input of step.inputs) {\n            edges.push({ from: cur.epc, to: input, at: step.at, tx: step.tx, depth: cur.depth + 1 })\n            if (seen.has(input)) continue\n            seen.add(input)\n            items.push({ epc: input, itemRef: itemRefOf(input), depth: cur.depth + 1 })\n            next.push({ epc: input, depth: cur.depth + 1 })\n          }\n        }\n      }\n      frontier = next\n    }\n\n    /*\n     * **겹쳐 본다.** 이 개체의 품목이 어느 레시피의 산출이면, 그 레시피가 선언한 투입과 실제로\n     * 소비된 것을 자재별로 나란히 센다.\n     *\n     * 개체(EPC)와 자재 키를 잇는 것은 `productionSpec.binding`(자재 키 → GS1 품목 참조)이다.\n     * 바인딩이 없으면 **비교하지 않는다** — 짐작으로 이으면 \"설계와 다르다\" 는 거짓 진단이 나오고,\n     * 그건 아무 말도 안 하는 것보다 나쁘다.\n     */\n    const spec: any = (inst.model as any)?.productionSpec\n    const binding: Record<string, string> = spec?.binding ?? {}\n    const refToMaterial = new Map(Object.entries(binding).map(([mat, ref]) => [String(ref), mat]))\n    const materialOf = (e: string) => {\n      const ref = itemRefOf(e)\n      return ref ? refToMaterial.get(ref) ?? null : null\n    }\n\n    const myMaterial = materialOf(epc)\n    const recipes: any[] = spec?.definition?.recipes ?? []\n    const recipe = myMaterial ? recipes.find((r: any) => (r.outputs ?? []).some((o: any) => o.material === myMaterial)) : undefined\n\n    let conformance: any = null\n    if (!Object.keys(binding).length) {\n      conformance = { comparable: false, reason: 'no-binding' }\n    } else if (!myMaterial) {\n      conformance = { comparable: false, reason: 'item-not-bound' }\n    } else if (!recipe) {\n      conformance = { comparable: false, reason: 'no-recipe-for-material' }\n    } else {\n      /*\n       * 관측: **바인딩된 자재까지 내려가 센다** — 중간 산물(WIP)은 통과한다.\n       *\n       * 다단 라인에서 완제품의 직접 투입은 원자재가 아니라 **WIP** 다: 원자재는 첫 공정에서\n       * 소비되고 완제품은 마지막 공정에서 나온다. 그래서 직접 투입만 세면 레시피가 선언한 자재와\n       * **영원히 안 맞는다**(검사가 이것을 잡았다).\n       *\n       * WIP 은 라우트의 내부 산물이고 선언된 자재가 아니다 — 레시피는 자재로 말하므로 비교도\n       * 자재로 해야 한다. 바인딩에 있으면 거기서 멈추고, 없으면 그 위로 계속 따라간다.\n       *\n       * 다만 **다른 완제품까지 넘어가지 않는다**: 바인딩된 것을 만나면 멈추므로, 하위조립도\n       * 자재로 선언돼 있으면 그 자리에서 세어진다(그 아래는 그 자재 자신의 레시피가 볼 일이다).\n       */\n      const observed = new Map<string, number>()\n      let unbound = 0\n      const parentsOf = (e: string) => edges.filter(x => x.from === e).map(x => x.to)\n      const walked = new Set<string>([epc])\n      let layer = parentsOf(epc)\n      while (layer.length) {\n        const deeper: string[] = []\n        for (const e of layer) {\n          if (walked.has(e)) continue\n          walked.add(e)\n          const mat = materialOf(e)\n          if (mat) { observed.set(mat, (observed.get(mat) ?? 0) + 1); continue }\n          const up = parentsOf(e)\n          /* 바인딩에도 없고 더 올라갈 곳도 없다 — 정말 모르는 투입이다(수만 낸다). */\n          if (!up.length) { unbound++; continue }\n          deeper.push(...up)\n        }\n        layer = deeper\n      }\n      const declared = new Map<string, number>((recipe.inputs ?? []).map((i: any) => [i.material, i.qty ?? null]))\n      const keys = [...new Set([...declared.keys(), ...observed.keys()])]\n      conformance = {\n        comparable: true,\n        material: myMaterial,\n        recipe: recipe.key,\n        /* 자재마다 선언·관측을 나란히. 어느 한쪽에만 있는 것도 사실이다(빠뜨리지 않는다). */\n        lines: keys.map(m => ({\n          material: m,\n          declared: declared.has(m) ? declared.get(m) : null,\n          observed: observed.get(m) ?? 0,\n          matches: declared.get(m) === (observed.get(m) ?? 0)\n        })),\n        /* 바인딩에 없는 투입 — 설계에 없는 것이 들어갔을 수도, 바인딩이 덜 선언됐을 수도 있다.\n           어느 쪽인지 우리는 모르므로 **수만 낸다.** */\n        unboundInputs: unbound\n      }\n    }\n\n    return {\n      instanceId,\n      epc,\n      itemRef: itemRefOf(epc),\n      material: myMaterial,\n      items,\n      edges,\n      conformance,\n      /* 무엇을 근거로 답했나 — 창을 넘겨 끊겼으면 계보가 실제보다 얕게 보인다. */\n      basis: { source: 'journal', transformationsRead: rows.length, truncated, depthTruncated, depthCap, windowCap }\n    }\n  }\n}\n"]}

package/dist-server/service/twin-model/twin-location.d.ts

@@ -0,0 +1,58 @@
+import { Domain } from '@things-factory/shell';
+import { TwinInstance } from '../twin-instance/twin-instance.js';
+import { TwinArea } from '../twin-space/twin-area.js';
+export declare class TwinLocation {
+    readonly id: string;
+    domain?: Domain;
+    domainId?: string;
+    instance?: TwinInstance;
+    instanceRowId?: string;
+    /** 커널 계약의 `TwinModelDef.locations[].id` **그대로**. 바인딩은 id===id 다(ADR-0014). */
+    locationId: string;
+    /**
+     * **사람이 부르는 이름** — 프레임워크 엔티티 규약의 `name`/`description`.
+     *
+     * ── 왜 이것이 빠져 있었고, 무엇이 망가졌나 ────────────────────────────────────
+     * 투영이 마스터의 `name` 을 버리고 있었다. 그래서 행에는 id 만 남고, 화면은 이름을 만들 재료가
+     * 없어 `cut-station` 을 그대로 찍었다 — 그 결함이 목록·표·관계 그림마다 따로 나타나서 표면을
+     * 하나씩 고치게 만들었다. 표면의 문제가 아니라 **행에 이름이 없던 문제**다.
+     *
+     * 원본이 이름을 말하지 않으면 비운다(id 를 이름으로 베끼지 않는다 — 그러면 "이름이 있다" 는
+     * 거짓이 되고, 화면이 이름 없음을 알아볼 수 없게 된다).
+     */
+    name?: string;
+    description?: string;
+    /**
+     * 커널 카탈로그의 자리 타입 키(`storage`·`dock`·`yard-slot`…).
+     *
+     * **FK 를 걸지 않는다** — 타입 카탈로그는 커널이 SSOT 이고(ADR-0018) DB 로 내리면
+     * **커널 어휘의 사본**이 생긴다. 문자열 + 부팅 시 검증이 맞다(ADR-0032-F).
+     */
+    type: string;
+    capacity?: number;
+    parallelism?: number;
+    /**
+     * 속한 구역 — **실제 FK**.
+     *
+     * 커널 계약에서는 `locations[].parentId` 가 model 안에 대상이 없는 참조였다(마스터에서 구역도
+     * 자리와 한 목록이었다가 인제스트가 갈라 `TwinArea` 로 보내기 때문). 커널은 그것을
+     * `external: 'space.area'` 로 선언했고, **호스트에서는 평범한 FK 가 된다.**
+     */
+    area?: TwinArea;
+    areaRowId?: string;
+    /** GS1 식별자(SGLN 등) — 원본이 주면 싣는다. */
+    gs1Id?: string;
+    /**
+     * 이 자리의 **선언 속성** — 계약전력·요금 단가처럼 자리에 얹히는 수(ISA-95 Property).
+     *
+     * ── 왜 늦게 생겼나 (2026-08-18) ────────────────────────────────────────────
+     * 설비 행에는 이 칸이 있었는데 자리 행에는 없었다. 그래서 수전 지점에 계약전력·요금을 넣어도 **항목
+     * 패널의 「원본이 말한 값」에 그 줄이 아예 없었다** — 사용자는 값을 넣고도 화면에서 찾을 수 없었고,
+     * 「이 값이 무엇을 바꾸나」는 문장도 붙을 자리가 없었다(조용한 누락).
+     */
+    properties?: any;
+    sourceRef: string;
+    ingestedAt: Date;
+    createdAt?: Date;
+    updatedAt?: Date;
+}